|
|
Frequently Asked Questions v2 |
| FAQ Main / Answer Detail |
How to use Site Module
Author: Honza actionapps@ecn.cz |
|
Current APC ActionApps are very good for creation of small or not so complex database driven sites. It was not so easy to create complex websites with many cooperating slices and views, so far. The “site module” is the answer for those, who wants to build complex websites using APC AA.
At the time I wrote the text, the only sites driven by “site module” is the Econnect site http://ecn.cz. ChangeNet site http://changenet.sk and example site on Sourceforge http://action.org/slices/. I describe the site module on Econnect's site. You will see, that the principles are similar to all “site module” based websites.
The site module is part of AA admin interface, just like other modules are. You can access it from 'Switch to' selectbox, if you have permission to. Site module allows you to describe structure of the site – you modify there so called sitetree. Sites based on the module do not need any special files (like shtml, ...) - whole site could be managed using AA admin interface (there is no need for FTP access (with one exception – 'main control script' file described later)). How to describe the structure we will see latter in this text.
The first estimation in creation of
site module was the need to write it as fast as possible. The complex
sites used to be sites with many visitors a day. For better
performance is good to be able cache the generated pages. However, in
“pre-site module” approach each user gets its own session
id, which is unique for the user and help us to store the state,
where the user user is within the site (which page on page-scroller
she is on, ...). It is good, but it is extremely hard to cache such
informations. That's why we develop the site module without sessions
variables given to each user. We use “state string”
instead. There we store the state, where the user is within the
website.
State string is variable which we call “apc”
(stands for “Application Pointer Cache” :-) the name of
this variable is given – it have special behavior inside APC AA
(it is automatically added to all links generated by APC AA, for
example).
The “apc” variable is added to all links in
AA so you every time know, where the user was in step before.
For
example: if you get the link http://ecn.cz/index.stm?apc=zzvx1--&...,
you know, that user was in
“news-alerts-all_categories-all_regions-page1” page on
the site. How it is coded into “apc” state string is
another thing (and it is in most cases up to you) – will be
described in next caption.
As you can see, the Econnect's apc
state string consist of seven state variables – each character
in the string is one variable in our case, but it is not a rule (in
fact the fifth state variable - “p” - page could be more
than one character long). All the state variables are defined in main
control file for the site - /module/site/sites/site_xxx.php3 (or its
alternative called (for security reasons) through http:// call). In
this file you define not only the number of state variables, the
regular expression for extraction the variables from apc state
string, but you specify there also the ways, how we have to change
the state. For example, if the site_xxx.php3 file gets the following
url parameter:
http://ecn.cz/index.stm?apc=zzvx1--&p=3
the state variable is changed to apc=zzvx3--, which means that you are on the same webpage, but on the page 3.
Now we describe the variables used on Econnect's site, but keep in mind, that the variables used in your site could be different (if you will).
|
Position in apc state string |
Name of state variable |
Possible states of the variable |
description |
|---|---|---|---|
|
1 |
w (web) |
z,e,n |
Main classification of pages – Econnect's pages are
divided into three webs: |
|
2 |
s (subweb) |
z,m,k,t,a,s (for w=z) |
Each web (w) is divided into subwebs, so for example web z –
zpravodajstvi contains: |
|
3 |
f (filter) |
Any letter |
Primary use of this variable is to select category of shown items (environment, human rights, culture,...), but each page could utilize this variable for its own purpose (category of grant, job, ...) |
|
4 |
r (region) |
Any letter |
The same as f – primary use for region selection |
|
5 |
p (page) |
Any number |
Stores the page number, where user is (switched by page-scroller). Could be more than one character long in our case. |
|
6 |
t (type) |
Any letter |
Special type of output – like 'text only', 'printer friendly', ... |
|
7 |
x (item) |
Any number |
Id of item to show (like 24365) – as you see it could be again more than one character long |
You can use any number of any state variables in your site and combine it together into apc state string. The only thing you have to keep in mind is that apc state string must be splittable into state variables. In Econnect's example we are using following regular expression to get state variables from 'apc state string'.
{w} {s} {f} {r} {p} {t} {x} ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))
Main control file is the only file you will need to edit in the process of site creation. The file contains script (probably in PHP) and its purpose is just parse 'apc state string' into state variables and possibly change the state of the variables based on the parameters it gets through url.
The script is called before any page of the site is displayed. There is easy, but functional example of such script. All comments are inside.
If $apc is not defined, we probably access the main page (like http://ecn.cz).
if( !$apc ) $apc = 'zzvx--'; # initialize 'state string', if not set, yet
Split $apc state string into state variables (for now prefixed by 'o');
if( ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))
list($ostate,$ow,$os,$of,$or,$op,$ot,$ox) = $vars;
else # if the $apc is in wrong format, initialize it
list($ow,$os,$of,$or,$op,$ot) = array( 'z', 'z', 'v', 'x', '-', '-');
Now we have to program the reactions on special url requests. Wherever we are in the site and we click on the link containing w=z (like http://ecn.cz/index.stm?apc=zzvx1--&w=z), we change the state to 'news' section
if( isset($w) ) { # w stands for WEB
switch($w) {
case 'z':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('z','z','v','x','-','-',''); break;
case 'n':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('n','N','1','-','-','-',''); break;
case 'e':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('e','1','1','-','-','-','73161');
break;
}
}
The same with state variable s, but we are switching within the same WEB (variable {w} remains unchanged)
if( isset($s) ) { # s stands for SUBWEB
$os=$s;
$ox=''; # $ow stays the same – we change subweb, not web
$op='1';
if( $old_w != 'z' ) # the format in zpravodajstvi stays the same
$old_f='';
}
Write rule for each possible url request.
if( isset($f) ) {$of=$f; $ox=''; $op='1';} # f stands for FILTER
if( isset($r) ) {$or=$r; $ox=''; $op='1';} # r stands for REGION
if( isset($p) ) {$op=$p; $ox='';} # page
if( isset($t) ) {$ot=$t; $ox='';} # switch to special mode
if( isset($x) ) {$ox=$x;} # item id to display
if( isset($scrl) ) { # page scroller
$pagevar = "scr_".$scrl."_Go";
$op = $$pagevar;
$ox='';
}
Finaly, save the final state of variables into $apc_state array. The key 'state' is used for storing new 'apc state string', other keys of the array are variables, which we can use in site module administration (in next chapter). There should be not only state variables, but any other variables which you want to use in site module, as well.
$apc_state = array ('state' => "$ow$os$of$or$op$ot$ox",
'w' => $ow,
's' => $os,
'f' => $of,
'r' => $or,
't' => $ot,
'p' => $op,
'x' => $ox,
# helper variables used in site module – you can define as many such
# variables as you want
'archive' => (($op>10)? 'archive' : ''),
);
You can find example of such file
in /modules/site/sites/ directory of ActionApps installation
The HTML code for the pages is managed from site administration page. The code is divided into pieces, which is structured into tree structure – called sitetree. The sitetree you can see on the left side of the administration interface. During the displaying of the page, AA starts with the first HTML piece and then goes down and prints the right branch of the tree, based on the state of state variables. The piece of HTML code could contain not only HTML code, but there could be incorporated results of some slice view, as we see later.
We recognize two kind of HTML pieces – 'spots' and 'choices'.
spot is HTML code which is simply displayed. AA prints the contents of the spot and then the evaluation continue with the spot just below. On the other hand 'spot' (as well as choice) could be also the root of some branches of code. You can make spot as root of branch by assigning any (decision) variable to the spot. For example, if you assign variable 'w' to the 'start' spot, you create the root of branches (choices). The evaluation will continue in the branch (choice), where w satisfy the conditions.
As you see, each choice belongs to a spot, where a 'decision variable' is defined. Each choice has defined a condition for the decision variable. AA prints only FIRST choice, which satisfy the conditions. After evaluation of the chioce (printing the output), AA continues with the spot on higher level of the sitetree.
You can use regular expressions in the conditions. You can also combine the condition for more than one 'decision' variable. The conditions are joined by the logical AND operator.
You can use not only HTML cote in the spots, but you can incorporate here the outputs from any slice. The slice output is always controlled by view in site module (we do not use Fulltext or Index in site module). To include slice output use the following construct:
{view.php3?vid=353}
This includes in the output the result of view number 353. Although the {view.php3...} is just language construct (it have only a little to do with view.php3 file), we can use all the well known parameters we know from view.php3. So, the following example is the one, we surely use in our site for displaying the fulltext of the item x:
{view.php3?vid=217&cmd[217]=x-217-{x}}
As you see from the example, we can use another language construct {x}, which is substituted by the content of variable x (x is the state variable defined in 'main control file' in $apc_state array).
|
Syntax |
description |
|---|---|
|
{<variable>} |
Returns content of variable (like {w}) |
|
{view.php3?vid=<vid>&<view parameters>} |
Returns content of view <vid>. View uses the <view parameters> just like the view.php3 script. (like {view.php3?vid=122&cmd[122]=c-1-{f}} ) |
|
{switch(var1,var2,..)val1,val2,..:<printed text1>:val1,val2,..:<printed text2>} |
Returns <printed text1> or <printed text2> or ... based on conditions val1,val2 for variables var1, var2, ... The only first matching text is printed. You can use regular expressions in conditions. (like {switch(w)z:News:e:Econnect:.*:NGO} ) |
|
{# any text} |
Comments – no output is printed |
The construct could be nested – the level of nesting is unlimited.
Last Edit: Aug 17 2011
<aafaq id=1680> ~ToDo: 1680 How to use Site Module </aafaq>
This FAQ interface was developed by Jason at Commons.ca
|
 |
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 |