Provided by: libjifty-dbi-perl_0.78-3_all bug

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.

       referencing a record

       Correct usage is "references Application::Model::OtherClass by 'column_name'", where
       Application::Model::OtherClass is a valid Jifty model, subclass of Jifty::Record, and
       'column_name' is a distinct column of OtherClass. You can omit "by 'column_name'" and the
       column name 'id' will be used.

       At this moment you must specify type of the column your self to match type of the column
       you refer to.

       You can name a column as combination of 'name' and 'by', for example:

           column user_name => references App::Model::User by 'name', type is 'varchar(64)';

       Then user, user_name and respective setters will be generated. user method will return
       object, user_name will return actual value. Note that if you're using some magic on load
       for user records then to get real name of loaded record you should use
       "$record->user->name" instead.

       In the above case name of the column in the DB will be 'user_name'. If you don't like
       suffixes like '_id', '_name' and other in the DB then you can name column without suffix,
       for example:

           column user => references App::Model::User by 'name', type is 'varchar(64)';

       In this case name of the column in the DB will be 'user', accessors will be the same as in
       above example.

       referencing a collection

       Correct usage is "references Application::Model::OtherCollection by 'column_name'", where
       Application::Model::OtherCollection is a valid Jifty model, subclass of Jifty::Collection,
       and 'column_name' is a column of records in OtherCollection. In this case  "by
       'column_name'" is not optional.

       Columns that refers to a collection are virtual and can be changed. So such columns in a
       model doesn't create real columns in the DB, but instead it's way to name collection of
       records that refer to this records.

       example

       Simple model with users and multiple phone records per user:

           package TestApp::Model::User;
           use Jifty::DBI::Schema;
           use Jifty::DBI::Record schema {
               column name  => type is 'varchar(18)';
               ...
               column phones => references TestApp::Model::PhoneCollection by 'user';
           };

           package TestApp::Model::Phone;
           use Jifty::DBI::Schema;
           use Jifty::DBI::Record schema {
               column user  => references TestApp::Model::User by 'id',
                   is mandatory;
               column type  => ...;
               column value => ...;
           };

       From a user record you get his phones and do something:

           my $phones = $user->phones;
           while ( my $phone = $phones->next ) {
               ...
           }

       From a phone record you can get its owner or change it:

           my $user_object = $phone->user;
           my $user_id = $phone->user_id;

           $phone->set_user( $new_owner_object );
           $phone->set_user( 123 );    # using id
           $phone->set_user_id( 123 ); # the same, but only 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 "references".

   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.  Correct 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
       Used to declare that a column references a collection, which hides it from many parts of
       Jifty. You probably do not want to set this manually, use "references" instead.

   computed
       Declares that a column is not backed by an actual column in the database, but is instead
       computed on-the-fly using a method written by the application author. Such columns cannot
       (yet) be used in searching, sorting, and so on, only inspected on an individual record.

   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 automatically construct 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'".

   display_length
       The displayed length of form fields. Though you may be able to fit 500 characters in the
       field, you would not want to display an HTML form with a size 500 input box.

   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.