Designing Output Templates

From ActionApps Documentation
Jump to: navigation, search
ActionApps output possibilities

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:
  1. Choose the name of your new alias:

    Alias 2: _#MYRSSDAT

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

    Function: <code>f_d date</code>

  3. 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

Origin: ~ToDo: id=1714 Where is the HTML

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,..)

Origin: ~ToDo: id=1745 What are Views good for?

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>.


Origin: ~ToDo: id=1743 How do I include this View in a HTML page?

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.


Origin: ~ToDo: id=1676 How do I select a sub-set of items from a 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.


Origin: ~ToDo: id=1678 How do I create a Index of some items

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).


Origin: ~ToDo: id=1741 How do I make it view just a single item? rel:2090,1740,1736,

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


Origin: ~ToDo: id=1740 How do I link a Index view to show the items in a Full Text view rel:1741

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.

Origin: ~ToDo: id=1737 How can I change a piece of content on a page, for example a context-dependent Navigation menu

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.

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.

Origin: ~ToDo: id=1738 How can I parameterize a view and fill in details from the URL rel:1741

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

Origin: ~ToDo: id=1699 Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?

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 featuresViewIndex
Search conditions from URLYesYes
Search FormNo<#215>Yes
?x=1699No (workaround)Yes
ScrollerNoYes
Slice idImplicit, can be overridden by parameterParameter in include or URL
Copy with TemplateYes with new wizard, but may need to edit HTML because numbers changeYes
SortingFrom Admin onlyFrom URL parameters only



Empty result set

Origin: ~ToDo: id=1658 How "No item found" message in view definition works? rel:277,

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.