Designing Output Templates

Let's assume we have some data in the ActionApps slice. In this chapter, we'll look at how to present the data on the website, that means how to create a (single) web page which lists the data in the desired format and look. First, let's look briefly at which parts of ActionApps are responsible for generating the design:

Index View

~ToDo: Describe index view

Fultext View

~ToDo: Describe fulltext view 

Where is the HTML

The HTML for a typical APC-AA site can come from many places which can confuse people used to doing all their HTML in a single place.

Location	What to put there
.shtml file	static HTML that doesn't repeat, and is not changed often. Can be edited with any standard web editor by someone who has write permissions on the web server. The HTML has lines like <!--#include "/apc-aa/view.php3 --> (or apc-aa/slice.php3) to include a PHP file which will fetch information from the Slice's design.
Design section of the Slice	This is used to list a range of items in a slice, or display a single item. Someone with Admin permission on the slice can go to apc-aa/admin -> Admin -> Views or apc-aa/admin -> Admin -> Display/Index or Display/Fulltext. HTML can be placed here associated with the top and bottom of a listing, with each item, and with groupings of items. The HTML includes alias such as _#HEADLINE
Aliases such as _#HEADLINE	Each alias defines how to show a particular field, it does this by choosing a function (e.g. f_h) and parameters. For example _#HEADLINE is usually just output, while a Link might be output surrounded by <a href=" and ">. They can be edited by anyone with administrator priviliges on your slice by going to Admin->Fields->choose field ->Edit. A field can have several different ways of being output, for example a date could have aliases for both short (1/1/200) and long (1 January 2000) forms of output.
Functions such as f_h	These define functions certain common ways fields are output. They are defined in the PHP code, and so have to be edited by developers, except that there is an extension function f_u that calls functions from apc-aa/include/usr_aliasfnc.php3, these can be written by anyone who understands PHP3.
Data	Lastly of course, the HTML could be in specific fields in your data.

Exceptions:

• You don't have to put a .shtml at the top - you can just use a more complex URL refering to apc-aa/slice.php3 or apc-aa/view.php3
• You can include a view from within an alias by using the function f_v

What are Views good for?

Views are useful when you want functionality a little bit different from the standard Index, or Full-Text views. You can use them to customize sorting, or pick certain items or only a subset of the items.

How do I include this View in a HTML page?

<!--#include virtual="/aa/view.php3?vid=5"-->

Will embed view number 5 into your page. The view knows which slice it applies to, so this can be embedded in an Index or Full Text View.

View.php3 will take parameters either in the "include" line, or in the URL of the page to which it refers.

How do I sort items within a View?

You can sort items by specifying in the definition of the view (Admin->Views then select an existing View or click New) which fields to sort by, and wether to sort ascending or descending. The primary sort is the main ordering, and the secondary sorts within this. So for example you might specify Category as the primary sort, and sub-category as the secondary. Note that if you sort on a field then there is a bug (or feature) where items without that field defined will not show up in the index view.

How do I select a sub-set of items from a view

To select just a sub-set of the items, specify a Condition, or set of conditions, you can then parameterise that in the include statement or URL. So for example, if you set Condition 1 to "Category" and "LIKE" then you can specify a parameter of "cmd[5]=c-1-News" to set the first condition on View 5 to "News" so that it would list any item with a category containing the string "News". This condition could be set in either the Include statement or the URL e.g.

<!--#include virtual="/aa/view.php3?vid=5&cmd[5]=c-1-News"-->

or in the URL.

?cmd[5]=c-1-News&.....

If there are special characters in the search term, i.e. dashes (as in E-mail) or spaces then quote it, and escape the quotes, for example to select a category=Social Ecology would require a URL of the form:

conds[0][category........]=%22Social%20Ecology%22

(%22 is a double quote (") and %20 is space). If you are constructing this URL from somewhere else and do not know what could be in the field then make sure to quote and urlencode the string.

How do I create a Index of some items

You have to be the slice administrator, then from the standard admin page select Admin -> Views, then you select "Item Listing" and click New.

The first few items are the same as for creating Index views (see the manual). You can then specify how to sort items, and specify a condition (that can take a parameter in the URL).

How do I make it view just a single item?

Create a Full-Text view by going to Admin->Views and selecting "Full Text" and clicking "New". Then you can specify cmd[5]=i-5-1a2b3c4d in the URL or include statement. You can also use cmd[5]=x-5-934 where 934 is short _id

How do I link a Index view to show the items in a Full Text view

The right alias is _#ITEM_ID#.

For example, to show an item in a full text view, the view.php3 script should get the parameters like:

vid=110&cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf

( the 'i' command to view.php3 script takes as argument unpacked (long) item id)

So if we pass the vid parameter directly in fulltext.shtml page:
fulltext.shtml:

<!--#include virtual="/aaa/view.php3?vid=110"-->

Which then needs us to pass the cmd parameter through url:

<a href="fulltext.shtml?cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf"> fulltext </a>

So we can generate this by placing in the Odd rows field of an index view

<a href="fulltext.shtml?cmd[110]=i-110-_#ITEM_ID#"> fulltext </a>

If you want to link to a view appearing in the same place on the same page (as for the main index going to a full text), then if your Index view has vid=109 then the URL should be:

"?cmd[109]=i-110-_#ITEM_ID#"

which will redraw the same screen, replacing view 109 with view110, for the item specified.

How to create a Calendar

The AA now enable to create a Calendar. Events lasting for several days are supported, repeating events are not supported.

Usually three parts of a calendar view are needed. First, a table showing the days and perhaps some caption of events which happen. This is prepared by the calendar view type. Second, some select boxes to choose the year and the month. Prepare these in a .php3 page. Third, a list of events to be shown after clicking on a date. This may be done by a list view with the conditions set as explained further.

To put the view and the caption together, use a .shtml page --- an example of a very simple one is in doc/script/calendar.php3.

Calendar view

Create it by Admin - Views - Calendar - New. Two calendar types are available: Month List shows a month with days in one list under each other, Month Table shows a table with one row for each week. Some new aliases are defined:

• _#CV_NUM_D is the number of the day (to be used in a day cell)
• _#CV_NUM_M is the number of the month (to be used in a day cell, usually in an URL link)
• _#CV_NUM_Y is the number of the year (to be used in a day cell, usually in an URL link)
• _#CV_TST_1 time stamp of the current day at 0:00 (to be used in a condition)
• _#CV_TST_2 time stamp of the next day at 0:00 (to be used in a condition)

New parameters to the view command are introduced: month and year. E.g.
set[301]=month-3&year-2002

The view setting are as follows:

• Top HTML code must contain the <table> tag and may contain e.g. a table row with names of week days (Mon,Tue,...).
• Bottom HTML code must contain the </table> tag.
• Additional attribs to the TD event tag may e.g. set a background color to each event. If the alias _#COLOR___ contains a color, write bgcolor=_#COLOR___
• Event format is the code for the Event description.
• Start date field contains the event start date (must be filled!).
• End date field contains the event end date (must be filled!).
• Day cell top format For "Month List" calendar type it must begin with a <tr> tag. It contains a table cell tag with the day number, usually linked to an daily event list, e.g.
  <td><A href="calendar.shtml?vid=319&cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1&month=_#CV_NUM_M&year=_#CV_NUM_Y&day=_#CV_NUM_D"><B>_#CV_NUM_D</B></A></td>
  
  The view settings cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1 involve appropriate settings in the list view (no. 319 in my case) - see further. The month=_#CV_NUM_M&year=_#CV_NUM_Y&day=_#CV_NUM_D variables are used in the .php3 page to show the appropriate date - see the example in doc/example/calendar.php3
• Day cell bottom format for "Month List" it must end with </tr>
• Empty day cell top format usually the same as Day cell top format, but without the link to the event list
• Condition 1,2,3 you may use conditions with the calendar, e.g. to view only events of some type

Year and month selectboxes

These may be created by a .php3 script. An example of one is in doc/script/calendar.php3. The script is commented

List of events

An ordinary view of the type "Item listing" will do. You must set two conditions. The first condition must be "Start date <" where Start date is the name of the field containing event start date, the second must be "End date >=" where End date is the name of the field containing event end date.

The conditions are controlled by the command cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1 described above.

Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?

The Item Listing View (View.php3) and Design-Index (slice.php3) provide overlapping features. Which to use will depend on which features you need. Here are some of the differences.

Available features	View	Index
Search conditions from URL	Yes	Yes
Search Form	No	<#215>Yes
?x=1699	No (workaround)	Yes
Scroller	No	Yes
Slice id	Implicit, can be overridden by parameter	Parameter in include or URL
Copy with Template	Yes with new wizard, but may need to edit HTML because numbers change	Yes
Sorting	From Admin only	From URL parameters only

How "No item found" message in view definition works?

In view you can specify "No item found" message, which is displayed if view (due to its current conditions) do not find an item to display.You can enter there:

• nothing - standard "no item found" message is displayed (this setting is historical)
• any text - the text is displayed. From AA v2.6 you can also use aliases and other AA expressions like {switch()...}...
• <--Vacuum--> - if you use this keyword (exactly!), nothing is displayed.

One recomendation is to write something that relates to the slice content, e.g. "No news found" or "No events found", with in visible HTML or a comment tag. This helps with both usability and view development problem solving.