Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Jifty::DBI::Schema(3) User Contributed Perl DocumentationJifty::DBI::Schema(3)

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.

       o   Button

       o   Checkbox

       o   Combobox

       o   Date

       o   Hidden

       o   InlineButton

       o   Password

       o   Radio

       o   Select

       o   Textarea

       o   Upload

       o   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.

perl v5.24.1			  2014-05-29		 Jifty::DBI::Schema(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | EXAMPLE | AUTHOR | BUGS | SUPPORT | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Jifty::DBI::Schema&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help