RT 5.0.6 Documentation

RT::Record::AddAndSort

NAME

RT::Record::AddAndSort - base class for records that can be added and sorted

DESCRIPTION

Base class for RT::ObjectCustomField and RT::ObjectScrip that unifies application of RT::CustomFields and RT::Scrips to various objects. Also, deals with order of the records.

METHODS

Meta information

CollectionClass

Returns class representing collection for this record class. Basically adds 's' at the end. Should be overridden if default doesn't work.

For example returns RT::ObjectCustomFields when called on RT::ObjectCustomField.

Returns name of the field in the table where id of object we add is stored. By default deletes everything up to '::Object' from class name. This method allows to use friendlier argument names and methods.

For example returns 'Scrip' for RT::ObjectScrip.

ObjectCollectionClass

Takes an object under "TargetField" name and should return class name representing collection the object can be added to.

Must be overridden by sub classes.

See "ObjectCollectionClass" in RT::ObjectScrip and "CollectionClass" in RT::ObjectCustomField.

Manipulation

Create

Takes 'ObjectId' with id of an object we can be added to, object we can add to under "TargetField" name, Disabled and SortOrder.

This method doesn't create duplicates. If record already exists then it's not created, but loaded instead. Note that nothing is updated if record exist.

If SortOrder is not defined then it's calculated to place new record last. If it's provided then it's caller's duty to make sure it is correct value.

Example:

    my $ocf = RT::ObjectCustomField->new( RT->SystemUser );
    my ($id, $msg) = $ocf->Create( CustomField => 1, ObjectId => 0 );

See "Add" which has more error checks. Also, RT::Scrip and RT::CustomField have more appropriate methods that should be preferred over calling this directly.

Add

Helper method that wraps "Create" and does more checks to make sure result is consistent. Doesn't allow adding a record to an object if the record is already global. Removes record from particular objects when asked to add the record globally.

AddedTo

Returns collection with objects target of this record is added to. Class of the collection depends on "ObjectCollectionClass". See all "NotAddedTo".

For example returns RT::Queues collection if the target is RT::Scrip.

Returns empty collection if target is added globally.

NotAddedTo

Returns collection with objects target of this record is not added to. Class of the collection depends on "ObjectCollectionClass". See all "AddedTo".

Returns empty collection if target is added globally.

Delete

Deletes this record.

DeleteAll

Helper method to delete all applications for one target (Scrip, CustomField, ...). Target can be provided in arguments. If it's not then "TargetObj" is used.

    $object_scrip->DeleteAll;

    $object_scrip->DeleteAll( Scrip => $scrip );

MoveUp

Moves record up.

MoveDown

Moves record down.

Move

Takes 'up' or 'down'. One method that implements "MoveUp" and "MoveDown".

Accessors, introspection and traversing.

TargetObj

Returns target object of this record. Returns RT::Scrip object for RT::ObjectScrip.

NextSortOrder

Returns next available SortOrder value in the neighborhood. Pass arguments to "Neighbors" and can take optional ObjectId argument, calls ObjectId if it's not provided.

LastSibling

Returns the object with maximum SortOrder in the neighborhood. Pass arguments to "Neighbors" and can take optional ObjectId argument, calls ObjectId if it's not provided.

IsSortOrderShared

Returns true if this record shares SortOrder value with a neighbor.

Neighbors and Siblings

These two methods should only be understood by developers who wants to implement new classes of records that can be added to other records and sorted.

Main purpose is to maintain SortOrder values.

Let's take a look at custom fields. A custom field can be created for tickets, queues, transactions, users... Custom fields created for tickets can be added globally or to particular set of queues. Custom fields for tickets are neighbors. Neighbor custom fields added to the same objects are siblings. Custom fields added globally are sibling to all neighbors.

For scrips Stage defines neighborhood.

Let's look at the three scrips in create stage S1, S2 and S3, queues Q1 and Q2 and G for global.

    S1@Q1, S3@Q2 0
    S2@G         1
    S1@Q2        2

Above table says that S2 is added globally, S1 is added to Q1 and executed before S2 in this queue, also S1 is added to Q1, but executed after S2 in this queue, S3 is only added to Q2 and executed before S2 and S1.

Siblings are scrips added to an object including globally added or only globally added. In our example there are three different collection of siblings: (S2) - global, (S1, S2) for Q1, (S3, S2, S1) for Q2.

Sort order can be shared between neighbors, but can not be shared between siblings.

Here is what happens with sort order if we move S1@Q2 one position up:

           S3@Q2 0
    S1@Q1, S1@Q2 1
    S2@G         2

One position more:

           S1@Q2 0
    S1@Q1, S3@Q2 1
    S2@G         2

Hopefully it's enough to understand how it works.

Targets from different neighborhood can not be sorted against each other.

Neighbors

Returns collection of records of this class with all neighbors. By default all possible targets are neighbors.

Takes the same arguments as "Create" method. If arguments are not passed then uses the current record.

See "Neighbors and Siblings" for detailed description.

See "Neighbors" in RT::ObjectCustomField for example.

Siblings

Returns collection of records of this class with siblings.

Takes the same arguments as "Neighbors". Siblings is subset of "Neighbors".

← Back to index