Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Developer objects

Loading an existing object or objects

$obj->load()

$obj->load_iter()

You can load an object from the datastore using the load method. load is by far the most complicated method, because there are many different ways to load an object: by ID, by column value, by using a join with another type of object, etc.

In addition, you can load objects either into an array (load), or by using an iterator to step through the objects (load_iter).

load has the following general form:

my $object = MT::Foo->load( $id );

my @objects = MT::Foo->load(\%terms, \%arguments);

my @objects = MT::Foo->load(\@terms, \%arguments);

load_iter has the following general form:

my $iter = MT::Foo->load_iter(\%terms, \%arguments);

my $iter = MT::Foo->load_iter(\@terms, \%arguments);

Both methods share the same parameters; the only difference is the manner in which they return the matching objects.

If you call load in scalar context, only the first row of the array @objects will be returned; this works well when you know that your load call can only ever result in one object returned - for example, when you load an object by ID.

\%terms should be either:

  • The numeric ID of an object in the datastore.

  • A reference to a hash.

The hash should have keys matching column names and the values are the values for that column.

For example, to load an MT::Foo object where the foo column is equal to bar, you could do this:

my @foo = MT::Foo->load({ foo => 'bar' });

In addition to a simple scalar, the hash value can be a reference to an array; combined with the range setting in the \%arguments list, you can use this to perform range searches. If the value is a reference, the first element in the array specifies the low end of the range, and the second element the high end.

  • A reference to an array.

In this form, the arrayref contains a list of selection terms for more complex selections.

my @foo = MT::Foo->load( [ { foo => 'bar' }
    => -or => { foo => 'baz' } ] );

The separating operator keywords inbetween terms can be any of -or, -and, -or_not, -and_not (the leading ‘-’ is not required, and the operator itself is case-insensitive).

Values assigned to terms for selecting data can be either simple or complex in nature. Simple scalar values require an exact match. For instance:

my @foo = MT::Foo->load( { foo => 'bar' });

This selects all MT::Foo objects where foo == 'bar'. But you can provide a hashref value to provide more options:

my @foo = MT::Foo->load( { foo => { like => 'bar%' } });

This selects all MT::Foo objects where foo starts with ‘bar’. Other possibilities include not_like, not_null, not, between, >, >=, <, <=, !=. Note that not and between both accept an arrayref for their value; between expects a two element array, and not will accept an array of 1 or more values which translates to a NOT IN (...) SQL clause.

\%arguments should be a reference to a hash containing parameters for the search. The following parameters are allowed:

sort => “column”

Sort the resulting objects by the column column; column must be an indexed column (see “indexes”, above).

Sort may also be specified as an arrayref of multiple columns to sort on. For example:

sort => [
    { column => "column_1", desc => "DESC" },
    { column => "column_2", }   # default direction is 'ascend'
]

direction => “ascend|descend”

To be used together with a scalar sort value; specifies the sort order (ascending or descending). The default is ascend.

limit => “N”

Rather than loading all of the matching objects (the default), load only N objects.

offset => “M”

To be used together with limit; rather than returning the first N matches (the default), return matches M through N + M.

start_val => “value”

To be used together with limit and sort; rather than returning the first N matches, return the first N matches where column (the sort column) is greater than value.

range

To be used together with an array reference as the value for a column in \%terms; specifies that the specific column should be searched for a range of values, rather than one specific value.

The value of range should be a hash reference, where the keys are column names, and the values are all 1; each key specifies a column that should be interpreted as a range.

MT::Foo->load( { created_on => [ '20011008000000', undef ] },
    { range => { created_on => 1 } } );

This selects MT::Foo objects whose created_on date is greater than 2001-10-08 00:00:00.

range_incl

Like the ‘range’ attribute, but defines an inclusive range.

join

Can be used to select a set of objects based on criteria, or sorted by criteria, from another set of objects. An example is selecting the N entries most recently commented-upon; the sorting is based on MT::Comment objects, but the objects returned are actually MT::Entry objects. Using join in this situation is faster than loading the most recent MT::Comment objects, then loading each of the MT::Entry objects individually.

Note that join is not a normal SQL join, in that the objects returned are always of only one type - in the above example, the objects returned are only MT::Entry objects, and cannot include columns from MT::Comment objects.

join has the following general syntax:

join => MT::Foo->join_on( JOIN_COLUMN, I<\%terms>, I<\%arguments> )

Use the actual MT::Object-descended package name and the join_on static method providing these parameters: JOIN_COLUMN is the column joining the two object tables, \%terms and \%arguments have the same meaning as they do in the outer load or load_iter argument lists: they are used to select the objects with which the join is performed.

For example, to select the last 10 most recently commmented-upon entries, you could use the following statement:

my @entries = MT::Entry->load(undef, {
    'join' => MT::Comment->join_on( 'entry_id',
                { blog_id => $blog_id },
                { 'sort' => 'created_on',
                  direction => 'descend',
                  unique => 1,
                  limit => 10 } )
});

In this statement, the unique setting ensures that the MT::Entry objects returned are unique; if this flag were not given, two copies of the same MT::Entry could be returned, if two comments were made on the same entry.

unique

Boolean flag that ensures that the objects being returned are unique.

This is really only useful when used within a join, because when loading data out of a single object datastore, the objects are always going to be unique.

window_size => “N”

An optional attribute used only with the load_iter method. This attribute is used when requesting a result set of large or unknown size. If the load_iter method is called without any limit attribute, this is set to a default value of 100 (meaning, load 100 objects per SELECT). The iterator will yield the specified number of objects and then issue an additional select operation, using the same terms and attributes, adjusting for a new offset for the next set of objects.

Back