Documentation Mailing Lists FAQ Frequently Asked Questions v2

Topic: Site Module

Site Module

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.

Idea - State and sessions

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.

“apc” state string

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: z – zpravodajstvi (news) e – econnect n – nno (NGO related news)
2	s (subweb)	z,m,k,t,a,s (for w=z) 1,2,3,4,5,6,7,8,9 (for w=e) N,F,P,I,J,V (for w=n)	Each web (w) is divided into subwebs, so for example web z – zpravodajstvi contains: |z – news k – comments t – press releases ...
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

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

Site administration

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

a) spot

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.

b) choice

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.

Incorporating database views into output.

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

Language construct to be used with site module

The construct could be nested – the level of nesting is unlimited.

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