Accessing databases using models

A model in the world of Jifty is a class that defines how your data looks alike. Usually the data is retrieved from a database. To create a skeleton model class yo invoke the following commands:

$ bin/jifty model --name NameOfModel
Writing file .../lib/ApplicationName/Model/NameOfModel.pm
Writing file .../t/00-model-NameOfModel.t
$

The perl-module file contains two packages:

• ApplicationName::Model::NameOfModel::Schema which defines the record layout of a typical entry of this model inside the database.
• ApplicationName::Model::NameOfModel which defines additional methods you need to work with the model.

Aside this definition there is some magic behind that creates two special classes, that are created by Jifty::ClassLoader:

• ApplicationName::Model::NameOfModelCollection which is a descendant of Jifty::Collection. A collection is responsible for managing many Records of the same type. The Collection may be used to display a page of records, which are Jifty::Record objects. A Record has the ability to get edited, updated or deleted.
  • ApplicationName::Record (the base class of ApplicationName::Model::NameOfModel) is a subclass of Jifty::Record and automatically defines all methods required to allow loading, deleting, saving and checking of rights.

Defining a table in the DB schema

In the package ApplicationName::Model::NameOfModel::Schema, you define columns of the table that holds the records using the following syntax which is shown as a BNF (omitting non-terminals that are self explaining for perl programmers):

schema_definition ::= column_definition+ ';'

column_definition ::= 'column' string '=>' column_info [ ',' column_info ]+

column_info ::= 'type' 'is' string
   | 'label' 'is' string
   | 'render_as' string
   | 'render' 'as' string
   | 'refers_to' class_name ['by' string_classname]
   | ( 'default' | 'literal' ) is string
   | 'validator' 'is' subroutine_reference
   | ['is'] 'immutable'
   | ['is'] 'unreadable'
   | 'length' 'is' number
   | ['is'] 'mandatory'
   | ['is'] 'not_null'
   | ['is'] 'distinct'
   | ['is'] 'virtual'
   | 'sort_order' 'is' number
   | ( 'input_filters' | 'output_filters' | 'filters' ) 'are' string_classname
   | 'since' string_version_number
   | 'valid_values' 'are' array_of_valid_values
   | 'valid' 'are' array_of_valid_values
   | 'hints' 'are' string

* 'as', 'is', 'on', 'by' and 'are' are fill-words that may get omitted.

An example model

use strict;
use warnings;

package ApplicationName::Model::Address;
use Jifty::DBI::Schema;

use ApplicationName::Record schema {
    column firstname =>
        type is 'text',
        label is 'Firstname',
        render_as 'Text',
        since '0.0.1';

    column surname =>
        type is 'text',
        label is 'Surname',
        render_as 'Text',
        since '0.0.1';

    column email =>
        type is 'text',
        label is 'E-Mail',
        render_as 'Text',
        since '0.0.1';

    column birthday =>
        type is 'date',
        label is 'Birtday',
        render_as 'Text',
        since '0.0.1';
};

# Your model-specific methods go here.

1;

After having defined the schema above, you may update the schema at any time.

$ bin/jifty schema --setup
INFO - Generating SQL for application ApplicationName...
INFO - Using ApplicationName::Model::Address
INFO - Using Jifty::Model::Session
INFO - Using Jifty::Model::Metadata
INFO - Set up version v0.0.1, jifty version 0.607220</pre>

After a while, we need to add another column for holding the address of our persons. To get that done, we add a new column into the schema, name it with a newly created version number, which also has to get adjusted in the config-file etc/config.yml.

column address =>
    type is 'text',
    label is 'address',
    render_as 'Textarea',
    since '0.0.2';

Now we can update the schema:

$ bin/jifty schema --setup
Jifty version 0.607220 up to date.
INFO - Generating SQL to upgrade ApplicationName v0.0.1 database to v0.0.2
INFO - Upgrading through 0.0.2
INFO - Upgraded to version v0.0.2</pre>

Testing a model

At any time, you can go to the admin console, browse through your models and add or edit records.