Syntax
Contents
- 1 Curly Brackets Syntax Introduction
- 2 {<fieldID>} - Reading Field Value
- 3 {<variable>} - Reading a Value of a Variable
- 4 {const} - Reading Category Values
- 5 {view} - Including Views
- 6 {alias} - Using alias functions
- 7 {switch} - Comparing Values
- 8 {preg_match}- Pattern Matching
- 9 {math} - Mathematical Functions
- 10 {include} - Including External Page
- 11 {user} - Reading Logged In User Values
- 12 {scroller} - Adding Pagination
- 13 {formbreak} - Label tabs of a multipage input form
- 14 {@} - Loop through multiple values
- 15 {debug} - Debug or Troubleshoot
- 16 {#} - Comment
Curly Brackets Syntax Introduction
Note that there are two different ways of accessing the actual value of a field in your design templates. This reference explains the curly bracket syntax, which we encourage you to use extensively, as it's somewhat cleaner. The discussion about the actual differences can be found at the beginning of the Designing_Output_Templates chapter. The {} syntax, also sometimes called in-line alias definition marks up a special action that needs to be taken when rendering the output of a design template. The action is:
Evaluate the expression between { and }, and substitute the whole string including the brackets with the actual result of the evaluation.
Complicated as it may sound, the simplest example which is at the same time the most common usage is this
{headline........}
which simply says:
- lookup the value of headline........ - that's the evaluation bit
- and print it - that's the substitution bit
You will see below that an expression enclosed in {} can contain another (nested) expression. For interpreting and designing more complicated expressions correctly, you must remember that ActionApps interprets the innermost expression first.
Below is the list of all the expressions you can use. The developers appologize for the inconsistency in paramater separators - sometimes :, sometimes ?, sometimes ( . Eh...
{<fieldID>} - Reading Field Value
Syntax:
{<fieldID>}
where <fieldID> should be 16 chracters long field id which exist in the slice the template is applied to. ActionApps reads the value of that field for a particular item and replaces it (prints it out) as it is in the database.
Example:
{text...........1}
{<variable>} - Reading a Value of a Variable
Syntax:
{<variable>}
where variable must be a name of an existing variable defined in site module (apc_state) or through als[variable] the url parameter.
Example: Say you have defined the alias through the
...view.php3?vid=123&als[heading]=My Page
then use
<h1>{heading}</h1>
If the variable doesn't exist, the result is an empty string.
{const} - Reading Category Values
ActionApps Categories and Constants (the obsolete,simple ones) are stored in a special table (not in slice, unlike preferred Related Items). The relation between the table that holds the content and the table that holds the list of constants is done through the "value" of the constant. If you need to lookup another column from this table and you only know the value, you use this function.
Syntax:
{const_<column_name>:<fieldID>}
Where <column name> one of the valid column names listed below, and <fieldID> is a valid Term#Field_IDs which should have a category group associated to it through the Field properties, in other words should be one of the input types that allow user to select from a list of options.
Example:
{const_name:category.......1}
displays name of constant stored in field category.......1
The list of valid values for <column_name>:
| 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) |
{view} - Including Views
You can include the output of any AA view into any design template. Most of the time you will be using this to include your views in the site module. But you can also can include a view within another view, include the output of a certain view as a parameter for any function etc. Put simply, use anywhere in ActionApps where {} syntax is valid. This a powerful function (with a really bad name).
Syntax:
{view.php3?vid=<View ID>[¶meter1¶meter2&...]}
Where <View ID> must be a valid view ID. You can pass URL parameters to the view as if you were calling it via URL, but they can also be expressions enclosed in {}, which will evaluate first.
Example 1:
{view.php3?vid=123}
Returns content of view 123.
Example 2:
{view.php3?vid=122&cmd[122]=c-1-{f}}
f is a variable, a value of which will be passed to the 1st condition of the view 122
Example 3:
{view.php3?vid=33&cmd[33]=x-33-{relation.......1}}
use this for displaying related items
{alias} - Using alias functions
Modify the value through an alias function. 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, any other field ({headline........}) or any other in-line alias definition. There is no limit in level of nesting.
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'. ...
{switch} - Comparing Values
Switch extends the functionality conditional expressions, otherwise managed f_c function. Switch provides more flexibility through giving more options, regular expressions, etc. Switch takes it's logic from the php switch statement, although the syntax is different.
Syntax:
{switch(<expression>)<value1>:<output1>:....:<valueN>:<outputN>[:<default_output>]}
where
-
<expression>is any valid AA expression (you can/will use {} in there) -
<value1> - <valueN>is the regular expression value which the result of the<expression>will be compared with -
<output1> - <outputN>is the result of the {switch} expression if the<value1>matches the result of<expression> -
<default_output>is the result if no match is found among<value1> - <valueN>
Note: Because ':' is used as a separator, if you need to use ':' in either <value> or <output> you must prefix it with a '#' escape character, i.e. "#:"
Example:
{switch({number.........1})1:one:2:two:[3-7]:more:too much}
ActionApps evaluates the <expression>, which is the value of the >number.........1 field in our case. If content of the field is equal to 1, the 'one' is the result and will be printed. Because <values> are regular expressions, 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 process goes through values from left to right, the the first match is taken and no further evaluation is performed.
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:Continuous grant::12/11/2007}
Display of phone number, if specified (note that '#:' is an escaped ':' to distinquish from the argument separators):
{switch({con_phone......1}).+:Tel#:{con_phone......1}}
.+ (or just . (dot)) means non empty string in regular expressions. If you are not familiar with "regular expressions", please look at any tutorial. Regular expressions are very powerfull and you will find it usefull not only in ActionApps.
Remember, that regular expressions searches for substring, so if you want to compare exact value, there are two possibilities:
{switch({number..........})^14$:exactly fourteen}
^ is begin of the line in regular expressions, $ is end of line
{switch(x{number..........}x)x14x:exactly fourteen}
Used a trick with added two random characters in the expression (since expression could be any AA string)
Last example the flexibility of the <expression>. IT can be any valid ActionApps expression, and the of nesting of curly bracket expressions is unlimited.
{switch({disc_count......})[1-9][0-9]*:There is discussion under this item}
{preg_match}- Pattern Matching
Useful for extracting parts of the string that match a certain pattern.
Syntax:
{preg_match:/<pattern>/:<subject>}
where <pattern> is a perl regular expression as described in php preg_match pattern function manual, and <subject> can be any valid ActionApps expression.
Example:
{preg_match:/[0-9]*/:some text with number 25452 in it}
which returns 25452 (based on specified regular expression)
{math} - Mathematical Functions
This function allows you to perform some computatation on the values stored in the slice.
Syntax:
{math(<result_formatting>)<description1>:<expression1>:...:<descriptionN>:<expressionN>}
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 ":") |
<expression1>
|
in expression you can use numbers (decimal separator is ".". Aliases can be used of course) and characters: + - / * ^ . ( ) |
Example 1 - calculate points in a quiz
<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 (respectively):
<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
{include} - Including External Page
You can use this directive for an inclusion of a remote file or an output of some script
Syntax:
{include(<url>)}
which will be replaced by the output of the HTTP request for the <url> (by the page the URL points at). It a bit like the ssi include directive, or in fact more like a php include statement.
Example 1:
{include(http://www.google.com/)}
Include Google search form in your page.
Example 2:
{include(cgi/counter.pl?id=222)}
as you see here, you can use relative links, although the usefullness of this is questionable since you may not know which page the output of the template will appear at.
Example 3: 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)}</code>
Limitations:
- It runs only on http:// sites (https:// is not supported before PHP v4.3.0)
- 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, so it may cause performance problems.
{include(file)}
{include:file} or {include:file:http}
{include:file:fileman|site}
{include:file:readfile[:str_replace:<search>[;<search1>;..]:<replace>[:<replace1>;..]:<trim-to-tag>:<trim-from-tag>[:filter_func]]}
{user} - Reading Logged In User Values
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 in user by {user:} construct.
The syntax:
{user:<keyword or field ID>}
where <keyword or field ID> are explained on examples below:
| {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. |
| {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.
{scroller} - Adding Pagination
If you want to use page scroller (Page 1 | 2 | 3 | ... ) in view which is a part of the site build on Site Module, you can use this construct. You simply add {scroller} to the bottom of the view which you are calling from the site module - most likely the 'Bottom HTML' field. Example : {scroller:Page ::class="blue"}
Syntax :
{scroller:<begin>:<end>:<add>:<nopage>}
where:
<begin>
|
text to be shown before page numbers |
<end>
|
text to be shown after page numbers |
<add>
|
string to be added inside the page link, e.g. class= |
<nopage>
|
text to be shown wnen there are (yet) no pages (so the scroller is not displayed) |
Then you use the view include, and also utilize the {p} state variable which stores the page number in the site module's spot: {view.php3?vid=32&set[]=page-{p},listlen-10}
if ($scr_725_Go) { // there is probabaly a better way of doing this
$p=$scr_725_Go;
}
Is there a better way ?if (isset($scrl)) {
$pagevar = "scr_".$scrl."_Go";
$apc_state['page'] = $$pagevar;
}
{formbreak} - Label tabs of a multipage input form
~ToDo: Describe {formbreak} usage
Syntax:
{formbreak:<current_tab_name>:<next_tab_name>:...}
Allows to specify the name for all tabs, when using inputform formbreaks. The names are separated by ":" and are applied to current and then other tabs. It is useful mainly for the last tab.
{@} - Loop through multiple values
Example:
{@category.......1(const_name,const_value,_#MY_ALIAS):,:_#1 _#2 _#3}
~ToDo: Add the documentation for {@ } loop
{debug} - Debug or Troubleshoot
Syntax:
{debug}
Because it is sometimes unclear which substitutions are available at a certain point, {debug} will output some hopefully useful information
{#} - Comment
Syntax:
{#<comment>}
as addition to in-line aliases you can {# make comments} which are not displayed in the resulting html code {the result of this expression is always an empty string). It could be nested again, so you can {# comment out _#ALIASES_ as well as fields {headline........} or alias definitions } - nothing of it will appear in the result.
