Documentation: control/scan.php

control/scan.php - Scan subdirectories for hooks

This page is used to configure hooks. Its usage is restricted to associates.

Simply speaking, a hook is a straightforward way of integrating some scripts to any existing system.

What are the hooks supported by YACS?

At the moment YACS supports following hooks:

'control/populate.php' is called from the control panel to populate a new server
'control/setup.php' is called on each update of the database schema
'finalize' is called after the processing of any request
'publish' is called on article publication
'tick' to trigger periodic jobs

'control/populate.php'

This hook is triggered in the script control/populate.php during the first installation, and also on demand when necessary.

This hook has been created to fully support external modules of YACS that are based on specific tables.

'control/setup.php'

This hook is triggered in the script control/setup.php during the first installation, and also on each subsequent upgrade of the YACS software.

This hook has been created to fully support external modules of YACS that are based on specific tables.

We have also used it internally for some back-end modules that are provided with YACS, but that could be replaced by other more powerful pieces of software. Take a look at agents/browsers.php, agents/profiles.php, or agents/referrals.php for such examples.

'finalize'

This hook is called after page rendering, just before exiting from called script.

It is triggered at the end of the render_page() function (global.php) for pages built upon the templating system of YACS. This hook is triggered directly in other scripts (services/blog.php, ...), in order to integrate non-interactive scripts in finalizing steps as well.

This hook has been created mainly for statistics purpose. Look at agents/browsers.php, agents/profiles.php and agents/referrals.php for self-explanatory examples provided with YACS. Or create hooks of your own to improve computed figures...

'publish'

This hook is called on article publication, either through the on-line publication script (articles/publish.php), or on post from w.bloggar (see script services/blog.php).

By default, this hook pings several sites to notify them that your site has changed. The sites that will be advertised are listed in the table for servers.

To know servers that are pinged by default go to script servers/populate.php.

'tick'

This hook is triggered regularly in the script cron.php (the 'standard' cron), or on each script rendering (look at shared/global.php, the 'poor man' cron).

This means that scripts triggered on tick should make no assumption regarding delays between invocations.

With no additional configuration this hook calls Feeds::tick() to read XML news from feeders.

How to use hooks?

As a wise programmer, you want to open your software to others. Cool! Hooks are perfectly suited for that.

Firstly, select a unique id for you hook. We recommend to derive the id from the script name. For example, the hook to integrate configuration panels into the script control/index.php has the id control/index.php#configure. Simple enough, no?

Secondly, select a type for the hook.

'link' means that a link to the hooking script will be inserted into the resulting page
'include' means that the hooking script has to be included
'call' to link some remote procedure call to one web service
'serve' to bind one web service to services/xml_rpc.php or to another RPC script

Thirdly, load the hook. Use the file resulting from hook scanning. For example, here is an excerpt from control/index.php on the hook used to link to additional configuration panels:

// the hook for the control panel
include_once '../shared/hooks.include.php';
if(is_callable(array('Hooks', 'link_scripts')))
    $context['text'] .= Hooks::link_scripts('control/index.php#configure', 'bullets');

Another example is an excerpt from control/setup.php on the hook used to create/alter extra tables of the database:

// the setup hook
include_once '../shared/hooks.include.php';
if(is_callable(array('Hooks', 'include_scripts')))
    $context['text'] .= Hooks::include_scripts('control/setup.php');

How to describe a hook?

A hook is a php script file that describes some extension to the system.

For example, the scripts that handle collections in YACS have a hook to integrate the configuration panel of collections into the control panel of the system. Here is an excerpt of collections/hook.php:

$hooks[] = array(
'id'        => 'control/index.php#configure',
'type'        => 'link',
 'script'    => 'collections/configure.php',
'label_en' => 'Collections',
'label_fr' => 'Collections' );

Obviously, this hooking script has the simple task to append an array of attributes to a public variable named $hooks.

Another usage of hook is to include additional code to an existing script. For example, here is a hook to create additional tables during the setup of the database. Note that it is possible to call one function in the included file. This is an option however.

$hooks[] = array(
    'id'        => 'control/setup.php',
    'type'        => 'include',
 'script'    => 'overlays/assignment.php',
    'function'    => 'Assignment::setup',
    'label_en'    => 'Assignments',
    'label_fr'    => 'Assignations',
    'description_en' => 'Create tables for assignments.',
    'description_fr' => 'Cr&eacute;ation des tables pour les assignations.',
    'source' => 'http://www.yetanothercommunitysystem.com/' );

How to install a hook?

Typically an extended YACS environment will have several files hook.php spreaded over the file system. Of course, it would be not so efficient to browse the entire file system each time some hook is required. Therefore, hooks have to be installed through the control panel, and this is exactly the job of the script control/scan.php. When triggered, control/scan.php will look for files named 'hook.php' or '<some_label_here>_hook.php' almost everywhere under the YACS installation directory. It will then compile gathered information into the single file shared/hooks.include.php.

Configuration information

Configuration information is saved into shared/hooks.include.php.

The file shared/hooks.include.php.bak can be used to restore the active configuration before the last change.

This script does save hooking information even in demonstration mode, because of software updates. There is no known security issue with this way of proceeding anyway.

Hooking information is also saved in the file shared/hooks.xml for further processing. For example, this file can be read by services/index.php to list web services installed on this system.

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

include_hook()

function include_hook($path)

$path -