Xaraya

Voici un document que j'ai écrit pour introduction pour Xaraya 0.9.x comme introduction à la configuration de Xaraya. Il est probablement toujours d'actualité.

- How Xaraya works -

 ------------------



Why should you care?



Well, Xaraya is more than a simple Content Management System. If you need something more than an articles repository, you'll want to take advantage of Xaraya's extensibily, use your own fields, write your own template.



Understanding the basic of Xaraya's inner workings helps a lot in this task.



Xaraya is based on a MVC (Model, View, Controller) model:

- Model: the core logic of the application,

- View: the end-user interface,

- Controller: the link between the user request, the Model and the View.

When you request a web page, the system analyses the URL (Controller) and calls the right function (Model), then passes the resulting data to the right template (View).







The Controller

==============



So each time you enter a URL, the Controller decomposes the URL into components:

- module: Xaraya is composed of several module, each providing a set of features. A module can depend on other modules.

- type: user (default) or admin. This is a basic separation between the functions aimed at the visitors, who view content, and the authors, who modify contents and change the configuration.

- function name

- function arguments



The URL can be expressed using several patterns. The two most common are:

1) ?module=modulename&type=useroradmin&func=functionname&arg1=val1&arg2=val2...

eg: 

2) /modulename/functionname/?arg1=val1&arg2=val2... (only works for user functions)



"/modulename/" is called a "Short URL". Short URLs are usually not active by default.



In those patterns, the function and template to use are found using the directory structure of the module. Here is a short description of this structure:



The Xaraya main directory ("html") contains a "modules" directory. Each subdirectory is a module:

/html/modules

  /articles

  /xarpages

  /roles

  ...



In a module, you can find among others:

/html/modules/modulename

  /xaruser

  /xaradmin



'xaruser' and 'xaradmin' contain PHP files who name are the function you can call.

For example, when you access http://yoursite/index.php?module=articles&func=main, the function called will be html/modules/articles/xaruser/main.php

Note that since the 'user' type is the default, you needn't precise it.



The function is not called directly; as you can see, "index.php" is the site entry point. 'index.php' calls the right function, but also generates the surrounding presentation, and offer a generic framework for the modules, including database access wrappers, user session management, access to configuration variables, etc.



Now that the right function is called, we enter the Model part.







A brief introduction to the Model

=================================



For now, all you need to know is the the function gets its parameters from the URL, does some black magic, and then return a set of values to be displayed in the browser.



Reading a list of values would not be very convenient. Instead, we need a way to display a meaningful, well presented webpage containing that information. That's what templates are for.







The templates

=============



Templates are basically XHTML files, with a few preprocessing instructions interpreted by Xaraya.





In the module, there is a 'xartemplates' directory:

html/modules/modulename

  /xartemplates



Inside, you can see '.xt' files, ie the templates.

The .xt files are named using the pattern:

type-functionname.xt



For example, the template for http://yoursite/index.php?module=articles&func=main (and thus for html/modules/articles/xaruser/main.php) is html/modules/articles/xartemplates/user-main.xt





The reference for templates is in the BlockLayout RFC at xaraya.com (as of 2005-06-24, located at http://www.xaraya.com/documentation/rfcs/rfc0010.html).



Instructions include inserting values passed by the function, iteration over such values, conditionals, calls to other templates, calls to other modules, and more.



Under the hood, the template is converted to a PHP files that is then cached for efficiency. It is then no surprise that much of what you write in template instructions has a PHP flavor. For example:

<xar:if condition="php code"/>

You can even trick a template into executing PHP code:

<xar:set name="variable_name">1; php_code</xar:set>

This is something sometimes necessary, but you should use another way to do the job whenever possible, especially if you do not plan to hack and update your template on a regular basis.



Once the template is converted to PHP, the resulting PHP file is executing, and its output is inserted in the site-wide template.



Sometimes though, the values passed by the URL-called function are not enough for your purposes. In theory, this should not happen: the MVC model should provide enough information to the View / template part so that no processing besides displaying information is needed here.



In practice, you'll want to display more information, and you're confronted to a dilemna: either you modify the module to suit your need, either you break the MVC model.

Modifying the module for something very specific is usually not an attractive task, and will cause troubles during upgrades. Modifying templates is less risky. That's when you start adding PHP code to your template...



To mitigate this problem however, it is possible to restrict that PHP code to a few calls to the module's API, ie a set of useful functions available to the other modules and the templates.



So let's take a look back at the Model:







The Model, continued

====================



Each module can work and organise files differently, of course. However, there are a few conventions. What is interesting for us is to look at two other directories in the module structure:

html/modules/modulename

  /xaruserapi

  /xaradminapi



Like /xaruser and /xaradmin (without the "api" part) from the Controller part, they contain a set of PHP files, each providing not a user-visible interface in the website, but an internal function. Each file usually starts with a comment describing the purpose of the function.

Do not confuse these functions with the ones in xaruser/ and xaradmin/: xaruser/ and xaradmin/ contain entry points to specific interfaces in the website, and are called via the URL.

xaruserapi/ and xaradminapi/ contain internal functions related to the way the modules performs its job.



To call such a function, you use the xarModAPIFunc PHP function, which works in a manner similar to how the Controller does:

xarModAPIFunc(modulename, type, functionname, array(arguments))



For example, xarModAPIFunc('articles', 'user', 'get', array('aid' => 12)) will return an array containing information about article number 12.

(Note that the 'type' part is mandatory here.)



So if in your template you get a list of articles IDs and title, but if you also need their summary, you could grab them that way.







Sum up

======



With these explanations you now should be able to understand the modules structure and know what file you need to hack to change a given page's presentation of behavior.







Miscellaneous precisions

========================



* I mentioned only two URL patterns. What are the others?



Well, they look like one of /modulename/funcname, but:

- funcname can be caught by the module and interpreted as something else than a function name. For example, the article module can use this to interprete 'funcname' as the title of the article to display.

- modulename is not necessarily a real module name either; modules can register aliases and give a special meaning. For example, the article module can register a publication type as a module alias. Hence, '/articles/news/12' becomes the shorter '/news/12'. the xarPages module uses a similar technique to mimics a static pages hierarchy by registering a given page name as a module alias.



* What about writing my own module?



This section presented enough information to start modifying templates. However, this is also parts of the basics to write a module (or even hack the Xaraya core ;)). You need a few more information though. Check the Module Developer Guide (MDG) for more information. A copy of MDG is shipped in the docs/ directory of the Xaraya official distribution.







- Where to get help -

 -------------------



Check http://www.xaraya.com/index.php/base/support
 (docs)
and http://www.xaraya.com/index.php/team/71
 (contacts)