APC Action Applications - Home Page

Frequently Asked Questions v2

 

Topic: Views

0. How to use aliases
1. How to show integers but not show 0?
2. How to display archive (expired items)?
3. two level menu view
4. How "No item found" message in view definition works?
5. How can I include photos to the texts of articles?
6. MultiLingual eXtension for ActionApps / How to setup ActionApps for multilingual web sites
7. Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?
8. What are Views good for?
9. How do I create a Index of some items
10. How do I include this View in a HTML page?
11. How do I sort items within a View?
12. How do I include Previous and Next in the scroller of a View.
13. How do I select a sub-set of items from a view
14. How do I view just highlighted items on a page.
15. How do I make it view just a single item?
16. How do I link a Index view to show the items in a Full Text view
17. What is a Static View and how do I use it
18. How can I parameterize a view and fill in details from the URL
19. How can I change a piece of content on a page, for example a context-dependent Navigation menu
20. How do I use a Javascript view to see pages on a site where AA is not installed
21. Which parameters can I use with view.php3
22. How do I use jsview.php3 to view pages on a site where AA is not installed
23. What are the different kinds of Views on the Admin->Views page?
24. Which parameters can I use with slice.php3
25. Which strings exactly are removed from Views?
26. Protecting sensitive data against reading
27. What paramater substitution is done in f_v

The output generated by AA is controlled by aliases. The aliases are 10 letters long words defined on 'Admin' -> 'Fields' -> 'Edit' page. Aliases are obviously expanded to the content of some database field or its modification (like How to use aliases alias). For modification of behavior of the alias we use alias functions, as described on
http://apc-aa.sourceforge.net/faq/#216.
http://apc-aa.sourceforge.net/faq/#291.

Since the AA version 2.1 there is possibility to use the aliases NESTED, which means that you can use another alias 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.

You can use there not only the aliases, but 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"

The AA version 2.2-pre (04/25/2002) give you new possibilities in alias definition - IN-LINE ALIAS DEFINITION. The parsing of format strings was rewritten, so now you can define aliases not only on 'Admin' -> 'Fields' -> 'Edit' page, but you can define it directly inside the format string (= 'Fulltext HTML code' on 'Design' -> 'Fulltext' page, for example). The new features are 100% backward compatible.

The alias definitions are surrounded by curly braces. There are the possibilities:

  1. direct display of some field

    ... there is displayed headline: {headline........} <br> Source: ...

  2. constant display

    Constants are stored in database as values, but it is possible to convert value back to name, description, ...
    The syntax is : {const_name:category.......1}, {const_description:category.......1}, which displays name (description) of constant stored in field category.......1.
    You can grab following information for the constants:
    const_short_idshort_id
    const_name name
    const_value value (the same as {category.......1} )
    const_pri priority number
    const_group name of constant group
    const_class class (APC parent category)
    const_id long constant id
    const_descriptiondescription (defined on hierarchy editor pages)


  3. display of multivalue fields

    ... fields in AA could contain multiple values (categories, ...). It is possible to diesplay it: The example is directly in Item Manager of 'Test News' slice. The syntax is:
    {@category.......1} displays list of 'values' - comma separated (comma is default)
    {@category.......1:-} displays list of 'values' - dash separated
    (it is usefull for example in display of related items: {view.php3?vid=11&cmd[11]=x-11-{@relation.......1:-}}
    {@category.......1:,:<b>_#1</b>} displays list of 'values' in bold - comma separated (_#1 is alias for the values)
    {@category.......1:,:<a href="/category.shtm?conds[0][category.......1]=_#1">_#1</a>} displays list of categories with link to the each category
    {@category.......1(const_name,const_value,const_short_id):,:<a href="/category.shtm?conds[0][category.......1]=_#2">_#3 _#1</a>} displays list of categories with link to the each category, but the text shows category name (and short_id) instead of value.
    You can use as many constant translations as you want in the parethes. See 'constant display' for list of possible values in previous paragraph.


  4. direct display of a variable defined with als or in $apc_state:

    ...view.php3?vid=123&als[heading]=My Page

    and then ... <h1>{heading}</h1>


    The same syntax will find variables defined in apc_state (by the site module).

  5. modification through alias functions:

    ... The previous example is good, but sometimes we need to modify the database field before it is displayed. For example the date field is displayed as number if seconds since begin of year 1970, which is probably not exactly what we want to show to user. The solution is to use alias function modification, which has the following syntax:

    alias:<the field>:<alias function>:<parameters>

    So, in text (format string) could be the publish date displayed by {alias:publish_date....:f_d:j.n.Y}. There you can use any alias function with any parameters.

    The parameters could be nested, so inside curly braces you can use any alias (How to use aliases), any other field ({headline........}) or any other in-line alias definition. There is no limit in level of nesting.

    For example, conditional display of date could look:

    {alias:switch.........1:f_c:text:{alias:publish_date....:f_d:j.n.Y}<!--:-->::}

    or if we have 06/19/2002 alias defined:

    {alias:switch.........1:f_c:text:06/19/2002<!--:-->::}

    Both this constructs displays date only if switch.........1 is equal to 'text'. ...

  6. comments

    ... as addition to in-line aliases you can {# make comments} which is not displayed in result html code. It could be nested again, so you can {# comment out _#ALIASES_ as well as fields {headline........} or alias definitions } - nothing will be in result HTML code ...

  7. switch

    ... the really new and very useful construct is switch. Many of us knows the troubles with conditional expressions, managed so far by f_c function. Now there is much better solution, which allows more options, regular expressions, ... The syntax is:

    {switch(<condition>)<option1>:<output1>:<option2>:<output2>:...[:<default_output>]}

    which we can explain on example:

    {switch({number.........1})1:one:2:two:[3-7]:more:too much}.

    This construct evaluates the condition, which is the content of the number.........1 field in our case. If content of the field is equal to 1, the 'one' is printed. Because 'options' are regular expression, we can specify the third option as [3-7] which means any number in range between 2 and 7. The default option is 'too much' in our case. The evaluation of options goes from left to right and the output is printed only for the first matching option.

    The 'switch' could be used instead of f_c alias function in many cases:

    {switch({switch.........1})text:06/19/2002}

    This expression could replace the expression in the paragraph 2)

    Another example displays text 'Continuos grant', if the field unspecified....2 is filled by 'yes', 'on', 'true' or '1'. Else it displays expiry date:

    {switch({unspecified....2})yes|on|true|1:Continuos grant::12/11/2007}

    Display of phone number, if specified (as obvious, '#:' stands for ':' if you do not want to use it as argument separator:

    {switch({con_phone......1}).+:Tel#:{con_phone......1}}

    Last example demonstrates the fact, that there is no limit in <condition>. There could be not only field (in curly braces), but there could be also any alias, alias definition or its combination. The level of nesting of 'curly braces expressions' is again unlimited.

    {switch({1})[1-9][0-9]*:There is discussion under this item}

  8. Inclusion of a view
    {view.php3?vid=123}

    Returns content of view 123. View uses the just like the view.php3 script, and can nest other {} structures. (e.g. {view.php3?vid=122&cmd[122]=c-1-{f}} ) Very useful for displaying related items e.g. {view.php3?vid=33&cmd[33]=x-33-{relation.......1}}

  9. includes (added 06/20/2002 - will be in AA v2.2.1)

    ... Sometimes we need to include some file or output of some script into the page. Now, there is {include(<file>)}, which will be replaced by the file. The file is called through HTTP request. No matter if included file is html, shtml, php, ...:

    the page was visited {include(cgi/counter.pl?id=222)}

    (the result of http://www.example.com/cgi/counter.pl?id=222 will be printed)

    APC news: {include(http://apc.org/apps/aa/view.php3?vid=112)}

    (the remote view (from APC site) will be printed)

    If you want to include other slices, it could be usefull to pass the URL parameters to the included file. In this case use the special URL_PARAMETERS constant:

    {include(fulltext.shtml?URL_PARAMETERS)}

    The limits:

    This can be used in an alternative syntax {include:<file>} or {include:<file>:http} which work exactly the same or {include:<file>:fileman} which will try and read the file directly from the Fileman directory for the slice being used. (this code is new 23 may 2003 and the definition of which slice is being used might change)

  10. mathematics operations (new in AA v2.4.0)

    ... If you want to compute some walue from datadase field, use the {math..} alias. The syntax is ...:

    {math(result_formatting) description1: expression 1: description2: expression2:...:description x : expression x }

    where:
    result_formatting has 3 parameters separated by '#' (number of decimals # decimals separator # thousands separator)
    descriptioncan be any text or html and is displayed before result of expression ("#:" mean ":")
    expressionin expression can be used numbers (decimal separator is ".". Aliases can be used of course) and characters: + - / * ^ . ( )

    example 1 - use in inquiry

    
    <img src="red.gif"   height=10 width="{math(0#,#) : {_#ANSVER1_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER1_ <br>
    <img src="blue.gif"  height=10 width="{math(0#,#) : {_#ANSVER2_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER2_ <br>
    <img src="green.gif" height=10 width="{math(0#,#) : {_#ANSVER3_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER3_ <br>
    
    
    if _#ANSVER1 = 25, _#ANSVER2 = 50, _#ANSVER3 = 250 result will be:
    
    
    <img src="red.gif" height=10 width="8%">  25   <br>
    <img src="blue.gif" height=10 width="15%">  50   <br>
    <img src="green.gif" height=10 width="77%">  250   <br>
    
    

    example 2 - cost of ordered services last year
    
    {math(2#,# ) <br>mails=:{_#NOOFEMAI}*{_#EMAPRICE}:
                 <br>web=:{_#WWWPRICE}:
                 <br>technical support=:{_#NOOFHOUR}*{_#HOURPRIC}:
    <br><hr>total={_#NOOFEMAI}*{_#EMAPRICE}+{_#WWWPRICE}+{_#NOOFHOUR}*{_#HOURPRIC}
    }
    
    
    result:
    
    mails=450,00
    web=1500,00
    technical support=2400,00
    ----------------------------
    total=4350,00
    

  11. user informations (new in AA v2.6 (CVS 05/19/2003))

    In AA v2.6 is new Reader Management, where you can control access to directory or file through AA admin interface (see Reader Management). You can then display informations about logged user by {user:} construct.
    The syntax is following:
    {user:} displays login of current user
    (this option do not search in database, so it is quick)
    You can use this parameter even if you do not use Reader Management slice and you are using standard Apache's password file auth ...
    {user:password} displays password of current user (in plain text)
    (this option also do not looks into database, but into internal server variable, so it is also quick)
    {user:headline........} displays headline........ field for current user, which is grabbed from Reader Management slice. There is no need to specify in which Reader Management slice user is, because all users are unique in all Reader Management slices.
    If the Reader Management slice is protected by password (see 'Slice Admin' -> 'Slice' -> 'Password for Reading'), you have to add slice_pwd parameter to view.php3 (or slice.php3), in which you want to display user's database info.
    You can of course display any field from Reader Management slice.
    {user:role} displays user's permission role (author/editor/administrator/super/undefined)
    (usefull in AA admin interface when you want to display another informations to authors and editors - use it in switch() - like {switch({user:role})editor:_#POSTED_BY} )

    Such construct you can use in any view or slice - just like any other aliases.

  12. page scroller (for site module only)

    ... If you want to use page scroller (Page 1 | 2 | 3 | ... ) in view , which is part of 'site'! (see site module), the {scroller} syntax construct is the right tool. You just add {scorller} to the view, there you want to usepage scroller - probably in the 'Bottom HTML' fileld of the view:

    {scroller:Page ::class="blue"}

    The syntax for {scroller} is:


    {scroller:begin:end:add:nopage}

    where:
    begin text to be shown before page numbers
    endtext to be shown after page numbers
    addoption to be added to page number
    <a href=".." class="blue10v">1</a>
    nopagetext to be shown wnen there are (yet) no pages (so the scroller is not displayed)

    Then you use quite normal view include using {p} state variable, which stores the page number in the site module's spot:

    {view.php3?vid=32&set[]=page-{p},listlen-10}

  13. Debugging

    Because it is sometimes unclear which substitutions are available at a certain point, {debug} will output some hopefully useful information

In this example, we are trying to only show alias for page numbers (_#NM_PAGES) when it is greater than zero.

The field input has Validate: Number, so it generates a zero when left blank. To not show the alias and label when zero, use:

{switch({_#NM_PAGES})^0:: _#NM_PAGES pages }

This switch will show nothing when the number starts with 0, otherwise it will show e.g. "15 pages". Since number validation removes preceeding zeros e.g. 0020, this should always work.

Expired items are normaly not visible on the public website. However is it usefull to sometimes show expired items such as for archives.

There are two easy steps to show expired items in a view:

  1. Make sure display of expired items is permitted by setting ALLOW_DISPLAY_EXPIRED_ITEMS constant to true in config.php3
  2. Define a condition where 'expiry_date.....' is specified. You can use a condition fields in a view design or a search condition or a condition in an URL or SSi using cmd[]-c or cmd[]-d see parameters to view.php3

Example of condition fields in a view design:

set Condition 1 'expirary date' < 9999999999999
(this is a unix date in far far far future - you'll be dead :^)

Example of view.php3 parameter:
.../view.php3?vid=23&cmd[23]=d-expiry_date.....-e:>-1.1.1998



This example uses 1 view, 3 categories, and 2 levels of constants. The catgories are not important but maybe you like to use them so I left them in there.

The view below manages a two level side bar menu. It highlights the branch you are in and the (sub)item you have selected. Example can be seen here http://pi.gn.apc.org

The constants are used as the menu entries. You have to use hierarchical constants and define the constants like this:

Level 0: Name      Value 
         Terrorism Terrorism 
         Policy    Policy ... 

Level 1: Name                        Value
         Politics of Terrorism       Terrorism::Politics of Terrorism Defining 
         Terrorism and Emergencies   Terrorism::Terrorism and Emergencies 
         IGOs and Laundering Policy  Policy::IGOs and Laundering Policy
         ... 

Now create a new constants view Paste the text below into Odd Rows.  Set the Group by to "Value Select" the hierarchical constant group created above View 342 is the listing view I use to display items from my slice.

The slice has 3 categories. This menu only manages the selection of the first category (category........) which is set to use the constant group created above. Further it's first confition is set to LIKE (name of category........). You will have to replace 342 in the text below with your listing view. You can leave away most of the {country}-stuff. To work this just needs {theme} and {_parent_}.

TODO: use better names for the aliases. 'theme' and 'country' might be substrings in the constants. That would cause havoc! All left to do now is to create your style sheet. Have fun!

----------SNIP SNIP----------

{switch({_#LEVEL##_})0:<br>
  {switch({theme}).*theme.*:
    <div class="constView_ContentThemes_ListEntry">
  :{_#NAME###_}.*:
    <div class="constView_ContentThemes_ListEntry_Hl">
    :<div class="constView_ContentThemes_ListEntry{switch({_parent_}){_#NAME###_}.*:_Hl}">
  }
  <a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}{switch({_#VALUE##_}){theme}.*:&als[_parent_]={theme}}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_ListEntry_link">_#NAME###_</a>
  </div>
:1:<!--{theme}--_#VALUE##_--_#NAME###_-->
  {switch({_parent_}).*_parent_.*:
    {switch({theme}).*theme.*::
      {switch({_#VALUE##_}){theme}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={theme}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  :{switch({theme}).*theme.*::
    {switch({_#VALUE##_}){_parent_}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={_parent_}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  }
}

----------SNIP SNIP----------

 

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:

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.

This can be done thanks to function f_y - expanded string.

  1. In the slice "Photogallery" make a view or views, which will show a single photograph.
  2. It is usefull to define the aliases in the Slice Admin / Design / Item Manager, so in the Item Manager you will see below any photograph the alias or aliases for showing it, e.g.: "{view.php3?vid=1047&cmd[1047]=i-1047-6341bce1bd2d5072f75cc440d6e1edf4}"
  3. In the slice "Articles", for the field "full_text......." create an alias e.g. _#FULLTEXT with fuction "f_y" and with no defined parameters.
  4. During the editing of items you can just copy the aliases from the slice "photograph" to the places in the text, where you would like to have the photographs

See an example.

see http://mimo.gn.apc.org/mlx for instructions

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

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.

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

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

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.

Because views do not currently use sessions. There is no way, how to add 'Previous 1 2 .. Next' scroller to the 'view'.

This is the biggest limitation of 'Views' and we have to count with it.

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.

If you want to put highlighted items on a page, you should create a view. In the view, one of the conditions is that highlight is not '' (note there is a bug so that once you've set the condition to '' if you try and edit this view, you will need to reset the condition to '' before you hit update or you will get a SQL syntax error

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

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.

Static Views are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.

It is a view that only has one format - the 'Odd Row' format. It does not lookup the values for any items or fields, but just prints the 'Odd Row format'.

However they can take parameters from the URL

You can use aliases defined in the URL parameter 'als'. For a detailed description of the als parameter, see "What parameters can I use with slice.php3"

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

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

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.

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 by <!--#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 ----------
[...]
<h3>content</h3>
<!--#include virtual="/apc-aa/view.php3?vid=9"-->
<p> page footer... </p>
[...]


--------- code for this menu in the Odd row field of view #9-----
[...]
<a href="index.shtml?cmd[9]=v-13">News</a><br>
<a href="index.shtml?cmd[9]=v-14">Calendar</a><br>
<a href="index.shtml?cmd[9]=v-15">About us</a><br>
[...]

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.

Javascript item exchange View is a type of View. It works exactly the same as a standard view, but the primary usage for this type is to show items on any page around the Internet. For a simpler way of doing this, see "How do I use jsview.php3 to view pages on a site where AA is not installed."

The destination page should contain a HTML tag like:

<SCRIPT LANGUAGE= "JavaScript"SRC="http://aa.ecn.cz/apc-aa/view.php3?vid=1"></SCRIPT>

This tag includes the output of view to any page on Internet (there is no restriction to one server).

Because such tag requires javascript as output of view.php3, the format strings for the view (Admin -> View) should look like:

Top HTML document.write("<TABLE WIDTH='100%' BORDER='0' CELLPADDING='2' BGCOLOR='#FFFFFF'>")
Odd Rows: document.write("<TR><TD VALIGN='TOP'>12/05/2001</TD><TD><a href='?x=1735'>How do I use a Javascript view to see pages on a site where AA is not installed</a></TD></TR>")

Bottom HTML:

document.write("</TABLE>")

Note that there is (or was) a bug where if the item would generate no items then you'll get an error rather than empty Javascript.

The only required parameter to view.php3 script is number of view to show. This parameter is given by vid url variable. All remaining parameters are optional.

Each optional view parameter begins with cmd[x], where x is view number in which the parameter should be used. This is needed because of possibility to include more than view to one shtml page. That's why we need to specify, for which view the command should work.

It is impossible to specify more than one cmd for one view. If you want to use cmd[]=d for the view, you can't use it with combination with cmd[]=c, for example.

Above is still true, even after CVS snapshot 20031109, since when you can also use this syntax: vid=x&cmd[x][]=c-1-<something>&cmd[x][]=c-2-<something>. Note the extra [].

However, you can use more settings (set[x]) per view. Just seperate settings with a comma, like: set[23]=from-10,to-20.

After the cmd[x]= is always character, which specify which command is used - how modify the view. The c command modifies conditions, for example. The values after command character are user parameters and its meaning is different for each command. The parameters are separated by '-' character. If you need to use a hyphen '-' in a parameter, use 2 hyphens '--' instead. Description of parameters is in following table of examples.

Parameter example Description
vid=4 id of displayed view
cmd[23]=v-25 show view id 25 in place of view id 23
cmd[23]=i-24-7464647 view number 23 has to display item 7464647 in format defined in view 24
cmd[23]=x-24-1589 The same as i, but there you can use both - short_id or long item id (as the last parameter)
cmd[23]=x-24-1589-1545-1612 Display all three specified items. You can use as many ids as you want (the same works also for 'i' and 'o' cmd). This behavior is used for related fields, where related fields are displayed by{view.php3?vid=33&cmd[33]=x-33-{@relation.......1:-}}.
cmd[23]=x-24-url keyword url means, that item id is taken from url parameter 'x=...'
cmd[23]=o-24-1589 The same as x, but the number of item display (countHit) is not increased (as opposite to 'x' or 'i')
cmd[23]=c-1-ICT display view no 23 in place of view no 23 (that's normal), but change value for condition 1 to "ICT"
cmd[23]=c-1-ICT-2-%22Jane%20Smith%22

the same as above, but there are redefined two conditions. All three conditions could be redefined, notice how "Jane Smith" requires urlencoded double quotes %22 or the search won't work, and the space turned urlencoded to %20 otherwise it would be interepreted as Jane OR Smith

Since CVS snapshot 20031109 you can also use this syntax:
cmd[23][]=c-1-ICT&cmd[23][]=c-2-%22Jane%20Smith%22
You do need to use this e.g. when you want to specify the first condition in your .shtml file, while second one comes from the URL
cmd[23]=d-headline........-LIKE-Profit-source.........1-=-Ecn-publish_date....-m:>-86400 displays view no 23 and redefines the conditions. The conditions are in format field-operator-value. For list of possible operators see search caption. The operators could be with its modifiers, too. The unlimited number of conditions should be there specified. The speciefied conditions allways replaces all conditions specified in view definition (through admin interface). There are three diferences from cmd[]-c command - 1)operators and fields are specified, 2) default view conditions are ingnored, 3) there can be unlimitted number of conditions. The example would show items in which the headline contains 'Profit' and source field is 'Ecn' and the item is newer that one day.
cmd[23]=d-headline.......1,category........-RLIKE-Enviro You can use more than one field in one condition. Example displays items where headline.......1 OR category........ begins with Enviro
set[23]=listlen-20 setings to modify view behavior (can be combined with cmd)
- sets maximal number of viewed items in view 23 to 20
- there can be more settings - comma separated
set[23]=sort-headline.......1 set item order (use 'sort-headline.......1-' for descending sort order
set[23]=from-10 - displays items from 10-th (in view 23) - it can be combined with listlen, to, ... parameters (set[23]=listlen-20,from-5)
set[23]=to-15 - displays items to 15-th (in view 23) - usefull if combined with from parameter (set[23]=from-2,to-9)
set[23]=page-2-3 - displays second page from 3 (in view 23) - it didvides all matching items into 3 pages and displays the second one. If you do not specify the second parameter (3 in our example), the page will be listlen items long.
set[23]=random-1
set[23]=random-number.........1
selects item(s) to show randomly. If you use the 'random-1' parameter, any item in Active bin is displayed. If You use field_id instead of '1', then the content of field specified by field_id is used as probability to show the item. Let's have two items. The parameter looks like 'random-number.........1'. The first item has the number.........1 filled with number 10, the second with 50. Then the second item will be displayed 5x more offten than the first one. The 'weight numbers' and 'number of displayed items' are unlimited. This feature is very good for banners.
set[23]=banner-2-38
set[23]=banner-2-38-number.........1
set[23]=banner-2-38-norandom
by this parameter you are able to display any view (38 in or case) inserted just after the second (2) item in view (number 23). The item shown in inserted view (38) is selected randomly, possibly with weight specified in weight field (number.........1) - just like in random parameter described above. If you do not want use random item (banner), use 'norandom' keyword in place of 'weight field' (good for displaying nested newsbox). See also banner parameter for slice.php3. The example of included banner is on http://ecn.cz.
set[23]=noitem-Not%20found - redefines the 'Not item found' message in view.
set[23]=slice_id-79a69a0ad73c81ac332b0e8c4c3cea93 - redefines the slice from which the items will be displayed.
set[23]=slices-79a69a0ad73c81ac332b0e8c4c3cea93-45639a0ad73c81ac332b0e8c4c3cea44 - display items from specified two or more slices.
als[alias] user alias definition - you can define your own aliases in url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8 characters long. Don't forgot, that the alias value have to be urlencoded.
Example: als[MY_ALIAS]=Summary%20Page (or maybe better: als%5BMY_ALIAS%5D=Summary%20Page)
defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design Index' for example), it prints 'Summary Page'
nocache=1 URL parameter for pagerefresh - the view is not taken from cache (- no matter if the view is allready cached or not). Cache is updated.


If you want to display some view on page, which is stored on site where is not installed AAs, you have three possibilities.

  1. use remote, remotec or remotec.php
  2. create javascript view - this is good if you want to do something complex with the Javascript.
  3. use the jsview.php3 to display existing view.

This answer covers point 3) - jsview.php3

The usage is easy. Just replace SSI include in original shtml age with the javascript one. The jsview.php3 takes exactly the same parameters as view.php3.

For example, if the old SSI code in page.shtml was:

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

the new javascript code in page.shtml would be:

<script type="text/javascript" src="http://www.apc.org/apps/aa/jsview.php3?vid=2&cmd[2]=c-1-APC"></script>

Normally you will want either a Item listing, Full text or Static Page view.

The slice.php3 is the main script used to display items from database. The alternative for this script is view.php3. The main ussage of slice.php3 script is to include it into some .shtml file by the SSI include command - like:

 <!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6"-->

The following parameters you can add just like url parameters. It is possible to combine more than one parameter. Example:
<!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6&listlen=10&no_scr=1"-->

The slice.php3 is there from the beginning of ActionApps, so some of the parameters are quite old. Such parameters are still implemented, but in many cases it is better to use newer - more powerfull substitution for the parametr. That's why the list is prioritized from the most common parameters (which should be used) to the old parameters (which use is deprecated).

The only way, how to display data from slices, where 'Reading Password' is set. See: http://apc-aa.sourceforge.net/faq/#slice_pwd
ParameterRequiredDescription
slice_idYesid of displayed slice
conds[]Novery usefull for complex conditions - see How to setup the searchform? for conds parameter setting (it can be used as url parameter too - not only form Forms, as described in search section)
Example:conds[0][category........]=Environment&conds[1][category.......1]=Waste
defaultCondsOperatorNoreplaces LIKE for conds with not specified operator - simplified syntax of conds[] uses LIKE operator as default - you can change it by this operator to RLIKE for example (RLIKE is better in many cases - at least it is much faster from database point of view)
Example: defaultCondsOperator=RLIKE&conds[0][category........]=Environment
neverAllItemsNoif set, don't show anything when everything would be shown (if no conds[] are set) - good for search pages, where on the top (or bottom) is searchform - normaly, for the first time (when you did not send the searchform), all items are shown - if you want to have there only blank page intead, use this parameter
sort[]Nosee conds[] - very usefull for complex sorting
Example:sort[0][pub_date........]=d&sort[1][headline........]=a
(a ...ascending order; d ... descending order)
xNothe same as sh_itm, but short_id is used instead (implemented for shorter item url (see 1767 alias))
iviewNochanges the design of index item listing to the design defined in specified view. The view should be of 'Item listing' type.
Example: iview=49
- listing of items generated by slice.php3 will use format-strings as defined in view No. 49
fviewNochanges the design of fulltext to the design defined in specified view. The view should be of 'Fulltext view' type.
Example: fview=48
- the item displayed by the slice.php3 script will use format-strings as defined in view No. 48
dviewNouses specified view for discussions instead of the one specified on 'Slice Admin' -> 'Design - Fulltext' page. (good for testing new discussion view, ...)
Example: dview=18
- view 18 is used as tepmlate for discussion design in this slice
listlenNochange number of listed items in compact view
Example: listlen=10
slice_pwdNo
Example: slice_pwd=VerySecret
no_scrNoif true, no page scroller is displayed
Example: no_scr=1
group_nNodisplayes only the n-th group (in listings where items are grouped by some field (category, for example)) - good for display all the items of last magazine issue
Example: ( group_n=1 )
slicetextNodisplays just the text instead of any output - can be used for hiding the output of slice.php3
Example: slicetext=%20
highlightNowhen true, shows only highlighted items in compact view
Example: highlight=1
als[alias]Nouser alias definition - you can define your own aliases in url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8 characters long. Don't forgot, that the alias value have to be urlencoded.
Example: als[MY_ALIAS]=Summary%20Page (or maybe better: als%5BMY_ALIAS%5D=Summary%20Page)
defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design Index' for example), it prints 'Summary Page'
incNofor dispalying another file instead of slice data (for example some static html file)
Example: inc=/contact.html
items[id]Noarray of items to show one after one as fulltext (ids are the long ones - see sh_itm, but there is special 'x' character before each index).
Example: items[x5462876e8ab29ac95462876e8ab29ac9]=1&items[x65ac876e8a555b29543ea76e8ab29a34]=1 (doesn't matter which value is given to element (1 or 'on' or ...) - good for display of the form, where you select which item to show)
hidefulltext=1Noif you add this parameter to url, the fulltext is not shown when you go to page, where the specific item should be displayed. The discussions under the fulltext are not hidden. It is usefull, if you want to show discussions for the item on separate page. On the other hand, probably better results You can get by using fview parameter.
banner=2-38Noby this parameter you are able to display any view (38 in or case) inserted just after the second (2) item in view (number 23). The item shown in inserted view (38) is selected randomly, possibly with weight specified in weight field (number.........1) - just like in random parameter described above. If you do not want use random item (banner), use 'norandom' keyword in place of 'weight field' (good for displaying nested newsbox). See also banner parameter for view.php3. The example of included banner is on http://ecn.cz.
Example: banner=2-38 or banner=2-38-number.........1 or banner=2-38-norandom
nocache=1NoURL parameter for page refresh - the items are not taken from cache (- no matter if allready cached or not). Cache is updated.
searchlogNoif you add searchlog parameter to the slice.php3 script on some search page, all searches (by conds[]) are logged into database table searchlog. There are logged not only the conds[] parameters, but also the time, which database spent on the query. The access to the log is for superadministrators only, right now. You will find it on 'AA' -> 'Misc - View SearchLog' page in AA admin interface (or you can look into searchlog table in the database).
scr_url=script_nameNoscr_url parameter is answer to problem mentioned in apc-aa-general mailinglist (apc-aa-general mailinglist). If you try to include the slice.php3 into your php3 script by calling include("http://www.sitename.org/apc-aa/slice.php3...");, the page scroller do not work, becouse the called script (slice.php3) do not know from which script it was called. But the scroller should know it - scroller should point to the same page - to the calling one. By scr_url parameter you can define the name of calling script.
Example: include("http://www.sitename.org/apc-aa/slice.php3?...&scr_url=%2Fscripts%2Findex.php");
('%2F' stands for ' / ' character).
sh_itmNoid of item to show - if specified, selected item is shown in full text
Example: index.shtml?sh_itm=01ac1b10fae13c0a61c5292ba72d70b1
restrictNofield id used with "res_val" and "exact" for restricted output (display only items with "restrict" field = "res_val"
Example:restrict=category........&res_val=Environment&exact=1
res_valNosee restrict
exactNoif set, restrict field must match res_val exactly (=) otherwise substring is sufficient (LIKE '%res_val%')
orderNoorder field id - if other than publish date add minus sign for descending order
Example: order=headline........-
timeorderNoif rev - reverse publish date order (less priority than "order")
Example: timeorder=rev
scr_goNosets page scroller to specified page
Example: scr_go=2
encapYes for not encapsulateddetermines wheather this file is SSI included to .shtml file (<--#include virtual="... ) or called directly as slice.php3
Example:encap=false
cat_idNoselect only items in category with id cat_id
Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter
cat_nameNoselect only items in category with name cat_name as substring
Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter
srchNotrue if this script have to show search results
Not supported from AA v1.5
There was changed behavior of string removing in AA v2.6. Now we use much easier steps:
  1. unalias (expand) whole text (replace aliases and any other AA expressions)
  2. remove all specified remove strings
Following worked in AA v2.4 and less, so now is OBSOLETE

Removing of stings works before alias substitution - it never replaces the text filled by user in the field. If you have

=> _#HEADLINE (_#AUTHOR##)

and remove string "()", than it first looks for empty alias content and then removes such aliases.

Let _#HEADLINE = "Hi Ann"
and _#AUTHOR## = "" (empty)

In first step the emtpty aliases are removed:

=> _#HEADLINE ()

Then the "remove strings" are removed:

=> _#HEADLINE

and then the remaining aliases are substituted.

With the concept of Reader management slices introduced it is important that some data are not accessible for reading. This is achieved by setting a reading password for slices containing sensitive data. If you fill the field "Reading Password" in Slice Settings, you must always sent this password as a parameter slice_pwd. This may be done by adding this parameter to SSI includes like

<!--#include virtual="/aa/slice.php3?slice_pwd=the_password&slice_id=xy...."-->

If somebody tries to fetch read-protected data without the correct password, all fields are filled with an error message.

If you are interested, the password is prooved in the GetItemContent() function. For AA control panel pages (Item Manager and Item Edit), the function FetchSliceReadingPassword() is used.

f_v takes a parameter on which certain substitution is done.

 

This FAQ interface was developed by Jason at Commons.ca

APC: Internet and ICTs for social justice and development APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development