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.2.2.1
--- 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 25 Aug 2015 18:02:14 -0000 1.2.2.1
@@ -2,36 +2,47 @@
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,
+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
+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
+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
+(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 The ACS Templating System for Web Designers
Reading
+
+The ACS Templating System for Web Designers
+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?)/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
@@ -46,7 +57,8 @@
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
@@ -68,16 +80,19 @@
of the multirow>.<name of a field in the multirow>\@, and
can only be called within their respective
<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 +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
@@ -87,16 +102,20 @@
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 +
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 +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 @@ -105,7 +124,8 @@ 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:
\@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 +
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
@@ -127,21 +148,26 @@
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 +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 +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 +
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.
+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 +
+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 @@ -190,12 +222,14 @@ <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 @@ -206,15 +240,19 @@ <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 +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 +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
@@ -229,7 +267,8 @@
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
:
form-sample.acs
:
+startrow
attribute so that the address
book listing begins at a rownumber determined by the Tcl file code
@@ -241,6 +280,8 @@
pointing towards the next set of rows should not appear if the user
is already viewing rows 1-5 of 5 total rows.