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 Index View
- 2 Fultext View
- 3 Where can the design come from
- 4 Special views (Calendar,RSS,..)
- 4.1 What are Views good for?
- 4.2 How do I include this View in a HTML page?
- 4.3 How do I sort items within a View?
- 4.4 How do I select a sub-set of items from a view
- 4.5 How do I create a Index of some items
- 4.6 How do I make it view just a single item?
- 4.7 How do I link a Index view to show the items in a Full Text view
- 4.8 How can I change a piece of content on a page, for example a context-dependent Navigation menu
- 4.9 How can I parameterize a view and fill in details from the URL
- 5 Index View vs. Other Views
- 6 Empty result set
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 <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
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?
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.
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 | <a href="http://actionapps.org/faq/detail.shtml?x=1676">Yes</a> | <a href="http://actionapps.org/faq/detail.shtml?x=1767">Yes</a> |
| Search Form | No | <#215>Yes |
| ?x=1699 | No <a href="http://actionapps.org/faq/detail.shtml?x=1740"> (workaround)</a> | 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 | <a href="http://actionapps.org/faq/detail.shtml?x=1677">From Admin only</a> | From <a href="http://actionapps.org/faq/detail.shtml?x=1767">URL parameters</a> 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.
