/ 
Jifty-DBI-0.48
River stage one • 4 direct dependents • 6 total dependents
/ Jifty::DBI::Schema

NAME

Jifty::DBI::Schema - Use a simple syntax to describe a Jifty table.

SYNOPSIS

package MyApp::Model::Page;
use Jifty::DBI::Schema;
use Jifty::DBI::Record schema {
# ... your columns here ...
};

DESCRIPTION

Each Jifty Application::Model::Class module describes a record class for a Jifty application. Each column statement sets out the name and attributes used to describe the column in a backend database, in user interfaces, and other contexts. For example:

column content =>
   type is 'text',
   label is 'Content',
   render as 'textarea';

defines a column called content that is of type text. It will be rendered with the label Content (note the capital) and as a textarea in a HTML form.

Jifty::DBI::Schema builds a Jifty::DBI::Column. That class defines other attributes for database structure that are not exposed directly here. One example of this is the "refers_to" method used to create associations between classes.

It re-exports defer and lazy from Scalar::Defer, for setting parameter fields that must be recomputed at request-time:

column name =>
    default is defer { Jifty->web->current_user->name };

See Scalar::Defer for more information about defer.

filter_die

FUNCTIONS

All these functions are exported. However, if you use the schema helper function, they will be unimported at the end of the block passed to schema.

schema

Takes a block with schema declarations. Unimports all helper functions after executing the code block. Usually used at BEGIN time via this idiom:

use Jifty::DBI::Record schema { ... };

If your application subclasses ::Record, then write this instead:

use MyApp::Record schema { ... };

column

DEPRECATED. This method of defining columns will not work anymore. Please use the schema {} method documented above.

merge_params HASHREF HASHREF

Takes two hashrefs. Merges them together and returns the merged hashref.

- Empty fields in subclasses don't override nonempty fields in superclass anymore.
- Arrays don't merge; e.g. if parent class's valid_values is [1,2,3,4], and
  subclass's valid_values() is [1,2], they don't somehow become [1,2,3,4,1,2].

BUG: This should either be a private routine or factored out into Jifty::Util

register_types

references

Indicates that the column references an object or a collection of objects in another class. You may refer to either a class that inherits from Jifty::Record by a primary key in that class or to a class that inherits from Jifty::Collection.

Correct usage is references Application::Model::OtherClass by 'column_name', where Application::Model::OtherClass is a valid Jifty model and 'column_name' is a column containing unique values in OtherClass. You can omit by 'column_name' and the column name 'id' will be used.

If you are referring to a Jifty::Collection then you must specify by 'column_name'.

When accessing the value in the column the actual object referenced will be returned for refernces to Jifty::Records and a reference to a Jifty::Collection will be returned for columns referring to Jifty::Collections.

For columns referring to Jifty::Records you can access the actual value of the column instead of the object reference by appending '_id' to the column name. As a result, you may not end any column name which uses 'references' using '_id'.

refers_to

Synonym for references.

by

Helper for references. Used to specify what column name should be used in the referenced model. See the documentation for referencese

type

type passed to our database abstraction layer, which should resolve it to a database-specific type. Correct usage is type is 'text'.

Currently type is passed directly to the database. There is no intermediary mapping from abstract type names to database specific types.

The impact of this is that not all column types are portable between databases. For example blobs have different names between mysql and postgres.

default

Give a default value for the column. Correct usage is default is 'foo'.

literal

Used for default values, to connote that they should not be quoted before being supplied as the default value for the column. Correct usage is default is literal 'now()'.

validator

Defines a subroutine which returns a true value only for valid values this column can have. Correct usage is validator is \&foo.

immutable

States that this column is not writable. This is useful for properties that are set at creation time but not modifiable thereafter, like 'created by'. Correct usage is is immutable.

unreadable

States that this column is not directly readable by the application using $record->column; this is useful for password columns and the like. The data is still accessible via $record->_value(''). Correct usage is is unreadable.

max_length

Sets a maximum max_length to store in the database; values longer than this are truncated before being inserted into the database, using Jifty::DBI::Filter::Truncate. Note that this is in bytes, not characters. Correct usage is max_length is 42.

mandatory

Mark as a required column. May be used for generating user interfaces. Correct usage is is mandatory.

not_null

Same as "mandatory". This is deprecated. Currect usage would be is not_null.

autocompleted

Mark as an autocompleted column. May be used for generating user interfaces. Correct usage is is autocompleted.

distinct

Declares that a column should only have distinct values. This currently is implemented via database queries prior to updates and creates instead of constraints on the database columns themselves. This is because there is no support for distinct columns implemented in DBIx::DBSchema at this time. Correct usage is is distinct.

virtual

Declares that a column is not backed by an actual column in the database, but is instead computed on-the-fly.

sort_order

Declares an integer sort value for this column. By default, Jifty will sort columns in the order they are defined.

order

Alias for sort_order.

input_filters

Sets a list of input filters on the data. Correct usage is input_filters are 'Jifty::DBI::Filter::DateTime'. See Jifty::DBI::Filter.

output_filters

Sets a list of output filters on the data. Correct usage is output_filters are 'Jifty::DBI::Filter::DateTime'. See Jifty::DBI::Filter. You usually don't need to set this, as the output filters default to the input filters in reverse order.

filters

Sets a list of filters on the data. These are applied when reading and writing to the database. Correct usage is filters are 'Jifty::DBI::Filter::DateTime'. See Jifty::DBI::Filter. In actuality, this is the exact same as "input_filters", since output filters default to the input filters, reversed.

since

What application version this column was last changed. Correct usage is since '0.1.5'.

till

The version after this column was supported. The column is not available in the version named, but would have been in the version immediately prior.

Correct usage is till '0.2.5'. This indicates that the column is not available in version 0.2.5, but was available in 0.2.4. The value specified for "since" must be less than this version.

valid_values

A list of valid values for this column. Jifty will use this to autoconstruct a validator for you. This list may also be used to generate the user interface. Correct usage is valid_values are qw/foo bar baz/.

If you want to display different values than are stored in the DB you can pass a list of hashrefs, each containing two keys, display and value.

valid_values are
 { display => 'Blue', value => 'blue' },
 { display => 'Red', value => 'red' }

valid

Alias for valid_values.

label

Designates a human-readable label for the column, for use in user interfaces. Correct usage is label is 'Your foo value'.

hints

A sentence or two to display in long-form user interfaces about what might go in this column. Correct usage is hints is 'Used by the frobnicator to do strange things'.

render_as

Used in user interface generation to know how to render the column.

The values for this attribute are the same as the names of the modules under Jifty::Web::Form::Field, i.e.

  • Button

  • Checkbox

  • Combobox

  • Date

  • Hidden

  • InlineButton

  • Password

  • Radio

  • Select

  • Textarea

  • Upload

  • Unrendered

You may also use the same names with the initial character in lowercase.

The "Unrendered" may seem counter-intuitive, but is there to allow for internal fields that should not actually be displayed.

If these don't meet your needs, you can write your own subclass of Jifty::Web::Form::Field. See the documentation for that module.

render

Alias for render_as.

indexed

An index will be built on this column Correct usage is is indexed

EXAMPLE

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.