|
DBIx::Record - Middle tier system for representing database records as objects. |
pkfset_fields(%options)new_record_pk($pk)fields_object()show_fields()show_field_names()reset_errors()add_error()add_dbierror()show_errors_plain()die_errors_plain()get_ob_dbh($ob)get_dbh()is_new()save()exists()delete()children(%options)get_login()get_dbh()validate()validate_fields()still_valid()changed()reset()display_record()display_record()display_record()crunch()tc()htmlesc()hascontent()strip_html()create_login()record_level_validate()always_rl_validate()pk_field_name()display_fields()field_defs()changed()reset()FETCH($key)new(%options)add(%options)output($media)output(%options)html_display_row()set_from_interface($value)set_from_db()send_to_db()validate($rec)text_display()html_display()html_form_field()DBIx::Record::Fieldhtml_form_field()set_from_interface()validate($rec)DBIx::Record::Field::Textrecord($login)validate($rec)DBIx::Record::Fieldset_from_interface($val)DBIx::Record::Fieldhtml_form_field()validate($rec)html_form_field()
DBIx::Record - Middle tier system for representing database records as objects.
use Hospital; # load class that implements DBIx::Record class my ($login, $patient);
# get object that holds the database connection $login = Hospital->get_login;
# Instantiate object representing the patient record
# that has primary key 1000. Change the record's name_last field.
# Then save the record.
$patient = Hospital::Patient->new($login, 1000, fields=>['name_last']);
$patient->{'f'}->{'name_last'} = 'Smith';
$patient->save;
# Instantiate object representing a patient record
# that doesn't exist yet. Set the name_last field, save,
# and output the primary key of the new record
$patient = Hospital::Patient->new($login, -1);
$patient->{'f'}->{'name_last'} = 'Smith';
$patient->save;
print 'primary key: ', $patient->{'pk'}, "\n";
DBIx::Record can be installed with the usual routine:
perl Makefile.PL
make
make test
make install
DBIx::Record is a system for representing database records as objects.
Each table in a database can be considered a class, and each record an
instantiation of that class. By presenting records as objects, each
type of record can have its own custom properties and methods.
DBIx::Record is an abstract class: it must be overridden by a concrete
class to be implemented.
A DBIx::Record record object (more simply known as a ``record object'')
is instantiated with the new static method, which accepts two
arguments: a DBIx::Record::Login object (which
holds the connection to the database) and one of several objects that
provides the data for a specific record. (new is explained in more
detail below.) For example, consider a database of medical patients.
Each patient has a record in a ``Patients'' table, and can be represented
by an object of the class Hospital::Patient. The following code
creates a record object with a primary key of 1000:
my $patient = Hospital::Patient->new($login, 1000);
The new object, then, represents the patient record whose primary key
is 1000. The primary key is stored in the pk
property of the object:
print 'primary key: ', $patient->{'pk'}, "\n";
When the record object is instantiated using an ID, no calls to the
database are made. That is, the object merely knows its primary key. No
data has been retrieved from the database, and in fact, it has not even
been confirmed that the record exists. To pull the record's data from
the database, use the set_fields method:
$patient>set_fields();
set_fields retrieves the record fields from the database and stores
them in the object's f (``fields'') property. That
data can then be written to and read, and the record saved:
$patient->{'f'}->{'name_last'} = 'Smith';
print 'last name: ', $patient->{'f'}->{'name_last'}, "\n";
$patient->save;
There are other ways to instantiate an object besides using an existing
record's primary key. For example, to create a new record (i.e. to add
a new record to the database, send a negative primary key.
DBIx::Record will understand that to mean a new record. You can put
values in the record's f hash and save the record as usual:
my $patient = Hospital::Patient->new($login, -1);
$patient->{'f'}->{'name_last'} = 'Smith';
$patient->save;
print 'primary key: ', $patient->{'pk'}, "\n";
Another way to instantiate a record object is to pass a DBI statement
handle as the second argument. DBIx::Record will understand to
populate the object's f hash from the next record in the statement
handle:
my $patient = Hospital::Patient->new($login, $sth);
print 'primary key: ', $patient->{'pk'}, "\n";
Yet another way to instantiate a DBIx::Record object is to pass a CGI
query object as the second argument. In that situation you must always
pass a specific list of fields that should be read from the query.
DBIx::Record will read the listed fields from the query and store them
in the f hash:
my $patient = Hospital::Patient->new($login, $q, fields=>['name_last', 'name_first', 'date_of_birth']); $patient->save;
The techniques described here provide the basis for how DBIx::Record
objects work. There are many more features. Just to name a few,
DBIx::Records provide:
DBIx::Record is based on certain assumptions about how you design your
database. While most of the assumed practices are quite typical, it's
necessary to be sure that DBIx::Record and your database design do not
clash.
Tables that are represented by record object classes are assumed to
have a single primary key. It is assumed that that key will never be a
negative integer. It is also assumed that a new primary key can be
programmatically generated for each new record (typically through use
of a sequence). DBIx::Record does not (currently) support referencing
tables with composite primary keys, but it does not prevent you for
including those types of tables in your database and referencing them
in a more traditional manner.
DBIx::Record assumes that no database or HTML form fields start with
the ``dbr.''. DBIx::Record reserves that prefix for use as hidden fields
in HTML forms. It is also assumed that field names are
case-insensitive.
DBIx::Record is implemented by extending the base class through
several layers that implement different pieces of the database
connection puzzle. A typical implementation will extend DBIx::Record
through four layers. The following sections look at each layer.
The base class is DBIx::Record itself. DBIx::Record provides the
overall interface as well as a variety of utility functions.
DBIx::Record is an abstract class and defines several methods that
must be overridden. This class also implements a wide range of
concrete methods that can be used by the final concrete classes.
The next layer,
DBIx::Record::DBFormat::format,
extends DBIx::Record to handle a specific database format such as
MySQL, PosGreSql, Oracle, etc. This layer implements six static methods
that provide generic access to a relational database:
The Application layer extends one of the database format classes to
provide methods that apply to your specific application. This class
provides the create_login
method that provides a login object and a database handle.
This concrete class layer extends the application layer to provide
objects for a specific table. This class implements the
table_name,
pk_field_name, and
field_defs methods.
DBIx::Record is the base class for record objects. One class is defined for
each table in the database. Every instantiation of DBIx::Record
represents a single record in that table.
DBIx::Record has three constants for indicating the media for the field object. These constants are all integers, so you can use ==
for comparisons.
DBIx::Record exports the following methods and constants if you load it with the :all option, like this:
use DBIx::Record ':all';
%DBIx::Record::nospace is used by strip_html. %nospace gives a set of HTML tags which, when removed, should
not be replaced with a single space. Each key in %nospace is the name of a tag, in lowercase. The values are ignored.
An array of error messages that are created when a function has an error. Any function may add errors to this array, but only the following functions may clear the array:
login represents the record's connection to the database. login
is used by every method that sends data to or retrieves data from the
database.
login may either be an object which returns a DBI database handle
via its get_dbh method, or login
may itself be a database handle. DBIx::Record dynamically determines
which type of object it is and acts accordingly. The application layer creates the login object using its static
create_login method.
pkThe primary key of the record. This property should never be set outside of the class.
If true, then the object uses itself as its own login object. This
property is used by the get_login method.
fThe hash of field objects. The keys are the field names, the values are field objects. It's named ``f'' instead of fields because I found myself using this property dozens of times per web page, and I wanted something shorter to type.
f is reference to a tied hash. If you assign a value to one of the
hash keys, the value is assigned using that field object's
set_from_interface method.
Also, the tied object tracks if any changes to the fields have been
made, so that no database call is necessary if no changes were made.
This static method is the constructor for a DBIx::Record object. The
method has two required arguments. The first, $login, is the login
object. It may instead be a dbh object.
The second, $id is one of these types of scalars:
$id is a defined non-reference, and if it
is an integer greater than or equal to zero, then it is assumed to be
the primary key of an existing record.$id is not defined, or if it is
a number less than zero, then it is assumed that the record object
represents a new record. In this case the pk property is not
defined.$id is a DBI statement handle, then
the current record in the handle will be used to set the fields of the
record object. In doing so, the statement handle will be advanced to
the next record. The statement handle must include the primary key
of the record. If the statement handle is at eof, then new returns
undef.dbr.form_sent field in the query is true, and if
the dbr.cancel field in the query is false, then the fields are set
from the CGI object. The feature is only enabled if the
fields option is also sent. Only the
fields listed in fields are loaded from the CGI. fields may be
set to * to indicate all fields.
This option consists of an array of fields to retrieve from the
database. If this option is sent, then the new record object
automatically retrieve. If the list consists of just *, then all the
fields are retrieved. The options set_fields and fields mean
exactly the same thing.
set_fields(%options)This method retrieves data from the database using the primary key of
the record object, and stores the data into the fields hash. There
are no required arguments. By default, set_fields retrieves all the
fields in the record. This function uses select_single(%opts), which
is implemented in the database format layer, to do the actual retrieval
of records from the database. An array of errors is returned if pk
is not defined or if the record is not found in the database.
fields is an array of the names of fields to retrieve. It may also
be a scalar, which will be interpreted as a single-item array. So, for
example, this code retrieves the name and email fields:
$client->set_fields(fields=>['name', 'email']);
TODO
TODO
TODO
new_record_pk($pk)Returns true if the given primary key is in the format of a new record.
fields_object()Returns the object to which the fields hash is tied.
show_fields()A handy utility for debugging. Displays all fields in a web page
show_field_names()Another handy utility for debugging. Displays all field names.
reset_errors()Clears out all errors from @DBIx::Record::errors.
add_error()Adds an error to @DBIx::Record::errors. Always returns an empty array, so returning the return value of this
function is a clean way to return false from a subroutine.
add_dbierror()Adds the value of $DBI::errstr to @DBIx::Record::errors. Always returns an empty array, so returning the return value of this
function is a clean way to return false from a subroutine.
show_errors_plain()Handy for debugging. Outputs @DBIx::Record::errors to STDOUT.
die_errors_plain()Handy for debugging. Outputs @DBIx::Record::errors to STDOUT, then dies.
get_ob_dbh($ob)Returns the database handle from a login, if $ob *is* login object. Otherwise returns
$ob itself.
get_dbh()Returns the database handle used by the record obejct.
is_new()Returns true if the record is a new record (i.e. not saved to the database yet).
save()This method saves the record to the database, returning an array of errors if the record could not be saved.
First, save calls validate. If validate
returns any errors then save returns those errors to the caller and
is done.
If pk is defined, then save calls
update, returning its error
array. Otherwise save calls
insert, setting the resulting
new primary key to pk (if there were no errors) and returning the
array of errors.
exists()Returns true if the given record exists in the database. Calls record_exists to make the check.
delete()Deletes the record. Returns true if successful. Before the record is deleted, the
before_delete method is called. If that method returns false, then the record is
not deleted. After the deletion, the <after_delete> method is called.
This static method returns a
DBIx::Record::Looper|/DBIx::Record::Looper object representing the
results of a select statement.
By default, every field in every record is returned. For example, this code loops through the entire Clients table:
$looper = MyApp::Client->get_records();
while (my $client = $looper->next) {
print $client->{'f'}->{'name'}
}
The optional arguments allow you filter down what is returned.
Note that if any of these options are tainted then there will be a fatal error. The only exception is the list of bindings, which may be tainted.
These options are passed to
select_multiple,
which is implemented in the database format level. fields, bindings, and
order are first checked to ensure that they are array refs. If they
are scalars then they are converted to refs to single element arrays.
children(%options)This method returns a looper referencing child records in a foreign
table. The only required argument is $class, which is the name of
the class of the foreign table. For example, the following code returns
a DBIx::Record::Looper for the members of a club:
$looper = $club->children('MyApp::Club');
This method accepts the same options as
get_records: fields, where,
bindings, and order. The where clause created by the where
option is set in addition to the primary of the current record.
get_login()Returns the login held in the
login property. If the object's
is_own_logon is true, then the object itself is returned.
get_dbh()Returns the database handle used by the object.
validate()Validates the record. Returns true if the record passes valdation, false otherwise.
If there are any errors,they will be in @DBIx::Record::errors.
Calls validate_fields()|/DBIx::Record.validate_fields, holding on
to the returned array of errors. If no errors are found, or if
always_rl_validate()|/DBIx::Record.always_rl_validate returns true,
the process then calls
record_level_validate()|/DBIx::Record.record_level_validate,
holding on to those errors.
Before any valdation is done, the still_valid method is called. If
it returns true, then the record has not been changed since it was
retrieved from the database, or since it was last confirmed as valid,
so no validation is needed and validate returns true.
If errors are found, validate returns false. @DBIx::Record::errors
contains an array of errors.
validate_fields()Loops through all changed fields and runs their
validate methods. If any of the
validations return false, then this method returns false. Otherwise it
returns true.
still_valid()Returns true if the record has been validated before and the record has not changed since that validation.
changed()Returns an array of the names of fields that have changed since the record object was created or since the last save. For a new record, all fields are noted as ``changed'' when the object is created.
This method actually just calls the changed() method of the DBIx::Record::FieldHash object.
reset()Sets the record so that no fields are marked as changed. The values of the fields are not changed back to their original values.
This method actually just calls the reset() method of the DBIx::Record::FieldHash object.
display_record()Returns a single record with just the fields listed in display_fields.
display_record()Returns a looper object just like get_records, but with the display fields specifically requested.
display_record()Returns the output of the display_str method of the record with the given pk.
crunch()Trims leading and trailing space, crunches internal contiguous whitespace to single spaces. In void context, modifies the input param itself. Otherwise crunches and returns the modified value.
tc()Sets the given string title case: the beginning strings are in uppercase, everything else is lowwer case. In void context, modifies the input param itself. Otherwise crunches and returns the modified value.
htmlesc()Escapes the given string for display in a web page. In void context, modifies the input param itself. Otherwise crunches and returns the modified value.
hascontent()Returns true if the given scalar is defined and contains something besides whitespace.
strip_html()Removes all HTML tags from the given string.
create_login()This method sets $login to either a
DBIx::Record::Login object, or a DBI database
handle. This method returns true/false indicating success. This method
is the most loosely defined in DBIx::Record That is because every
application will have a different way of creating login objects and
connecting to the database.
record_level_validate()Override this method in the table layer.
This method is called by validate()|/DBIx::Record.validate to allow
the designer to perform custom validation beyond that which is
performed at the field level. This
method returns true/false indicating success. The default is to return
true. This method should not be used to check field-level business
rules such as ``required''. Those checks are done by the individual field
objects and are all called by
validate_fields, which is also called
by save|/DBIx::Record.save.
Designers of extensions of this subroutine should be sensitive to the fact that not all of the fields for a given record may be loaded into the object. Therefore, checks on relationships between several fields may not be necessary if not all of those fields are loaded.
always_rl_validate()Override this method in the table layer.
If this method returns true, then when validate()|/DBIx::Record.validate calls
validate_fields()|/validate_fields and it gets errors, it
still calls record_level_validate(). Defaults to false.
pk_field_name()These methods provide simple information about a specific table.
table_name returns the name of the table. pk_field_name returns
the name of the primary key field.
These methods simply return a string. They require no arguments and can be called as either static or object methods. Generally each can be implemented in a single line of code:
sub table_name {'COUNTRY'}
sub key_field_name {'COUNTRY_ID'}
display_fields()display_str outputs a string that is used to indicate this record. Usually this
method is used in lists of records. For example, in a table holding
country names, this method would return the name of the country (e.g.
``England'', ``Canada''). In a list of people, this record could return the
list of people's names.
display_str returns an array ref of fields that are used by display_str.
These methods are called before and after the creation, update, and deletion of a record. If any of ``before'' events return false then the event is cancelled. By default all of these simply return true.
field_defs()This method returns a hash of field definitions. Each field definition
is itself a hash of properties for that field. These definitions are
used to create the fields in the f property of
DBIx::Record::Field|/DBIx::Record::Field objects.
Each key in the hash is the name of the field. Field names should
always be lowercase. The value consists of a hash of field properties.
The only required property is the name of the class of the field. Other
properties are passed to the field object
constructor and will generally be used to set properties of that field
object.
The default property is used to set the default value of the field.
That value is passed to the field object constructor via its
set_from_interface method.
field_defs determines the definitions in any way the programmer
chooses, but generally it's easiest to simply create and return the
hash directly in the sub, like this:
sub field_defs {
return
name => {
class => 'DBIx::Record::Text',
required => 1,
display_size => 25,
maxsize => 50,
},
email => {
class => 'DBIx::Record::Text',
rows => 5,
cols => 70,
maxsize => '1k',
},
comments => {
class => 'DBIx::Record::TextArea',
},
;
}
Deletes the record in the given table with the given primary key. This method returns true/false indicating success. Implement this method in the database format layer.
Retrieves the record's data from the database, returning a hash of the
fields and data. By default, all the fields are retrieved and returned.
If the fields option is sent, then only the fields listed there
should be retrieved.
This static function is implemented in the database format layer. select_multiple selects
a set of records from the class' table, returning a DBI statement handle of that selection. The
statement handle should not be executed.
In its simplest form, select_multiple selects all fields in all records in
the entire table:
$sth = MyApp::Clients->select_multiple($dbh);
The optional arguments filter down the results:
fields is an array of the names of fields to retrieve. The default
is *, which may also be sent explicitly. So, for example, this code
retrieves the name and email fields:
$sth = MyApp::Clients->select_multiple($dbh, fields=>['name', 'email']);
Regardless of what fields are listed in this argument,
select_multiple should always return the primary key in the
return hash.
age then
name:
$sth = MyApp::Clients->select_multiple(
fields => ['name', 'email'],
order => ['age', 'name']);
$sth = MyApp::Clients->select_multiple(
fields => ['name', 'email'],
where_str => 'age < 21');
where option. This
option is an array of values associated with the bound params in the
where clause. So, for example, this code binds 21 to the first param
and 'm' to the second:
$sth = MyApp::Clients->select_multiple(
fields => ['name', 'email'],
where => 'age < ? and gender=?',
bindings => [21, 'm']
);
Returns true if a record with the given primary key exists in the given table.
This static function is implemented in the database format layer.
This method saves the fields in the %fields to a specific existing
record. The hash will always contain at least one name/value pair, and
the function can assume that the record already exists. This method
returns true/false indicating success.
This method creates a new record in the table and returns the primary key
of that new record. %fields ius a hash of field names and values for the new
record. The hash may have any number of name/value pairs, including
none. This method returns true/false indicating success.
A DBIx::Record::Login object represents the connection to the
database. DBIx::Record::Login is an interface class: it is not
provided by DBIx::Record. Each application must provide its own class
that implements the DBIx::Record::Login interface. Alternatively, the
application can pass around a DBI database handle object and never
implement a DBIx::Record::Login class.
Returns an active database handle.
This is the tied hash class that is used to create the tied hash for
the f property of the record object.
The id, login, and class of the parent record object. Because of Perl's difficulty in garbage collecting circular references, we don't store a direct reference to the parent record object. Instead, we hold on to the info we would need in case we need to retrieve any other fields.
Hash of field objects.
This property indicates which fields have been changed since the record
object was created. When the save|/DBIx::Record.save method is
called, if no fields have been changed, then no save is done. If any
fields have changed, only those fields that have changed are stored
back into the database. changed_fields consists of a hash whose keys
are the changed field names. The values of the hash are not important.
changed()Returns an array of the names of fields that have changed since the record object was created or since the last save. For a new record, all fields are noted as ``changed'' when the object is created.
reset()Sets the record so that no fields are marked as changed. The values of the fields are not changed back to their original values.
Instantiates the object, stores the record's id, login, and class
properties in itself. Creates the fields hash.
FETCH($key)Returns the given key from the fields hash. If the field doesn't
exist then the value is loaded from the database, stored in the
fields hash, and returned.
If the given val is a DBIx::Record::Field|/DBIx::Record::Field object
(or any class that extends DBIx::Record::Field), then that object is
stored directly in the fields hash, and the field name is stored in
changed_fields. If the fields hash already contains a
DBIx::Record::Field object with that key, then the value is passed to
the object using its set_from_interface method.
If the field doesn't exist in the fields hash, then the class's
field_defs method is called, and a definition for that field name is
sought. If the definition is found, then the field object is added to
the hash and the value stored in it as before.
If the field doesn't exist in the field definitions, then a fatal error occurs.
This one's a little weird. You don't delete fields from a database. In this situation it makes sense to say that delete means ``remove from the cache, don't save any value''.
Returns true if the given field exists in the fields hash.
Used to cycle through the fields hash in the normal tied hash
manner.
A looper object is used to iterate through the results of a select
statement. Each call to next returns a
DBIx::Record object of the class that created the
looper. So, for example, this code selects all clients and returns
their information one at a time:
$looper = MyApp::Client->get_records();
while (my $client = $looper->next) {
...
}
Looper objects are lazy... they do not actually connect to the database
until the first next method is called. After the last record is
returned, they close the statement handle.
The statement handle being held for looping through.
The name of the class of the returned record objects.
If false, then the statement handle has not been executed yet.
This method is the constructor. This method creates the looper object and stores the class name and the statement handle that are passed as the arguments.
This method instantiates and returns a single record object representing the next record in the statement handle.
If the executed property is false, then this is the first time that
next has been called. The statement handle is executed and
executed is set to true.
If the statement handle returns undef, then the handle is done and is undeffed.
DBIx::Record::Error objects represent a single error message returned
by a function. The object oriented format of the error messages allow
function to return messages that take advantage of HTML while still
restricting themselves to plain text when necessary.
The plain text of the error message.
The HTML version of the error message.
new(%options)Instantiates an error object. The optional arguments must have either
html or text. If neither is sent then a fatal error occurs. The
options are stored in the html or text properties as appropriate.
add(%options)This static method works just like new(), except that instead of returning the error object,
it adds the object to the @DBIx::Record::errors array.
output($media)Returns the error message for the given media.
$media should be
DBIx::Record::MEDIA_TEXT,
DBIx::Record::MEDIA_HTML, or
DBIx::Record::MEDIA_HTML_FORM.
If the object's text property is defined,
but html is not, and if the media indicates HTML, then the text
property is HTML escaped and output. If text is called for and there is
only HTML, then all HTML is stripped (though for the time being
probably not very well for this first release) and returned. If there
is neither, then a fatal error occurs.
DBIx::Record::Field represents a single field in a record. A
DBIx::Record::Field knows how to dislay itself in three different
medias, can deserialize itself from two types of data sources, and
knows how to format itself for saving in the database.
DBIx::Record::Field allows the application designer to define once how
a field is displayed and stored, and then use that definition in many
different places.
DBIx::Record::Field is an abstract class. It is extended by several
different classes to implement different types of fields.
DBIx::Record::Field objects stringify to the results of the
output() method. By doing so, fields can be easily output in Perl
``here'' documents.
The name of the field that is stored in the database.
This property holds the value of the field. Strictly speaking, the type of data (scalar, array reference, hash reference) that is stored in this property is up to each extending field class. Calculated fields may not even use this property. However, default values will be stored in this property, and extending classes should customarily store data here.
Indicates if the field is required. Generally it implies that the value may not be an empty string, and must contain something besides whitespace. However, extending classes may interpret this property however they want.
A short description of the field, what many people might call the
``name'' of the field. This will often be different than the id. For
example, a field might have a field with an id of phone but a
desc_short of ``Phone number''.
A long text description of the field. This field may be of any length, but 100 characters is the upper limit of good taste. This field may be left undefined, in which it is simply not output.
The HTML version of desc_long_text. If this property is not defined,
then desc_long_text is HTML escaped and output to the web page.
This property indicates how the field data should be displayed. There
will be three possible values, set as constants in the DBIx::Record
namespace:
If this property is set, the object it references is used to determine
the display media rather than the media property itself. The object
must implement the get_media method.
Field objects stringify to the output of their outputmethods.
Therefore, the two following commands function identically:
print $myfield->output; print $myfield;
new is the constructor for field objects. new takes two arguments.
$definition is the field definition as returned by the table layer's
field_defs method. $login is the
login object used to communicate with the database.
output(%options)Returns the results of either text_display(), html_display(), or
html_form_field(), depending on the media type. This method is used
by the stringification class property to display the field according to
the proper media.
html_display_row()Returns an entire row of an HTML table for displaying the name,
description, and value of a form field. Typically, the first column
will contain the shortdesc of the field and the longdeschtml (if
it exists) below that. The second column will contain the form field or
the html value. In no cases should this method return more than two
HTML table columns.
set_from_interface($value)Sets the value based on the value received from the user interface.
set_from_db()Sets the value of the field based on the value returned from the
database. By default this method is just calls set_from_interface.
send_to_db()Returns the value that should be stored in the database. By default
this method just calls text_display.
validate($rec)Checks if the data in the field violates any business rules for the
field. This method returns true/false indicating success. The default
base implementation of this method always returns true. The first
argument is the DBIx::Record object, which may be used to do external
checks on the field data.
text_display()Returns the value that should be displayed exactly as-is in a
text-based interface. By default this method simply
returns the value of the value property.
html_display()Returns the value that should be displayed (not as a form field) in a
web page. Text-fields, for example, will simply return the text with
the HTML escaped. In DBIx::Record::Field, this method simply returns
the HTML escaped value of the value property.
html_form_field()Returns the HTML to display the field in an HTML form. The code should default the field to its current value.
DBIx::Record::FieldThis class represents a short text field. Examples of data that would
use DBIx::Record::Field::Text would be people's names.
Indicates that the data should have leading and trailing whitespace removed, and internal whitespace crunched down to single spaces.
Indicates how many characters wide the text field should be in form editing.
Indicates that the maximum number of characters the text may be. 0 or undef indicate no maximum size. 'k' may be appended to the value to indicate that the size is in kilobytes, or 'm' to indicate that the value is in meg. For example, '3k' would indicate that the string may be 3 kilobytes long.
If any of these properties are true, then the data is uppercased, lowercased, or title-cased when it is imported from the user interface.
html_form_field()Returns the HTML code for an <INPUT> element. The size of
the field is set to the size property.
set_from_interface()Overrides DBIx::Record::Field's set_from_interface to implement the
upper, lower, and title properties.
validate($rec)Performs a large set of validation checks. If the field is required,
the value must consist of something besides whitespace. If there is a
maxsize, that is checked. If the record is a static
foreign_key(), then the foreign key is checked using
record_exists($id).
DBIx::Record::Field::TextDBIx::Record::Field::TextArea objects are just like
DBIx::Record::Field::Text objects except that they provide a much
larger editing area for the user interface.
DBIx::Record::Field::TextArea are for large blocks of text such as
``description'' fields.
Indicates the number of rows and columns to use for the text editing box.
extends DBIx::Record::Field
A field that is a foreign key to another table.
The class name of the foreign table.
If this field does not allow the user to change the value of the field.
record($login)Returns the record that this field references. Return undef if value
if undef.
validate($rec)Uses the given record object to check if a record of the given class
exists with the primary key stored in value.
DBIx::Record::FieldA field object of this class holds a true/false value. It is represented in the user interface with a checkbox.
This property consists only of 1 or 0.
This property contains the strings that indicate true or false. The
property consists of an LCHash in which each key is
a string that might be used to represent true or false. The value of
each hash element is 1 or 0. When data is input into the field using
the set_from_interface
method, if the input value is defined and matches (on a crunched,
case-insensitive basis) any of the keys in the hash, then the value of
that hash element is stored. If the value does not exist in the hash,
then the value is stored based on its standard Perl truth or falseness.
This property defaults to these keys and values:
{
1 => 1,
0 => 0,
y => 1,
n => 0,
yes => 1,
no => 0,
t => 1,
f => 0,
true => 1,
false => 0,
}
This property holds the strings that are output to the database to indicate true and false. The property consists of a hash with keys 1 and 0. The default value of this property is this hash:
{
1 => 1,
0 => 0,
}
This property holds the strings that are output to the user interface to indicate true and false. The property consists of a hash with keys 1 and 0. The default value of this property is this hash:
{
1 => 1,
0 => 0,
}
If this property is set, then when the data is represented in HTML, but not in a form, the images defined in this property are displayed to indicate true or false. This property can be used to present images of checkboxes that look like the checkboxes in a form, but are not editable.
This property should consist of an anon hash with two elements. The
keys for the hash are 1 and 0. The value of each element is a hash
consisting of the properties of the image. The properties of the image
are url, height, width. An example of this property might
consist of this hash:
{
1 => {
url => '/images/yes.gif',
height => 15,
width => 15,
},
0 => {
url => '/images/no.gif',
height => 15,
width => 15,
},
}
set_from_interface($val)This method sets the value of the field according to this algorithm:
DBIx::Record::FieldObjects in this class have a defined, finite set of available options. The user interface for this type of field is a dropdown selection in which the user may select exactly one value.
This property consists of an array of values and value displays. The values and displays alternate: a value, then a display, then another value, then its display, etc.
If this property is set, it gives the class name of a table. This property indicates that the value of the
field is a foreign key to the given table. The primary keys and display values are retrieved from the class
using its display_options and display_str methods.
html_form_field()Returns HTML for a <SELECT> field.
validate($rec)Checks that the value is one of the defined set of acceptable values.
extends DBIx::Record::Select
Works just like DBIx::Record::Select except that it outputs radio
buttons instead of a select box.
html_form_field()Returns HTML for a set of radio buttons.
Copyright (c) 2002 by Miko O'Sullivan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with NO WARRANTY of any kind.
Miko O'Sullivan miko@idocs.com
|
DBIx::Record - Middle tier system for representing database records as objects. |