The ACS Templating System for Web Designers

Reading

• ACS Templating System documents
• Templating System demo
• Read beginning and end of Using Templates in ACS 4

Sections

1. Overview
2. Exercises

Overview

This series of exercises is meant as a learning tool for any web graphic designer wanting or needing to understand how the ACS Templating System, or ATS, works, and how to use it in building web pages.

First, perhaps an explanation of what the templating system does will help us understand how it works. An ATS template itself serves as a reusable, unchanging framework that delivers dynamic data. The advantage to this is something you probably already realize: you need only build and edit a few pages to maintain a consistent presentation style while accommodating numerous permutations of changing data.

This training module will teach largely by exercise and example, but you should also refer regularly to the ATS documents provided and more specific pointers will be given to help you out along the way.

Okay, let's get to the nitty gritty.

Exercises

The basic building block of dynamic data in a template is the onevalue variable. A variable is simply a tag used in your .adp file that holds data supplied by another source file; that source will probably be another file of the same name with a .tcl extension. Variable tags come in three basic formats, as lists, multiples and onevalues.

Exercise 1: Onevalues, onelists, multilists and multirows
(nestedlists, too?)

Let's first take a look at some list and variable tags in action. Open up another browser and look at this page, which is a text rendition of the /ats/doc/exercise/list-and-var-sample.tcl page we'll be sourcing our data from; at the top of the page you'll find a block of commented text describing the variables generated by this page, followed by the actual code itself. Now, using your preferred text editor, open the file list-and-var-sample.adp located in the same directory and compare the html script that you see there with the final user-viewed page, list-and-var-sample.acs. Almost every .acs page the user sees is supported by one .tcl file which supplies the data to be shown, and one .adp file specifying the format of its presentation. Compare what you see in list-and-var-sample.acs with its supporting .adp file and make note of the textual and structural differences between the two, specifically:

• variables in the .adp file are designated with "@" markers, like the @name@ variable that litters the opening text block of list-and-var-sample.adp; here, @name@ is used as a place-marker for the value set in list-and-var.sample.tcl
• the variables within the <multiple> tag, though only appearing once in the .adp file, are cycled repeatedly to show multiple sets of information when displayed in list-and-var-sample.acs; example:

      <multiple name="your_multirow">
      <tr><td>@your_multirow.first_names@ @your_multirow.last_name@ </td> </tr>
      </multiple>
      

  The user will see one table row filled with a different person's name for each row contained in the multirow your_multirow.
• multirow variables are identified with this format: @<name of the multirow>.<name of a field in the multirow>@, and can only be called within their respective <multiple> tags

You probably noticed some other funky looking tags, too, but ignore those for now.

Now since the variable marker @name@ is set in list-and-var-sample.tcl, you can go ahead and edit that file to replace "(Your Name)" with whatever your name really is (be sure to leave the quotes); if you wish,edit some of the other values to personalize the page. You'll see your changes take effect upon saving the .tcl file and reloading list-and-var-sample.acs. In general, though, you should probably not be editing .tcl files unless you have a pretty good sense of their innerworkings.

Okay, now go back to the web browser in which you are viewing list-and-var-sample.acs and change the ".acs" extension to ".dat". This page displays a view of datasources generated in the .tcl file that can be used in your .adp template (actually, the information is generated from commented text parsed from the top of the .tcl file, so you can view this information in either the .dat page or straight from the .tcl file). Go ahead and make use of the datasource variables not already included in the .adp file; specifically, change list-and-var-sample.adp so that:

• your personal phone number information is included
• each of your friends' names serves as a hyperlink that allows the viewer to email your friend
• a listing of recently watched movies and your reactions to them follows after the information about your friends
• also, note that the use of any variable tags referring to variables not declared in the .tcl file will break the .acs page

Congratulations! You've just created a personalized web page describing friends you've never met and movies you've possibly never seen.

Exercise Two: <if> and <else>, the conditional tags

Dynamic data implies a changing page, and also changing presentation. The <if> and <else> tags allow you to alter the format of your page to accommodate data changes. The function of <if> is straightforward enough: given a condition -- such as @x@ equals 5 -- all the text/html/dynamic data between the opening and closing <if> tags will be displayed if and only if @x@ does in fact equal 5. A complete listing of currently supported conditions and some brief explanatory notes can be found here. Also, a few more things to keep in mind:

• in Tcl all variables, even numbers, are stored as text strings with quantitative values, so conditions like less than, greater than, and (not) between can also be used with text to determine alphabetical order: a < b < ... < z, lowercase letters are greater than uppercase, and numbers less than letters. Example: "you" are greater than "me", and "I" am less than "you"
• the "between" conditions checks inclusively, so <if 2 between 2 6> will test true
• <if @a@ between @b@ @c@> requires that @a@ is greater than or equal to @b@ and less than or equal to @c@; so <if @x@ between 4 2> will always test false
• the "in" condition uses a regular expression check (or will it? come back here and revise)

Now, alter a few of the <if> tags in list-and-var-samle.adp and add a few of your own. Specifically, add one <if> and <else> combination so that the friend description reads "likes chocolate" when likes_chocolate_p is "t", "doesn't like chocolate" when likes_chocolate_p is "f", or "probably like chocolate" if likes_chocolate_p is an empty string. Also, add one <if>, and one <if> only, so that a is appropriately changed to an for any 11-, 18- or 80- to 89-year olds.

Exercise Three: The <master> and <slave> tags -- a call to the dominatrix in you

The <master> and <slave> tags allow you to maintain a consistent style and format among pages without having to edit each page individually. To get a sense of what these tags do and how they work, go ahead and run through this short demonstration, and then use a text editor to view the related .adp files. Also, read this discussion on the use of master pages.

One thing you may have noticed earlier about list-and-var-sample.adp is that it lacks the standard <html>, <head>, <title> and <body> tags. This is because list-and-var-sample.adp is, as indicated by the <master> tag at the top of the file, also a slave section, contained within master-sample.adp.

Let me stress a few key points you might have already picked up on from the demonstration and upon examining the .adp files, and add a few pointers:

• the <slave> tag indicates where on the master page the slave section is inserted
• slave pages indicate the source of the master file with the <master> tag, referring by the filename only, and not including its ".adp" extension
• as mentioned earlier, slave sections do not require <html>, <head>, and <body> tags when contained within a master tag already formatted for HTML
• as the demonstration points out, pages are browsed at the .acs page sharing the same filename as the slave, not master
• the master page can be viewed at its own .acs page, but shows nothing in place of the <slave> tag
• you can have nested slave sections, that is, a slave section within another slave
• you cannot have two different slave sections within the same master (go ahead and try adding an extra <slave> tag to a master page to see what happens)
• <property> tags are used within a slave section to pass text, HTML and references to local datasources up to the master page; these values are placed in the master page in the same fashion as onevalues
• data and HTML can be passed from a nested slave section to its uber-master by using one <property> tag on each intermediate page
• if a variable set in the Tcl file of a master page shares the same name as a variable declared within the slave section's <property> tag, the master value overrides the slave's (unless the Tcl code checks for pre-existing information)

Now that the secrets of <master> and <slave> have been revealed, it's time to put a little of your newfound knowledge to use. Open up form-sample.adp, a standalone, independently formatted html page, and enslave it to the mastery of your personal web page. It would also be nice if you were to label the newly inserted form with some slave-specific title.

Exercise Four: The functions of <formtemplate>

Creating forms with ATS can be as simple as inserting two tags into a page. Try this: open form-sample.adp and add the two following ATS tags:

<formtemplate id="add_entry"></formtemplate>

Save the page and reload it. You should see now see a big baby-blue form block; this is the ATS default style for form presentation. Aside from requiring no HTML code, the <formtemplate> default has the added convenience of automated entry validation with appropriate correction requests. Test this out by trying to submit a form without including first or last name or gender information.

However, if ever you wish to build a form according to the mandates of your own taste, <formtemplate> also leaves you this option. Manually stylizing forms with ATS requires you to learn only two more tags, <formwidget> and <formgroup>. Browse through the ATS demo for examples of <formwidget> and <formwidget> usage. For the most part <formwidget> should be used in most places you might have used <select> or <input> in plain HTML, save for <input> checkboxes and radio buttons, which should be replaced with the <formgroup> tag. When working with ATS you should probably refrain from using plain <input> and <select> tags altogether.

You may have already noticed a few <formwidget> and <formgroup> in use within the block of HTML and ATS text commented out in form-sample.adp. Go ahead and put that block of HTML/ATS code into action by removing the comment tag wrapper and deleting the </formtemplate> tag; you should now see a hand-built version of the same form.

There are noticeable differences between the two form templates, most obviously the lack of background color and a few missing entry fields in the manually constructed one. Maybe not so noticeable is the grouping of entry widgets into one HTML table row (check out the Name field) and the multi-input combination of text entry boxes and radio buttons for entering telephone number information. Take a look at how the phone information entry section is constructed in form-sample.adp. Note specifically: <formgroup> is somewhat similar to the <multiple> tag in that the block of ATS code contained within the <formgroup> tags will be parsed into plain HTML once for each <formgroup> value option.

Practice using <formwidget> and <formgroup> by adding the missing entry fields manually into the form. Make free use of any HTML properties to streamline the form to your liking. If you can't remember what those fields were you can replace the closing </formtemplate> tag to recover the default format, or make use of the .dat datasource page to view your developer's description and comments about the form.

Also, try customizing your form's error response/correction request text. You'll need to use the <formerror> tag, an example of which can be found under the gender formwidget.

Exercise Five: more fun with multirows

Now that you've confidently added the conditional <if> and <else> tags to your ATS toolbelt, it's time to put those tools to good use in formatting multirow data. First, read the docs to learn about the automatcally generated @your_multirow.rownum@ column, the @your_multirow:rowcount@ onevalue which contains the total number of rows contained in your multirow, and the <multiple> startrow and maxrows attributes. Possible point of confusion: the variable @your_multirow:rowcount@ is a onevalue and not a column of the multirow your_multirow, so it need not be used within <multiple> tags and in many cases should not be used within <multiple> tags. Why is this? (Take a look at how @address:rowcount@ is used.) Now make the following improvements to the address book listing you found in form-sample.acs:

• stripe the table with banded rows of alternating grey and white, or some other color scheme of your preference
• use the startrow attribute so that the address book listing begins at a rownumber determined by the Tcl file code (check the .dat page)
• add navigation links to the address book so that users can move forward or back between row listings, or jump to the beginning or end of their address book
• each link should set the url variable that determines the first row of the set to be displayed
• the links should only appear when necessary, that is, a link pointing towards the next set of rows should not appear if the user is already viewing rows 1-5 of 5 total rows.