InSitu

Setup guide
InSitu can be used in a few different ways for web site development. It can be used to add editing functionality to an existing web site without investing a lot of time and/or money needed to install a CMS. Or you can use InSitu to speed up the development of a new web site that requires editing capabilities. Whatever situation you are in, the approach to setup InSitu is basically the same.

Templates
The first thing you need to think about is what pages and which parts of each page you want to be editable. It is oftenly a good idea to limit the possibilities for editing as much as possible.

If you're migrating an existing web application, hopefully you will find that the HTML pages it consists of are similar. Similar pages can be reduced to a single template. If they are similar in such a way that the only parts that change between one page and another are the same parts that are editable then all those pages can be generated using one template. To create a template, copy one of the pages to the \bw\templates folder and remove the content in it. The reference implementation of Insitu that you've downloaded only uses two templates. You can find them in the directory mentioned above.

If you cannot see any similarities in the HTML code of the web application that you're migrating. You should probably consider a redesign or else look for another tool (with layout capabilites such as DreamWeaver or FrontPage).

If you're creating a new web site you should make as many templates as you need for your web site and use InSitu to add content. This way, you won't have to copy and paste the same HTML code into several files.

Adding InSitu tags to a template
InSitu reads InSitu tags (HTML comments) from the HTML code in each page. An Insitu tag tells the InSitu scripts how to create the form used for editing, but since it is embedded in a HTML comment it is never displayed to the user and it doesn't affect the layout of your pages.

InSitu tags
There are six different InSitu tags: string, text, link, image, element and iterator. They all work pretty much the same and the best way to learn how to use them is to create a template and experiment with them.

The general inSitu tag syntax is as follows: CONTENT

ID is a unique (iterator/page scope) identifier for the element and TYPE specifies one of the six available tags. A string is converted into a input type="text" form element and text is converted into a textarea. Link, image and element types are represented by several input type="text" fields. An iterator is used to create or remove a set of input fields that are grouped together (for example a paragraph
that has a headline, an image and some text).

String and Text syntax
CONTENT

CONTENT

String and text tags are quite straight forward. There are only two/three things that can be set: caption (which is displayed above the input field in the HTML form on the admin page) and size (for string) or cols and rows (for text). Size, cols and rows are transfered directly to the resulting HTML form element.

Examples:

Lorem ipsum dolores sit amet,

consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.

Element, Image and Link syntax
<ELEMENT ATTR0="VALUE" .. ATTRn="VALUE">Lorem ipsum</ELEMENT>

Element, image and link tags are considered the same. Image and link was added to increase readability. An element tag have at least two attributes that can be set: caption, which works the same way as it does for string and text tags and show. Show attribute is used to define (with a comma separated list) which of the attributes
in the element that should be editable.

Please note that if you use, for example, the following: show="src, alt" you must also provide a src and a alt attribute in the ELEMENT, otherwise you will be able to edit it but nothing will happen with the resulting page.

For each of the attributes you specify within show, you can restrict their values by adding it as an attribute and specify the values it can have. You can specify an attributes value in two different ways: write the allowed values directly in a comma separated list (which is shown as a drop-down list in the admin page) or refer to a properties file (see below). Attributes that are not restricted are given an input
type="text" field in the HTML form.

Examples:

<title>Lorem ipsum</title>

<img src="screenshot.gif" alt="Screenshot" align="left" />

<a href="http://www.pulp.se" title="Go to www.pulp.se">www.pulp.se</a>

Iterator syntax
CONTENT

An iterator is placed around other tags that you wish to group together. The iterator is displayed as a 1 px box around these elements with two links (above the top left corner) for adding and removing a set of tags. There are two attributes that can be set: caption and id. Caption is displayed in the links for adding and removing the iterator block as "delete CAPTION, add CAPTION". Id should always be set to a number (use 0). InSitu gives a random id to each of the iterator blocks that are created.

Example:



<span class="headline">Pulp</span>

You can get more information at the InSItu web page at <a href="http://www.pulp.se">www.pulp.se</a><br /><br />



Property files
You can use property files to specify valid values for an attribute in an element. A property file can contain comments. A comment line must start with #, everything on that line behind the # is ignored. If # is not the first character on the line, it's not a comment.

A property file can contain a redirect command (>>>) which is interpreted using five attributes: dir, file, prefix, suffix, filter. Filter is used to filter out content from a directory. Specifying filter=".jpg" shows only JPEG files in the resulting dropdown list. Prefix and suffix attributes are used to add text before and after each value that
is read from the directory or file. Dir and file attributes are used to specify from where values should be read. By specifying a directory you read the contents (files) from that directory, by specifying a file each line in that file becomes a value in the resulting dropdown list.

Example:

image.properties
# get content from \images\
>>> dir= "\images\" prefix="/images/" suffix="" filter="gif"

Site properties
By now, you should have a web site ready. It probably contains a couple of templates with a few InSitu tags. The next thing you need to do to get InSitu to work properly is to edit the site properties. In the \cgi-bin folder there is a file called insitu.properties. Open it and change the values to match your web site. Please note that both the root directory and the root url MUST end with a \ and a / and that the
root url MUST NOT have a document part specified.

Edit /admin/index.shtml
There is a javascript-reload in the file /admin/index.shtml that needs to be changed to point to whatever page in your web site that you want the user to start at when using InSitu.

If you've done all the things mentioned above, you should have a working installation of your web site up and running by now. Feel free to adjust the look and feel of the InSitu pages so that they better meet your needs.