Yacs handbook Developer's guide

How to develop on top of YACS?

YACS, like many CMS packages, can be extended with additional pieces of software.

Do you have to add a new feature to YACS? Would you like to integrate an existing set of PHP scripts into YACS?

If you have answered Yes to any of these questions this page is for you. Here you will learn how to add any PHP script to a YACS system, and to integrate it to our lovely templating system.

[title]Be included?[/title] Several popular PHP-based CMS have a central entry point, and other scripts are included depending of the work to achieve. Also, the core usually triggers automatically an array of services such as: database connection, user authentication, template rendering and cache management.

Because of the way they are shaped these kind of systems are extended through modules that are included as well. Of course, most advanced packages will have sophisticated tools to manage all these included files.

For example Drupal is using this approach for its extension. By the way Drupal has refined the concept with reflection and other very clever things aiming to make the most out of software objects.

Because they are used to this way of proceeding many software programmers are asking me: How to develop modules equivalent to Drupal with YACS?

The first answer is simple: Strictly speaking, YACS modules are not exactly equivalent to those of Drupal.

The second answer is: What you can actually do is either to include YACS as a library, to overlay articles, or to hook your script. Let give a look at these various options.

[title]Include YACS![/title]

Are you starting from existing scripts that have to be integrated into YACS? It is likely that you will have to add some lines of code at the beginning and at the end of each of them.

Hopefully the minimum skeleton used to invoke the rendering engine is really straightforward. For example, to create a script that says Hello World you would put following code into control/hello.php:

// common definitions and initial processing
include_once '../shared/global.php';

// load the skin

// set display attributes
$context['page_title'] = 'the Hello World page';
$context['text'] .= 'Hello Word, I am happy to be there!';

// render the skin

We have executed the previous script on your behalf, to save your precious time:

To learn more on attributes handled by YACS templates look at skins/index.php.

[title]Overlay articles[/title]

If, during some analysis of your needs, you end up with the conclusion that adding some fields to an article would suffice, then consider overlays as the faster track to deliver.

For example, YACS come with standard overlays to specialize articles into recipes or into polls. Other overlays, while not being publicly available, have been developed to support consulting assignments or car races.

Overlay data is saved along standard articles as a serialized snippet. The encoding and decoding of this field requires a specialized class. The overlay interface masks these details and offers convenient methods to create, access and save piggy-back data.

Browse following links to learn more on this topic: - The overlay interface - Cooking recipe - Poll with a sample at Why will you select YACS as your next web platform?.

[title]Hook your script[/title]

Simply speaking, a hook is a straightforward way of integrating some scripts on a particular event.

To hook into YACS you will have to write a script named hook.php or <what_you_want>_hook.php and to drop it somewhere under the installation directory.

Then trigger control/scan.php to look for all available hooks and to bind them to YACS.

YACS supports following types of hooks:
* 'link' means that a link to the hooking script will be inserted into the resulting page. This kind of hook is used in the control panel (control/index.php)to extend the list of configuration panels, and to list non-core modules.
* 'include' means that the hooking script has to be included. This kind of links is used in the script that populate the database (control/populate.php) for example.
* 'serve' to bind one web service to services/xml_rpc.php or to another RPC script. For example, look at the script that validate Drupal-like authentication requests (services/xml_rpc_drupal.login_hook.php).
* 'call' to link some remote procedure call to one web service

Some hooks are described in the script control/scan.php. You can also trigger this script from your control panel to list hooks that have been actually installed at your system.