Building Aliro Components

This is a temporary description that needs further expansion. A component might be described as an application (it would be probably be described as a module in the Drupal world). It is characterized by handling user input, creating substantial output that is usually placed in a prominent position on the browser page, and by enshrining some kind of application logic that performs a useful function. Examples of components are the Simple Text component that supports building articles consisting of text and images, Remository (which provides a file repository) or Registration (that supports the creation by users of new accounts). An Aliro application is a component with some additional features, and as development continues, components are tending to migrate towards being Aliro applications. If you want to quickly start building a component, look at the builder tool described below.

About Aliro Components and their history

Describing components is made harder by the fact that they can take numerous different forms. There is one split that is universal, and that is between user side code and administrator side code. Each component must have a formal name, which is specified in the packaging XML (for backwards compatibility it can be formed from the component name preceded by "com_" but this is deprecated in favour of explicitly stating the formal name). It is not obligatory to have both, and some components exist entirely on the user side, or entirely on the administrator side. When a component is first installed, it is given two directories, both of which are named with the component's formal name. The user side directory is at ../components/com_example for a component whose formal name is "com_example". At present, by convention, all components have names that begin with "com_". This derives from history and for the time being Aliro depends on it, although the dependency may be removed in future. However, it may still be desirable to follow the convention as an aid to simple allocation of unique formal names.

On the administrator side, the component's directory might be called ../administrator/components/com_example. However, this must not be assumed, because the literal name "administrator" is not fixed and components must not use it. Instead, Aliro provides a number of symbol definitions that can be used instead, and the getCfg('admin_site') method that will provide an external pointer to the administrator site, such as http://mysite.com/administrator∞.

IMPORTANT NOTE: Any code that is to be accessed on the user side should be stored in the user side directory. As a security principle, the user side code does not know where the administrator directory is, and therefore cannot load code that is stored on the administrator side. Aliro's autoloading mechanism will only load administrator side code when running on the administrator side, with a user who has logged in as an administrator.

Therefore, at a minimum a component would need to have two files, one of which was a code file that implements the functions of the component, and the other is an XML packaging file. The code file would be for either the administrator or user side, and the XML file is always copied into the component's directory on the administrator side. More commonly, a component would have at least two code files, one for the administrator side and one for the user side.

The history of Mambo related CMSs indicates that the starting points for running a component should have conventional names, which are used by the CMS to run the component's code. On the user side, there would be a file called example.php (still assuming a component with formal name com_example) and on the administrator side, a file called admin.example.php. Aliro will still work in this way, and assumes that a component whose packaging XML does not specify a starting point for user and administrator code is a legacy component.

However, Aliro is also rather more flexible. In the main element of the packaging XML, one attribute is "userclass" and another is "adminclass". These classes are expected to provide a method called "activate" that is passed control when the component is invoked by, for example, http://mydomain.com/index.php?option=com_example∞ or http://mydomain.com/administrator/index.php?option=com_example∞. So there is no requirement that the program code files should have any specific names, although it may well make life easier if they are all built with names that incorporate the name of the component in a logical fashion.

Typically, a component will have a good many more program files. This is dictated by the number of tasks that can be carried out by the component, and also by design principles that suggest splitting code according to its type. A common split is between controller classes (which marshall everything else), problem classes (which model the problem and provide functions to solve the problem) and view classes that accept data and create visible output, such as browser pages.

The Aliro component building tool

In practice, components often become quite complex. Also, it can be tricky to write an XML packaging file from scratch. To save time and trouble, there is a tool that will build the bare bones of a component. It is currently found at http://developer.aliro.org/index.php?option=com_commaker∞. The information you have to provide is more or less self explanatory, although it will be more fully documented in time.

The component building tool creates code according to a more elaborate convention than has been described so far. It places most of the code files into subdirectories whose names and functions are:

• c-classes will be installed on the user side and is the location for controller classes
• p-classes will be installed on the user side although the classes refer to the problem domain and will be used by both sides (see note above)
• v-classes will be installed on the user side and is the location for viewer classes that create visible output
• c-admin-classes will be installed on the administrator side and is the location for controller classes
• v-admin-classes will be installed on the administrator side and is the location for viewer classes that create visible output

On the user side, it builds a class that will receive control from Aliro and that class is a subclass of aliroComponentUserManager. Often that class can remain very small. It creates an abstract controller class that will be the base for individual controller classes, one for each of the possible tasks performed by the component. The abstract controller class is initially very simple, but may be elaborated as the component is developed, and should contain common code that is used by more than one controller.

On the administrator side, the building tool creates a class to receive control from Aliro, and that class is (predictably) a subclass of aliroComponentAdminManager. On the administrator side, there is a two level structure of control variables. Each screen has a toolbar, and the toolbar options relate to task values. Within a single controller module there will typically be a series of methods with names that are built out of the task name and the word "Task", such as "editTask". There is a higher level control variable called "act" that can be used to partition the administrator operations into different areas, accessed through different "act" values in an administrator submenu.

To make a start, much of the above detail can be ignored and a component created using the building tool. The output from the tool is an archive containing a complete, installable, operational component. The simplest route into development is to start modifying or adding to the controller and view classes, and creating more complex problem domain classes to model the real life problem that the component is created for.