Creating Complex Sites With ActionApps
Contents
Using Site Module
Site Module
So far the best approach to build/manage a website of a medium to great complexity with ActionApps is to use the Site Module. It helps combining several views /slices into one page.
We are going to use Econnect's site as an example, to demonstrate the basic principles.
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 primary consideration during the Site Module planning was performance. 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 matter (and it is in most cases up to you) ? will be described in next caption.
The 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>site_xxx.php3</site> 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 wish).
|
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 used for the selection of a region |
|
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 beagain 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
|
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 |
|
{# any text} |
Comments - no output is printed |
The construct could be nested - the level of nesting is unlimited.
Making your site searchable by Google like search engines
~ToDo: Write about howto help google index the site properly
Search friendly URLs
~ToDo: Using mod_rewrite with ActionApps ???
Generating correct title and metadata
~ToDo: Write and advice on generating shtml/site module page headers</aafaqc>
