Intro#

This document is meant for designers working as part of a team that is building a web application that uses RSF for its presentation layer. It assumes comfort with HTML, CSS, file systems, Dreamweaver a plus. It assumes that the initial "design" is pretty much set and deals mostly with the mechanics on how to produce RSF templates that will make your colleagues smile.

To keep it simple - only markup will be dealt with - no behaviours, AJAX, etc.

1. First part will explain how things work, best practices.
2. Second part will go over creating templates with Dreamweaver and a Dreamweaver library. This last part is focused mainly on Sakai rendering idioms.
3. Third and last will aggregate tips, ruminations, notes on aspects of the whole process.

1 - Working with RSF #

RSF is a pure HTML templating system. This means that the markup you create ends up being the bones of the presentation layer of the application - putting you in total control of it.

Lets take a look at an example. This is a simple table that you can preview in the browser. You have written it, populated it with plausible content, tested it with users, edited it, etc. The only odd thing about it is the rsf:id attributes. These have the following purposes:

Line 7: <span rsf:id="headertitle1">Header title 1</span> - this is a leaf node. The value inside the <span /> will be substituted by a value determined by the rsf:id
Line 15: <tr rsf:id="row:"> - this is a branch, in this case indicating an iteration - the values of the children will be determined by the branch logic - it will cycle through all the items this table represents, and determine for the first cell/img if there is an attachment involved (and render a paperclip), for the second cell/span the name of the item (and render that), for the last cell/a if the user has the right to edit it (in which case she will get a link).

And that is it. There are some subtleties but we will cover these later.

1. <table rsf:id="tableFlat:" class="tableFlat" summary="Descriptive data table summary">
2. <caption rsf:id="caption">Caption</caption>
3. <thead>
4. <tr>
5. <th class="attach" id="attach"> </th>
6. <th id="id1">
7. <span rsf:id="headertitle1">Header title 1</span>
8. </th>
9. <th id="id2">
10. <span rsf:id="headertitle2">Header title 2</span>
11. </th>
12. </tr>
13. </thead>
14. <tbody>
15. <tr rsf:id="row:">
16. <td headers="attach" class="attach">
17. <img rsf:id="paperclip" src="library/images/sakai/attachments.gif" alt="Attachments" />
18. </td>
19. <td headers="id1">
20. <span rsf:id="cellcontents">Cell contents</span>
21. </td>
22. <td headers="id2">
23. <a rsf:id="item-modify" href="modify.html">Edit</a>
24. </td>
25. </tr>
26. <tr rsf:id="row:">
27. <td headers="attach" class="attach">
28. <img rsf:id="paperclip" src="library/images/sakai/attachments.gif" alt="Attachments" />
29. </td>
30. <td headers="id1">
31. <span rsf:id="cellcontents">Cell contents</span>
32. </td>
33. <td headers="id2">
34. <a rsf:id="item-modify" href="modify.html">Edit</a>
35. </td>
36. </tr>
37. <tr rsf:id="row:">
38. <td headers="attach" class="attach">
39. <img rsf:id="rsf-id-paperclip" src="library/images/sakai/attachments.gif" alt="Attachments" />
40. </td>
41. <td headers="id1">
42. <span rsf:id="cellcontents">Cell contents</span>
43. </td>
44. <td headers="id2">
45. <a rsf:id="item-modify" href="modify.html">Edit</a>
46. </td>
47. </tr>
48. </tbody>
49. </table>

}

Recommended procedures#

Regardless of how you create your markup - here are some guidelines:

write them as you see them #

Write your template so as to account for all the possible variables once it is running in the application. Although a table only needs one row (<tr>) branch to run correctly (iterate over all the members of the list and create as many rows, for example), you might want to put in 10 of them to see how it looks. The application will ignore the extras but having your template fully populated will help you visualize it.

comment lavishly#

Despite the fact that RSF templates are pretty much the presentation layer of the application, comments are needed to provide guidance to the developers. You might want to add an identifying word to your comments so that you can remove them after a testing phase is complete. Comment everything, early and often!

For example. Assume that a view has a table. If there are no items you do not want any part of the table to show. Instead you want to render a status message. Comments will help developers make sure that is what happens:

1. <!-- designNote: message below gets rendered if there are no items for tableFlat:-->
2. <p rsf:id="emptylistmessage" class="messageInstruction">A helpful status message</p>
3. <!-- designNote: table below only gets rendered if there is one item or more -->
4. <table rsf:id="tableFlat:" class="tableFlat" summary="Descriptive data table summary">
5. . . . . . . .
6. </table>

}

use real links#

1. <a rsf:id="add_new_item" href="add_new_item.html" >Add new item </p>

} Clicking on this link will take you to that view template. This useful for user testing, and for indicating what should happen to the developer.

using rsf:ids #

This is a bit more complex. In fact - you might negotiate with the developers that you will not be adding rsf:ids at all. They will rely on your lavish comments and your crystal clear documentation to figure these out. If this is so - comment! And if you are using the Dreamweaver library - remove all the stub rsf:ids from the templates.

But if not - here are some guidelines.

• Put rsf-id first: make the rsf:id the first attribute of the element - this helps developers scan your template
• Be meaningful: give the rsf:id a meaningful name that presages what should happen when the producer gets ahold of it and the nature of whatever gets sent to the browser.
• Be consistent: stick to the same naming convention for rsf:ids (another negotiation with developers might be needed here: camelCase, under_score, dash-madness, etc.).
• Be logical: make rsf:id reflect the logic of the view -

basically our choices are branch (rsf:id="rsf-id:") or leaf (rsf:id="rsf-id") If your markup cannot express what it should in the application - you are dealing with a branch. A branch indicates 1) a fork in the display (render this or render that); or 2) a repetition (render as many of these as there are); or 3) a hierarchy - a good example of this would be a categorized listing with multiple nesting levels. An element of each level is determined by the parent, and in turn it determines it's children.

A leaf represents just a one to one value.

• Be prepared: think of your page as an application with dynamic content and behaviours. If you take a look at the markup for the table above you will notice:

1. <td headers="id1">
2. <span rsf:id="cellcontents">Cell contents</span>
3. </td>

} The rsf:id could have been an attribute of the cell and it would have been much more economical. But since we have no assurance that there will be a value for that rsf:id we associate it with a <span /> so that the cell gets rendered in any case, otherwise we might get a column shift in that row.

• Be multilingual: Add all values of rsf:ids that resolve to literals to a myappname.properties file - this is icing on the cake and will really help when you localize your application for other languages and make the language of your application consistent.

So - for example, the markup

1. <h3 rsf:id="msg=page_title">A title </h3>

Means that the application will look up myappname.properties (sample below) the value of "page_title" and use it to substitute the words "A title" with "A title", "Un título", "Un titre" etc., depending on the language of the user.

1. page_title=A title
2. table_caption=Table caption
3. table_subject_header=Subject
4. . . . . . . . .

} This is all about speeding things up and maintaining control of the presentation layer. Structure myappname.properties by groups of entries, each group representing a particular view's entries. If some literals are common to the whole application - group them together as a first group and use them in your templates religiously (instant consistency! just add property file!). For example:

("common" below should have a hashmark octothorpe pound sign to denote it is a comment - but in this wiki it is used to denote a list item)
common
item=Item
save=Save
cancel=Cancel
edit=Edit
. . . . . . . .
("list of items view" below should have a hashmark octothorpe pound sign to denote it is a comment - but in this wiki it is used to denote a list item)
list of items view
page_title=List of items
table_caption=List items. Column 1 indicates if there is an attachment, column 2 the item name, column 3 a link to edit item if allowed.
table_subject_header=Subject
. . . . . . . .
("edit item view" below should have a hashmark octothorpe pound sign to denote it is a comment - but in this wiki it is used to denote a list item)
edit item view
subject_input_label=Subject
. . . . . . . .

Note: if your strings are complex - that is - they consist of a literal and a variable - use a normal rsf:id and make sure that the comments and the model reflect this.

For example:

1. <!-- designNote: notice the model below for rsf:id value -->
2. <p rsf:id="view_x_of_y" class="instructionMessage instruction">Viewing 1-10 of 34 messages</p>

}

Format well#

Keeping to a consistent format for indentation will keep you and the developers from running melancholy mad, specially when things get complicated. Dreamweaver does this decently - it looks like: Command/Apply Source Formatting

Make well formed and valid#

Make sure it is well formed and valid XHTML. This will:

1. allow it to work as a template at all!
2. allow you to pinpoint rendering problems as browser deviations from the norm
3. make you feel very virtuous

Dreamweaver works here as well - or you can use some other tool you are comfortable with, even the W3C validation service - it will complain bitterly about the rsf:ids, so ignore those warnings but fix the rest.

2 - Creating the pages with Dreamweaver #

Setting up#

If you want to use the Dreamweaver library and snippet collection:

1. Download and unpack the library
2. Put Sakai snippets folder into snippet library - this will depend on system.

For Windows, it will be in: E:\Documents and Settings\(username)\Application Data\Macromedia\Dreamweaver 8\Configuration\Snippets

For OSX it will be: /Applications/Adobe Dreamweaver CS3/Configuration/Snippets

1. Put site stub (templates, CSS, javascript) where you keep these things. If you are reading this you already know more about Dreamweaver than I do, so you probably know where.

Doing it#

Again - it is assumed the initial design is done. The flow/navigation has been defined, the views sketched out a grosso modo. The sequence follows:

1. Designate a default view - this may be the initial view of the application, given the role and any other contextual information that applies.
2. Create a new page for this default view. If you are using the DW library this will be based on the sakai-generic.dwt template. This will create a stub with the right declarations and links to css files and so forth. The part you will add markup to will be:

1. <body>
2. <div class="portletBody">
3. - - - - - here! - - - - -
4. </div>
5. </body>

}

1. Save this page - giving it a very descriptive name
2. Start dragging and dropping elements of the clip library as needed into your page. Working in code view will give you better results as you will know exactly where you are dropping things.

As an example the page will have:

1. a menu so that people can navigate to a different view
2. a menu so that people can select actions to perform in the current view
3. a list where each item has 3 attributes, as well as a set of possible actions on each item

The names for these elements in the snippet library are:

1. navToolBar
2. actionToolBar
3. tableFlat

Each element will provide all the markup needed. Let's take a look.

The navigation toolbar (navToolBar)#

1. <ul rsf:id="navToolBar:" class="navToolBar">
2. <li rsf:id="rsf-id-stub:">
3. <a rsf:id="rsf-id-stub" href="#" title="title">Go somewhere</a>
4. <li rsf:id="rsf-id-stub:">
5. <a rsf:id="rsf-id-stub" href="#" title="title">Go there</a>
6. <li rsf:id="disabled" class="disabled">Disabled Destination
7. <li rsf:id="current" class="current">You are here
8. </ul>

}

The snippet assumes that the navigation toolbar should be a branch. The producer will generate everything inside of it. In this case your markup is two things: 1) a placeholder - something that allows you to preview how it will look, do some user testing, etc, and 2) an indication to the developers of what should be sent to the browser.
Here are the edits I would do on this generic snippet:

1. Change all the list items and links (and their attributes) to something that will make sense in this view in this application.
2. Remove all the rsf:ids that do not have a corresponding value
3. Change all the rsf:ids to something meaningful (this will help the developer)
4. Change the href attribute values so that the link is pointing at another template that represents what would happen when application is running. The "Edit this thing" link should point to "edit-thing.html" template, for example (this will help everyone)

The action toolbar presents the same set of choices, so will not deal with it, but here it is:

The action toolbar (actionToolBar)#

1. <ul rsf:id="actionToolBar:" class="actionToolBar">
2. <li rsf:id="rsf-id-stub:">
3. <a rsf:id="rsf-id-stub" href="#" title="title">Add New Item</a>
4. <li rsf:id="rsf-id-stub:">
5. <a rsf:id="rsf-id-stub" href="#" title="title">Add New folder</a>
6. <li rsf:id="disabled" class="disabled">Disabled Action
7. <li rsf:id="current" class="current">Current Action
8. </ul>

}

a list (tableFlat)#

1. <table rsf:id="tableFlat:" class="tableFlat" cellpadding="0" cellspacing="0" summary="Descriptive data table summary">
2. <caption rsf:id="rsf-id-stub" title="a title">
3. Caption
4. </caption>
5. <thead rsf:id="rsf-id-stub">
6. <tr rsf:id="rsf-id-stub:">
7. <th rsf:id="attach" id="attach" class="attach"> </th>
8. <th rsf:id="id1:" id="id1">
9. <a rsf:id="rsf-id-stub:" href="#" title="title">
10. <img rsf:id="rsf-id-stub" src="library/images/sakai/sortascending.gif" alt="alt" border="0" width="11" height="11"/>
11. Header title
12. </a>
13. </th>
14. <th rsf:id="id2:" id="id2">
15. <a rsf:id="rsf-id-stub:" href="#" title="title">
16. <img rsf:id="rsf-id-stub" src="library/images/sakai/sortascending.gif" alt="alt" border="0" width="11" height="11"/>
17. Header title
18. </a>
19. </th>
20. </tr>
21. </thead>
22. <tbody rsf:id="rsf-id-stub">
23. <tr rsf:id="rsf-id-stub:">
24. <td rsf:id="attach" headers="attach" class="attach"></td>
25. <td rsf:id="rsf-id-stub:" headers="id1">
26. <a rsf:id="rsf-id-stub" href="edit-thing.html" title="title"> Edit this thing</a>
27. </td>
28. <td rsf:id="rsf-id-stub" headers="id2">Cell contents</td>
29. </tr>
30. </tbody>
31. </table>

}

The markup above should be familiar - I have cut all data rows but one (all the backend producer needs in any case). Edits I would do:

1. Add/substract columns as needed
2. Edit the content - make it meaningful for the template as a standalone.
3. Change all the list items and links (and their attributes) to something that will make sense in this view in this application.
4. Make all ids unique
5. Change all the rsf:ids to something meaningful (this will help the developer)
6. Change the href attribute values so that the link is pointing at another template that represents what would happen when application is running. The "Edit this thing" link should point to "edit-thing.html" template, for example (this will help everyone)

Adjusting the markup#

Notice that the snippets include a lot of attribute placeholders. In the table above you will see a summary, a caption, header id and cell headers. The images have alt. The only placeholder attributes included in the snippets are the ones required to create minimally meaningful markup (mmm!) - there are many other possible attributes - these are your call and will depend on the context. For example: in a long list that repeats the "Edit" link - it could be argued that the <a> should include a title attribute that incorporates the name of the thing being edited, making each link distinct. Thus:

1. <a rsf:id="item-modify" href="modify.html" title="Edit (item name)" >Edit</a>

} Notice the lack of rsf:id for the title - this is because everything inside the <a> will be replaced at runtime. But the title attribute as written will notify the developers of your intentions.

Previewing it #

Save your file and preview in a browser. Now may also be a good time to apply formatting, validate.

More....#

Process#

I found myself following this process when building templates. This might work for you as well:

1. Create stub template on the basis of sakai-generic DW template
2. Populate with the snippets, in code view so I could see what I was doing
3. Adjust the content of the template in design view
4. Adjust the markup (non visible attributes, rsf:ids, comments, etc.) in code view
5. Apply source formatting
6. Preview and validate

On style#

Since the template links to external CSS files reference the files in the location where these in the Dreaweaver site, and will change to reference the location of the same in the server, this is going to really cramp your style once past the first iteration, as you will be getting the templates back with the new path.

You can ask that the <link /> elements be rsf:id'd. Then they will change from

1. <link href="/library/skin/tool_base.css" type="text/css" rel="stylesheet" media="all" />
2. <link href="/library/skin/default/tool.css" type="text/css" rel="stylesheet" media="all" />

} to

1. <link href="library/skin/tool_base.css" rsf:id="scr=portal-matter" type="text/css" rel="stylesheet" media="all" />
2. <link href="library/skin/default/tool.css" rsf:id="scr=portal-matter" type="text/css" rel="stylesheet" media="all" />

} notice the rsf:id="scr=portal-matter" - this will ensure that when running in the server it will point to the right files regardless of the value of the href attribute - which now can hold the values that will make these files work fine in the Dreamweaver milieu. Hoorah!

Doing Demos/Testing with your RSF templates#

You will probably want to use the same set of files to do testing and demos as you are using for the templates. A given single template will work to present complex flows - some parts will be rendered, others not, for example, or a list will be sorted with a click, etc. How to replicate this behaviour in static files?

One solution is to add this to the template with javascript. A better one is to duplicate the template, edit the new one to display the change and save it with the suffix "-demo" as well as edit the old one and create a link to the new one. The workflow will work (for demos and testing) and the developers will then know that this is an interim template that should be ignored.

See: this example - click on the "Search" button and you will get UBookBookAddbyISBN-d.html - which is the for demo variant of what the original template (UBookBookAddbyISBN.html) will do once it is running (the extras provided by UBookBookAddbyISBN-d.html also are in UBookBookAddbyISBN.html but commented out).