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:

How to access fields

Using Aliases

Once you have the data in the database, you want to display them on the website. To access the value of the field, you can either call the value up directly by enclosing the field id in the curly brackets, or use something called "alias". Alias is a nickname of the field.

Aliases look like this: _#MY_ALIAS

They are exactly 10 letters long, always starting with _#.
This is what happens with aliases next:
If you use the alias (let's say _#MY_ALIAS) somewhere in the design template (or as a parameter of another alias), ActionApps system will

take the value of the current item (record) field

modify the value through the selected alias function

replace the _#MY_ALIAS string with the result of the previous two steps

Note: By "current item" we mean either an item referenced by it's id (fulltext views) or the current item in the iteration through all the items that follow certain conditions (index views)

As mentioned above, aliases can be used in a nested fashion, that means that you can use aliases as parameters for the alias function in the alias definition. For example this Parameters to f_c alias functions are possible:

!:<img src=":" _#PHOTO_WI _#PHOTO_HE alt="photo">::

which displays image (if it is defined). The aliases _#PHOTO_WI _#PHOTO_HE must be defined, of course.

Creating new aliases

Go to Slice Admin -> Fields -> Edit (next to the field you want to add an alias for, e.g Publish Date (publish_date....))
Under the section "ALIASES used in views to print field content" of the form, you can define up to 3 aliases.
Empty aliases have no name and are set to default function f_0 - null function. You choose the name of the alias, the function to be used and optionaly the parameters to the function.

In the following example, you want to create a new alias which will print the RSS compliant date based on the value in the "publish_date...." field.

Example:

Choose the name of your new alias:

Alias 2: _#MYRSSDAT

Choose the function to be used for generating the final value:

Function: <code>f_d date</code>

Define the parameters. If you need to modify the behavior of the function, do so through the parametres (clicking on parameter wizard may help). Parameters are separated by ':' (colon), if you need to use :, escape it by #, i.e #:

Using Curly bracket syntax

Similary, it is possible to use any of database field directly there. Imagine, we store type of record in switch.........1 field (for example text/audio/video). If we create three images - icon_text.gif, icon_audio.gif, icon_video.gif, we can add an icon before each link by the following Parameters to f_m alias function:

Index View

Fultext View

Where can the design come from

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 (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 [
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

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.

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 can I change a piece of content on a page, for example a context-dependent Navigation menu

Views can be swapped in and out from the URL, using syntax like:

cmd[5]=v-8

to display view 8 at the place where View 5 was expected, for example:

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

For example, if you want a navigation menu that redraws itself depending on what is clicked on, you should create each of the different views you want to appear and then include one view in the shtml page. Then you can switch between displayed views using the url parameter.

How can I parameterize a view and fill in details from the URL

You can use aliases defined in the URL parameter 'als'. For a detailed description
of the als parameter, see "<a href="http://actionapps.org/faq/detail.shtml?x=1767">What parameters can I
use with slice.php3</a>"
For example,
There are 13 navigation pages. For example, there is a page on 'Communication
Rights' which has a report on Internet Rights in general and links to the pages
'Communication Rights in South Africa'
'Communication Rights in Morocco'
'Communication Rights in Senegal'
etc...
I did not want to write 13 pages, so I used 2 static views -- one for country
pages, and one for topic pages.
The topic page is /topic.shtml. It has this include
topic.shtml will be called with parameters. To create the 'Communication Rights'
topic page, it will be called as

URLE_TOP is an alias similar to MY_TOPIC, but it double URL encodes the value.
It will be used to generate links. %2B represents the +. A + in url encoding
is a space.
In this topic.shtml I want to create links to these pages. To create these
links, view #2 has this 'odd row' format:

Popular Items (Hit counting)

If you want to display the most popular items in your slice, you can just create view and sort the items by display_count... field descending. The display_field is mandatory and is always present for each item. The field holds the total sum of item displays.

Statistics fields holding information about item views last day/week/month. The statistics field are not part of the slice automatically - you have to add it there. We do it on purpose, since the counting statistics is very timeconsuming task, so we count it only for the slices, where the field is added.

You can just add the fied "Hits last day", "Hits last week" or "Hits last month" on "Slice Admin" -> "Fields" page. Such fields are present in AA 2.12 and above.

It makes no sense to add such field to the slice if you do not want to use it! It is no problem to add such field anytime in the future, because we store the hit log for all items, so we are able to count the statistics backward.

We are trying to filter out all the hits which comes from the Bots (Googlebot, ...) and not count it in the statistics. The filtering was added in AA 2.12.

How it is done technicaly?

Hits are logged to two temporary tables - hit_short_id (for short item ids) and hit_long_id (for long item ids). With COUNTHIT_PROBABILITY (eg. default 1000 ==> probability 0.001) we recount logged hits into table item and move the hits to hit_archive table. hit_archive is then used for making statistics - like "10 the most read items in last week, ..."

The statistics is quite powerfull - it is counted only for the slices, where you add the hit_1..........., hit_7........... or hit_30.......... field. The hit_1.. field holds display count one day back, hit_7.. one week and hit_30.. one month (no problem to add new field like hit_14, or hit_100 if you need another time period). The statistics counting is quite demanding task - you need to update all the items in the slice. That's why we use periodical updater with different period for each field: Currently the time periods are

hit_1 (day) plan +/- 5 minutes

hit_7 (week) plan +/- 35 minutes

hit_30 (month) plan +/- 150 minutes

For the "statistics counting" task we use toexecute table, so if you have problems with statistics, check, if the script misc/toexecute.php3 is runned form the aa cron (see "AA" -> "Cron" admin page)

Why we use this approach? MySQL lock the item table for updte when someone do a search in that table. If we want to view any fulltext, we can't, because we have to wait for item.display_count update (which is locked). That's why we log the hit into temporary table and from time to time (with probability 1:1000) we update item table based on logs.

Spliting into three tables we make increase the speed of the database operations, which are often used in this case.

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.