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:
Contents
- 1 How to access fields
- 2 Using Curly bracket syntax
- 3 Index View
- 4 Fultext View
- 5 Where can the design come from
- 6 Special views (Calendar,RSS,..)
- 6.1 What are Views good for?
- 6.2 How do I include this View in a HTML page?
- 6.3 How do I sort items within a View?
- 6.4 How do I select a sub-set of items from a view
- 6.5 How do I create a Index of some items
- 6.6 How do I make it view just a single item?
- 6.7 How do I link a Index view to show the items in a Full Text view
- 6.8 How can I change a piece of content on a page, for example a context-dependent Navigation menu
- 6.9 How can I parameterize a view and fill in details from the URL
- 7 Popular Items (Hit counting)
- 8 Index View vs. Other Views
- 9 Empty result set
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#:Parameters: <code>r</code>
The "r" parameter tells the f_d date function to print RFC 822 formatted date required by the RSS specification
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:<img src="img/icon_{switch.........1}.gif" width="14"> :text...........1::href:class="green10"
There is also a possibility to use {} syntax, as explained in the {} Syntax section.
Index View
~ToDo: Describe index view
Fultext View
~ToDo: Describe fulltext 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
- You can include a view from within an alias by using the function f_v
Special views (Calendar,RSS,..)
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 <a href="http://actionapps.org/faq/detail.shtml?x=1677">sorting</a>,
or pick <a href="http://actionapps.org/faq/detail.shtml?x=1741">certain items</a> or only a <a href="http://actionapps.org/faq/detail.shtml?x=1676">subset
of the items</a>.
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.
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 view 110, for the item specified.
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.
For example:
----------- index.shtml ----------
[...]
content
<!--#include virtual="/apc-aa/view.php3?vid=9"-->
page footer...
[...]
--------- code for this menu in the Odd row field of view #9-----
[...]
<a href="index.shtml?cmd[9]=v-13">News</a> <a href="index.shtml?cmd[9]=v-14">Calendar</a> <a href="index.shtml?cmd[9]=v-15">About us</a>
[...]
When the index.shtml page is redrawn the initial view #9 will be replaced by the appropriate view, for example view #13 will appear in the News slice and view #14 in the Calendar slice.
Because the PHP is interpreted via an include on the server, you cannot easily change the view at run-time, for example changing it based on a mouse-over event, it requires a page to be redrawn.
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
/topic.shtml?als[MY_TOPIC]=Communication+Rights&als[URLE_TOP]=Communication%2BRights
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:
<a href="/resource.shtml?cmd[1]=c-1-South%2BAfrica-c-2-_#URLE_TOP">South
Africa - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Morocco-c-2-_#URLE_TOP">Morocco
- _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Senegal-c-2-_#URLE_TOP">Senegal
- _#MY_TOPIC </a>
and the MY_TOPIC and URLE_TOP are substituted from the als parameters in the
URL.
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.
If you want to use views like "Most popular last day" (or week), you have to add statistics fields hit_1..............., hit_7........... or hit_30..........
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.
Index View vs. Other Views
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 |
Empty result set
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.
