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 you 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 from 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.