Adding Modules
Adding a new module is very simple. First, insert a new <module> entry to the main Quince XML file. Inside that tag, you must specify the name of the module (which is used in the URL to load the module if no aliases are used) , the group of templates it will use, the class it will be tied to, and the default method in that class that will be called if none is specified, or the specified method isn’t implemented. Optionally, you can also add a <label> and <description> tag to each module. These may be useful if your application includes a listing of installed modules.
<module>
<name>mymodule</name>
<class>MyModuleClass</class>
<template>Mymodule</template>
<label>My First Module</label>
<description>This is the first Quince module I have ever made.</description>
</module>
As of version 0.8, you can store modules in more than one directory, thought they must share the same XML file. The <modules> tag, usually at the top of the controller XML, is where you specify these directories. Separate each one with a colon, and end each with a trailing slash.
<modules>Modules/:System/Modules/:/usr/lib/php5/myapp/</modules>
In the case of ambiguity, Quince uses the first module it finds that matches what it’s looking for, so if searching for the class file for mymodule, it will look for:
Modules/MyModuleClass.class.php or if not found,
Modules/mymodule/MyModuleClass.class.php or if not found,
Modules/MyModuleClass/MyModuleClass.class.php
And then, if none were found:
System/Modules/MyModuleClass.class.php or if not found,
System/Modules/mymodule/MyModuleClass.class.php or if not found,
System/Modules/MyModuleClass/MyModuleClass.class.php
And so on.
Inside A Module
Your classes
Your module classes don’t need to contain all of your functionality. In fact, for organisational reasons, it’s probably better to use subclasses to stop your module classes from getting too bloated. The main module class should mostly be thought of as a list of the different operations that can be completed in a single web request. For example, a very simple module that only deals with one type of data might have just five methods (apart from its constructor) – retrieve a list of data, retrieve a single record for display, delete a record, update a record, and insert a new record. Actual PHP code for building SQL queries could easily be included in a subclass, or data access object (DAO).
Manager classes
The way we recommend is to use what we call ‘manager’ classes for each module. These are classes that carry out many of the more low-level data-related tasks, such as checking for the existence of a primary key, or making an insertion. For instance, the main class for the news module, News.class.php, would make use of a NewsManager.class.php to take care of those individualised tasks that should never be executed directly by the user simply by going to a specific URL.
Base class
There are probably some operations that all of your modules will need to perform, for instance, redirecting the browser or perhaps connecting to the database (though if you use subclasses or manager classes, database interaction should probably be done there). If this is the case, it might be a good idea to use a base class, which your module classes extend. Quince comes with an interface that your base class should implement in order to be useful.
Template families
The user interfaces or other browser-side content that display the outcome of your modules’ various methods are grouped together as a “family”. The template family is in fact just a string that you can use in whichever way you wish to categorise your templates. It could be the name of a subdirectory where the templates for a particular module are stored (recommended), or it could be a prefix to differentiate your templates from those of another module, for instance, news.searchResults.tpl. Ultimately, you can retrieve the string with getTemplateName() and the rest is up to you. Quince was designed using Smarty as the ideal template engine, but you can use whichever you like best, or none at all.