Difference between revisions of "Syntax"

Revision as of 20:49, 20 September 2005

{<fieldID>} - Reading Field Value

{<variable>} - Reading a Value of a Variable

{const} - Reading Category Values

{view} - Including Views

{switch} - Comparing Values

{math} - Mathematical Functions

{include} - Including External Value

{user} - Reading Logged In User Values

{scroller} - Adding Pagination

{debug} - Debug or Troubleshoot

{#} - Comment

How to use aliases

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_id	short_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_description	description (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:

   • It runs only on http:// sites (https:// is not supported until PHP v4.3.0 will be released)
   • There is also limited size of included file. The default limit is 400kB, but you can change it by INCLUDE_FILE_MAX_SIZE constant in config.php3.
   • Also you should know, that each include generates one more HTTP request to server. That's why also the performance is not as big as for the other alias types.
   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)
    description	can be any text or html and is displayed before result of expression ("#:" mean ":")
    expression	in 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
    end	text to be shown after page numbers
    add	option to be added to page number <a href=".." class="blue10v">1</a>
    nopage	text 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