Background Technical Information
This section provides some background information about Ruby on Rails which the LZadmin backend is built on and YAML which is a language used to define the configuration files. This should help with some of the terminology used in the User Guide and the motivations for some of the design decisions.
Convention over Configuration
One of Rails’ fundamental design philosophies is “convention over configuration”. This means that code logic is built to adopt a number of conventions which are found in the most common use cases without requiring the help of any configuration information. So the common cases are in effect built in. Rails does allow over-riding most of these conventions when required, however. LZadmin has been designed to take advantage of this, which results in its rich functionality with very little configuration information.
Ruby Naming Conventions
Being Ruby based, Rails inherits many naming conventions of this language. In Ruby, class names must start with a capital letter, so rails has adopted the covention of forming multi-word class names by concatenating each capitalized word, for example: “MyUsefulClass”.
In Ruby regular variables are lower case including the underscore character ”_”. When forming multi-word variables, the convention is to concatenate the words separated by ”_”, for example: “my_dutiful_variable”.
Active Record Names
The Rails Active Record (AR) component (a gem in Ruby parlance) provides the interface between application logic using objects (or instances of classes) and storage in database tables. AR handles all of the mapping and persistence issues for the rest of the application.
As is typical for an object to relational mapping, each object (class instance) may be associated with one row of a database table. In AR, the object takes the class name and the database table takes a plural form of (since it may contains many rows) of the name expressed as a variable. For example, if we wanted an object representing a menu item the convention would be:
- Class name: MenuItem
- Database table name: menu_items
The LZadmin configuration design is consistent with this so objects at the class level use class name conventions. When creating database tables, however, the database table naming convention is used. This lets the person specifying tables see consistent names between the LZadmin ‘create_table’ names and names seen directly with SQL.
YAML
As introduced at YAML.org:
“YAML (rhymes with “camel”) is a straightforward machine parsable data serialization format designed for human readability and interaction with scripting languages such as Perl and Python. YAML is optimized for data serialization, configuration settings, log files, Internet messaging and filtering.”
Since YAML has a simple human readable syntax and is well supported by the Ruby language, it was chosen as the format to express the end user inputs to the code generation portions of LZadmin. If not already familiar with YAML please review its basics before continuing with this section. A good starting place is en.wikipedia.org/wiki/YAML or www.yaml.org.
At the top level, the configuration is structured as a map which is a set of (key word, value) pairs. The value is often a scalar, for example, a string or boolean. It may also be a list of scalar values which can be expressed as an indented dashed list (or alternatively [val1, val2, val3, ...]). In some cases the value part may itself be a map or a nest of maps which allows for arbitrarily complex structures to be specified.
Maps are unordered, meaning that the ordering of entries within the config file is not guaranteed to be retained when it is loaded into a program. Because of this, it is sometimes necessary to package map entries inside of a sequence (list) which does preserve the ordering. This approach may be used under the ‘create_tables’ config key when the order of table columns must be preserved.
Note that most string values do not need to be quoted in YAML. One exception is when the string conflicts with a YAML defined type value, e.g. “true” which if unquoted would be taken as the boolean true. LZadmin uses the YAML parser/loader which is packaged with Ruby 1.8. If in doubt, you may quote a value to ensure that it is interpreted as a string.