Index: openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp 27 Oct 2014 16:40:22 -0000 1.2
+++ openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp 7 Aug 2017 23:48:03 -0000 1.3
@@ -1,147 +1,178 @@
- This series of exercises is meant as a learning tool for any web
+
+ 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
+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 accomodating numerous permutaions 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. The basic building block of dynamic data in a template is the
-onevalue variable. A variable
+presentation style while accommodating numerous permutaions 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. The basic building block of dynamic data in a template is the
+onevalue variable. A variable
is simply a tag used in your
-Exercise 1: Onevalues, onelists, multilists and
-multirows Let's first take a look at some list and variable tags in
+Variable tags come in three basic formats, as lists, multiples and onevalues.
+Exercise 1: Onevalues, onelists, multilists and
+multirows 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 The ACS Templating System for Web Designers
Reading
-
+The ACS Templating System for Web Designers
+
+Templating System : Templating
+Exercise
+Reading
+
+
Sections
+
Sections
+Overview
Overview
+Exercises
Exercises
+.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.
-(nestedlists, too?)
+(nestedlists, too?)/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
+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 it's presentation. Compare what you see in
+the format of it's 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:
+two, specifically:
.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
+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
-list-and-var-sample.acs
; example:
-<multiple name="your_multirow"> - <tr><td>\@your_multirow.first_names\@ \@your_multirow.last_name\@ </td> </tr> +
-The user will see one table row filled with a different person's -name for each row contained in the multirow -<multiple name="your_multirow"> + <tr><td>\@your_multirow.first_names\@ \@your_multirow.last_name\@ </td> </tr> </multiple>
your_multirow
.
your_multirow
.<multiple>
tagsYou probably noticed some other funky looking tags, too, but -ignore those for now.
Now since the variable marker \@name\@
is set in
+
+
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 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:
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 +
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 -accomodate data changes. The function of <if> is +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 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:
<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 falseNow, alter a few of the <if> tags in
+\@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
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
+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 +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
+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:
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,
+
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
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 +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 +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 +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 +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 +<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, +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
+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 +<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
+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
:
\@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
:
+startrow
attribute so that the address
book listing begins at a rownumber determined by the Tcl file code
@@ -241,6 +286,8 @@
pointing towards the next set of rows should not appear if the user
is already viewing rows 1-5 of 5 total rows.