View Architecture
rBook is designed to separate the application logic from the presentation logic. The back-end code that processes requests is written in PHP. Once a the response is ready to be rendered, view objects are created and passed to a Smarty template to build the view. The templates, stylesheet, and static images are what make up the skin or the look-and-feel. The skins are located in the 'skins' subdirectory of the installation.
Extending
You can change the look and feel of rBook by creating a new skin. A skin is a separate view that interacts with the back-end PHP code. The skin you are using is defined in the config.php. By default, the skin rBook uses is default and exists under the skins directory. To change what skin you are using, modify the SKIN configuration parameter in config.php to specify the skin (for example, define("SKIN", "foobar"); makes rBook use the "foobar" skin).
A skin has the following directory structure:
There are several levels at which you can override the default behavior of rBook. All but the last require that the default skin be present.
- 1. Extending the existing style sheet
- If you want to make minimal changes to the default stylesheet (such as to modify colors), create a new skin and only create the images and style subdirectories. Create a new stylesheet called style.css in the style directory and add the following line to the top:
@import url('/rbook/skins/default/style/style.css');where the URL points to the logical locaiton of the stylesheet on your box. This isn't really a portable skin, but allows an individual user to make minor modificaitons in a forward compatible manor. - 2. Overriding the existing style sheet
- This method is a variation on the first method, but we don't include the default stylesheet. This would be done to change major look-and-feel portions of the system.
- 3. Overriding the style and some of the templates (version 1.6 and above)
- If you create a templates directory in your skin's sub-directory in version 1.6 or above, rBook will look there for the template and then fall back to the default skin's template. This is useful if you want to change the layout without modifying individual pages in the default skin. To achieve this behavior in the templates you override, make sure you follow this syntax:
{include file="skin:template.tpl"}This will force rbook to look in both places for the template. This is the most flexible option and provides the greatest forward compatibility since you will still be able to use most of the templates in the default skin. - 4. Overriding the style and all the templates
- Instead of overriding some of the templates, you override all the templates. This provides the greatest level of flexibility and control (and works in rbook 1.5) since you don't need the default skin to be present. The only disadvantage is that you will not be able to take advantage of forward development of the default templates.
Smarty Plugins
The following extensions to smarty have been built and can be used if you extend or modify the rBook code.- {form} {/form}
- Builds an HTML form based on the controller/action/arg specified.
Arguments Name Required Description action true The action to invoke on the controller when the form is submitted controller true The controller to invoke when the form is submitted id false The ID of the form on the HTML page arg false The optional arg to submit to the action method false (post|get) post is the default enctype false The encoding type - {getMessage}
- Gets a resource by its key
Arguments Name Required Description key true The resource bundle key - {getParameterizedMessage} {param}{/param} ... {/getParameterizedMessage}
- Gets a resource by its key and fills in the parameters
Arguments Name Required Description key true The resource bundle key - Usage:
If the resource bundle key is defined like this: foo="The event occurred on {0} in the year {1}"
You would do:
{getParameterizedMessage key=foo}{param}March{/param}{param}2007{/param}{/getParameterizedMessage}
You can also invoke {getMessage} inside the parameter block. - {link} text {/link}
- Builds an anchor tag that invokes the controller/action/arg
Arguments Name Required Description action true The action to invoke on the controller when the link is selected controller true The controller to invoke when the link is selected id false The ID of the link on the HTML page arg false The optional arg to submit to the action class_name false The class name of the html anchor tag - {starRating}
- Builds a widget that displays the number of stars based on the number passed in
Arguments Name Required Description number true The number of stars to display (if a fractional portion is specified greater than 0.5, a half star is shown)
Translation
Thanks to Michael Schäfers and Henrik Pihl for providing German and Estonian translations and for spending time working out the kinks
rBook uses a Java-inspired translation scheme where resources are specified as key/value pairs in hierarchical translation files from the most specific (where both language and country are specified), to just language, to the least-specific where neither is specified and it falls back to the default locale (English). The default English translations are stored in an associative array in resources_en.php. If you want to specify British English, for example, you would create a file called resources_en_GB.php (the first extension in the file is the ISO 630 language code and the second parameter is a ISO 3166 Country code).
If your country/language of interest is not specified, create a file with the appropriate suffices and follow the pattern specified in resources_en.php. rBook should auto-discover the new resource bundle based on the LANGUAGE and LOCALE variables specified in config.php. Make sure you contribute your translation back to the subversion repository when complete.
.