Extending and Hacking ActionApps

Creating custom alias function

This method should be used when the function you need is very proprietary (not worth contributing to the main AA code). You can create or edit the /include/usr_aliasfnc.php3 file, which is automaticaly included (if exists). There you can define your own alias functions. The function name must be prefixed by 'usr_' prefix. The function has three parameters:

• $columns - array of content of each field in item (for example
  $columns[headline........][0][value] = "This is item title"
  
  • value last array dimension - select between value and flag. Value is field content flag could be FLAG_HTML | FLAG_FEED | FLAG_FREEZE | FLAG_OFFLINE | FLAG_UPDATE
  • ' - used for multivalue fields (as categories in some slices). For single values we use just 0, for multivalues we use 0, 1, ...
  • headline........ - field id
    
• $col - field id of column for which the alias is definned
  
  
• $param - parameter passed to function from textfied in alias definition (just like usr_cz_date:1). The name of function is in param too!!!

The example listing of /include/usr_aliasfnc.php3 (the file should not be committed to CVS, because it is very proprietary and the content should not be shared between installations):

<?php //usr_aliasfnc.php3  

    /** Prints czech date (for Ekolist pages) 
     *  @param columns - array of all field values for all ifelds in current item
     *  @param col     - fileld id of field, for which the alias is defined
     *  @param param   - possibly parameters to alias function passed in alias definition parameter (usr_cz_date:parameter) 
     */
    function usr_cz_date($columns, $col, $param="") { 
        $dte     = $columns[$col][0][value];
        $month   = array( 1 => "ledna", "unora", "brezna", "dubna", "kvetna", "cervna", "cervence", "srpna", "zari", "rijna", "listopadu", "prosince");
        $weekday = array("nedele","pondeli","utery","streda","ctvrtek","patek","sobota");
        $m       = $month[ date("n", $dte)];
        $end     = ( !$param ? "" :  " (". $weekday[ date("w", $dte) ]. ")");
        return date("j", $dte) .". $m ". date("Y", $dte). $end; 
    }
?>

Such alias function can be called by defining new alias for some field. Just define alias name (as obvious), alias function should be "[#f_u f_u - user function]" and the parameter should be the name of the function ("usr_cz_date" in our example). It is possible to pass parameters to the function. The parameters are separated by colon (usr_cz_date:parameters).

If you need to parse $param, you can use AA function ParamExplode($param) to split the arguments (it takes care of #:)

Example:

list($function_name, $text, $group) = ParamExplode($param);

The advantage may be that all aliases are expanded, so in case

{alias:publish_date....:f_u:usr_i18n_date:_#HEADLINE}

you will not get the "_#HEADLINE" string, but a headline of the current item (if such alias is defined).

Cron - how to automatically run tasks on given time?

The script cron.php3 - similar to Unix cron - is able to run PHP scripts on given time. If you want to send e-mail notifications if some condition is satisfied or if you want to exchange items between slices regularly, you will find it useful.

The reason for this script to exist is that it's not easy to run PHP scripts by the Unix cron. It also allows us to use admin interface (AA -> Misc - Cron) to add/modify new tasks to run.

If you want to run some task on given time (like running admin/xmlclient.php3 for Cross Server Item Exchange each 15 minutes), you have to do two steps:

1. add new task on cron admin page (AA -> Misc - Cron)
2. make you sure the cron.php3 is periodically started from unix cron

1. Add new task on cron admin page

The task you can set/edit on cron admin page (AA -> Misc - Cron). The fields (their names are taken from PHP getdate()) have the following meaning: Let's call time units all from: minutes, hours, mday (month day, 1-31), month, wday (week day, 0-7, where 7 and 0 both mean Sunday). You may use three-letter month and week day names (like "jan","feb","sun","mon"). A time unit may be set to:

*	not set - jump over this field
10	number: run only when time unit equals
1-5	range: run when time unit equals 1 or 2 or 3 or 4 or 5
0-59/15	range with step: run when time unit (minutes in this case) equals 0 or 15 or 45
5,15-25/5,40	you may combine numbers, ranges and ranges with steps, separated by comma

• Don't write any whitespace (spaces, tabs) into the time units.
• Write script name into the "script" field. Use relative path from apc-aa home dir, e.g. "include/myscript.php3".
• If you need to send any parameters to the script, write them into the "params" field in form "var1=value1&var2=value2".

The task table is allready prefilled on APC ActionApps setup, so you should see something like:

 time script params * 1 * * * misc/alerts/alerts.php3 howoften=daily&lang=en (Alerts - daily diggest) * 1 * * 1 misc/alerts/alerts.php3 howoften=weekly&lang=en (Alerts - weekly diggest) * 1 1 * * misc/alerts/alerts.php3 howoften=monthly&lang=en (Alerts - monthly diggest) * 1 * * * misc/alerts/admin_mails.php3 (Alerts - sending of subscription e-mails,...) * 8,23,38,53 * * * admin/xmlclient.php3 (CSN - Item Exchange) 

(it is just an example - the set of task could be changed in next release of ActionApps)

2. Start cron.php3 periodicaly from unix cron

This must be done by a system administrator (i.e. someone with root shell access), but only has to be done once no matter how many task are sheduled then.

In order we can shedule tasks from ActionApps we must run periodicaly the script cron.php3 (based in root apc-aa install directory). It is not so easy to start php scripts directly from unix cron, that's why you should use aa-http-request shell script (based in misc/ directory), which will start cron.php3 script for you.

The instructions for setup of the aa-http-request script is also inside the script. For setup follow the nex few steps:

• For security reasons it is better to move the aa-http-request script to some directory, where webserver don't have access to. For example to the directory /usr/local/myscripts/aa-http-request
• Open the aa_http_request script
• Modify the HOST variable to point to your server where ActionApps are installed
  Example: HOST=aa.ecn.cz
• Modify the AADIR variable to be filled by the path to root of AA instalation from server root
  Example: AADIR=/aaa (for AA installed on http://aa.ecn.cz/aaa)
• Set LYNX or PERL to absolute path of lynx or perl if you have either of them. If neither are set, then the script will try telnet, which will not work if your server uses virtual hosts.
  Example:
  LYNX=/usr/bin/lynx
  PERL=/usr/bin/perl
• Save the changes and close the script
• In order to run this script from cron, it must have executable privileges
  ( chmod 755 aa-http-request )
• Test it, by running aa-http-request. If you have already configured some task on AA -> Misc - Cron page (you probably have), then check if 'last_run' column is changed for sheduled tasks
• Set the crontab so the script is started each 15 minutes e.g.
  crontab -e
  and put the line pointing at the aa-http-request:
  1,16,31,46 * * * * /usr/local/myscripts/aa-http-request > /dev/null

How do I get rid of the "?" by each input field

The ? only shows if their is a URL in the morehelp field. This is setup automatically to be http://aa.ecn.cz/aa/doc/help.html.

You can remove it on fields individually via Admin->Fields->anyfield -> More help and deleting the text which is there.

If you are too lazy to do this on every field, then ask your system administrator to run:

UPDATE field SET input_morehlp='' WHERE input_morehlp = 'http://aa.ecn.cz/aa/doc/help.html'

For future refence, the function that creates this link to help is in include/formutil.php3 : function PrintMoreHelp

How can I control which fields are fed, and whether they are editable

When you write an item which goes into the Active bin or when you approve an item, the feeding function is invoked. This function finds all slices where the item should be fed (depending on current feeding permissions ("Admin" -> "Content pooling - Import & Export") and feeding setings ("Admin" -> "Content pooling - Filters")). The feeding goes deeper and deeper between the slices until a cycle is detected or feeding into Holding bin is set.

Feeding one item from one slice to another means:

• The content of each field is copied to the destination slice (there is one exception - see the STATE_UNFEEDABLE flag in following text)
  
  
• The content is copied including the HTML codded / plain text flag
  
  
• The field is fed to the destination field with the same field_id as default (headline........ goes to headline........ field). This can be changed in the feedmap table, where you can map fields to another ones (See "Admin" -> "Content pooling - Mapping"
  
  
• flag FLAG_FEED is set for each stored value (see FLAG_* definitons in following text)

Let's look in the constants.php3 file:

# content table flags
define( "FLAG_HTML", 1 );
define( "FLAG_FEED", 2 );
define( "FLAG_FREEZE", 4 );
define( "FLAG_OFFLINE", 8 );
define( "FLAG_UPDATE", 16 );

# states of feed field of field table
define( "STATE_FEEDABLE", 0 );
define( "STATE_UNFEEDABLE", 1 );
define( "STATE_FEEDNOCHANGE", 2 );
define( "STATE_FEEDABLE_UPDATE",3);
define( "STATE_FEEDABLE_UPDATE_LOCKED",4);

# relation table flags
define( "REL_FLAG_FEED", 2 ); # 2 - just to be compatible with content table


There you see how the various flags can be set. The most important are the flags for the field table. For each field you can set whether this field is

• feedable (STATE_FEEDABLE) - the content of this field is copied to the new slice and user in the new slice can freely edit it
  
  
• unfeedable (STATE_UNFEEDABLE) - the content of this field is never copied to the new slice
  
  
• feedable, but locked (STATE_FEEDNOCHANGE) - the field is copied to the new slice, but the flag FLAG_FREEZE is set for the field, so the user in the new slice can display the content of this field, but she can't change the value
• feedable with update(STATE_FEEDABLE_UPDATE) - the same as STATE_FEEDABLE, but if the content of source field is changed, the content of the destination field is updated too. Editor of the destination slice can change value of such a field, but when someone changes the field in the source slice, the value is rewritten.
  
• feedable with update and locked (STATE_FEEDABLE_UPDATE_LOCKED) - the same as STATE_FEEDABLE_UPDATE, but the editor of the destination slice can't change the value of this field.
  
  

These settings can be done on the "Admin" -> "Main settings - Fields" -> "Edit" -> "Feeding mode" page, where you can set for each field:

• Feed (= STATE_FEEDABLE) - copy the content of the source field once (to the destination field)
• Do not Feed (= STATE_UNFEEDABLE) - do not copy the content of this field to the destination slice
• Feed locked (= STATE_FEEDNOCHANGE) - copy the content once, but forbid editors of the destination slice to change the value of this field
• Feed & update (= STATE_FEEDABLE_UPDATE) - copy the content and update the content of the destination field each time the source field is changed (content sharing)
• Feed & update & lock (= STATE_FEEDABLE_UPDATE_LOCKED) - the same as before, but editors of the destination slice can't change the content

Depending on field table flags, the flags for content table are set:

• FLAG_HTML is allways copied from the source field
  
  
• FLAG_FEED is allways set for fed fields (currently it has no specific use - we just mark the fed content)
  
  
• FLAG_FREEZE is set if the source field has STATE_FEEDNOCHANGE flag set. In other cases this flag is unset. All fields with FLAG_FREEZE are never displayed in the input form so they can't be changed by the user in the destination slice.

After copying the contents, the relation table is updated. This table holds information about the feeding tree (from which item is the content fed to another). The relation table will be used for another purposes in future too (for holding discussion threads, ...), so each record for feeding if flagged as REL_FLAG_FEED.