TSDRelation Class Reference
[Relationship Hierarchy Objects]

Represents link between two CSERD resources. More...

Inheritance diagram for TSDRelation:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 __construct ($sourceId= '', $destId= '', $version=TSD::VERSION_LIVE)
 Creates new relationship object.
 approve ()
 Approve this relationship.
 cancel ()
 Cancels pending changes to a relationship.
 commit ()
 Commits relationship to database.
 delete ()
 Marks relationship as DELETED.
 getIdentifier ()
 Generates useful identifier for this relationship.
 isValid ()
 Determines if relationship is valid for the database.

Static Public Member Functions

static getList ($constraints=array(), $limit=array(), $order=array(), $cnt=false)
 Retrieves list of relationships based on criteria.
static getRelated ($itemUrlOrId, $mode=TSD::MODE_LIVE, $cnt=false, $limit=array(), $order=array())
 Retrieves list of relationships for a given resource.

Detailed Description

Represents link between two CSERD resources.

A relationship between two resources indicates that they have some meaningful connection. For example, in Interactivate, related resources will be listed when viewing an activity or lesson. The relationship, at the very least, simply names the two resources that are being related. You can also provide a description of that relationship (which can also serve as a "reason" for the relationship).

To create a new relationship, first construct either an empty relationship object or create one with the desired resource IDs. Note that the first resource ID (the source ID) must be strictly less than the second resource ID (the dest ID): 

 # create empty relation and fill it in later
 $rel = new TSDRelation();
 $rel->sourceId = 37;
 $rel->destId = 48;
 $rel->description = "Important relationship";
 $rel->commit();

 # OR
 $rel = new TSDRelation(37, 48);
 # ... and the rest is the same
Once a relationship is created, it must be approved (or canceled), using the approve() (and cancel()) method.

You can modify an existing relationship like so: 

 $rel = new TSDRelation(37, 48, TSD::VERSION_DEV);
 $rel->description = 'a new description';
 $rel->commit();
 $rel->approve();
Note that you must specify that the relationship be a TSD::VERSION_DEV relationship, since you cannot modify live versions.

Attributes:

Constructor & Destructor Documentation

TSDRelation::__construct ( $  sourceId = '',
$  destId = '',
$  version = TSD::VERSION_LIVE 
)

Creates new relationship object.

There are several ways to invoke this constructor:

  1. new TSDRelation() -> creates brand new relationship
  2. new TSDRelation(37, 48) -> can mean two things:
    1. If relationship 37 -> 48 is in database, then creates a new object representing the LIVE version of that relationship
    2. If relationship is not in the database, creates new DEV version with source ID and dest ID pre-filled to be 37 and 48 (so mostly equivalent to the first invocation
  3. new TSDRelation(37, 48, TSD::VERSION_DEV) -> creates object representing DEV version of relationship in DB, if it exists, otherwise is equivalent to 2b above
  4. new TSDRelation(37, 48, TSD::VERSION_LIVE) -> equivalent to 2a above

Parameters:
$sourceId [int]: source ID of relationship
$destId [int]: dest ID of relationship
$version [string]: which version to instantiate, one of TSD::VERSION_DEV, TSD::VERSION_LIVE

Member Function Documentation

TSDRelation::approve (  ) 

Approve this relationship.

When a relationship is approved, a LIVE version is either created or updated based on the DEV version. If the relationship to be approved is marked as DELETED, then both the DEV version and the LIVE version will be deleted. You cannot approve LIVE versions. You must have the 'approve' permission to approve relationships.

Returns:
[boolean]: success or failure

TSDRelation::cancel (  ) 

Cancels pending changes to a relationship.

If a DEV relationship has been modified, marked as DELETED, or created (and thus marked as NEW) but not yet approved, then you can cancel those changes and restore the DEV relationship to the value of the LIVE version, or, in the case of a DEV relationship marked as NEW, simply remove the relationship altogether. You must have the 'approve' permission to cancel changes.

Returns:
[boolean]: success or failure

TSDRelation::commit (  ) 

Commits relationship to database.

If relationship is already in the database, then its information is merely updated. Otherwise, relationship is added to database. New relationships are always marked as DEV and NEW. You cannot commit LIVE relationships. Instead, create a TSDRelation object for the DEV version and then modify that, commit it and then approve it. You cannot change the source and destination ID for a relationship. That would entail creating a new relationship altogether.

Returns:
[boolean]: success or failure

TSDRelation::delete (  ) 

Marks relationship as DELETED.

You can only delete DEV versions. If the version is NEW, then it is simply removed from the DB. You must have the 'align' permission to delete relationships.

Returns:
[boolean]: success or failure

TSDRelation::getIdentifier (  ) 

Generates useful identifier for this relationship.

The identifier can be used as a nice way to represent the relationship in text. For this class, the identifier is guaranteed to be unique. Currently, it is the source ID and dest ID as a tuple surrounded by parentheses (e.g.: "(37, 48)")

Returns:
[string]: relationship identifier

static TSDRelation::getList ( $  constraints = array(),
$  limit = array(),
$  order = array(),
$  cnt = false 
) [static]

Retrieves list of relationships based on criteria.

See Guide to Database Constraints for more information on how to build the parameters to this method.

Parameters:
$constraints [array]: additional constraints on the result set
$limit [array]: parameters for the LIMIT clause of the query
$order [array]: how to order the results
$cnt [boolean]: whether to return the number of results (if true) or the results themselves (if false, the default)
Returns:
[array]: array of results, if any, or an integer specifying the number of results that would have been returned (if $cnt == true), or null if there was an error

static TSDRelation::getRelated ( $  itemUrlOrId,
$  mode = TSD::MODE_LIVE,
$  cnt = false,
$  limit = array(),
$  order = array() 
) [static]

Retrieves list of relationships for a given resource.

Parameters:
$itemUrlOrId [mixed]: specifies the resource for which to retrieve the list of relationships
$mode [int]: only include relationships that have this mode (see TSD::MODE_* constants)
$cnt [boolean]: if true, only return a count of how many relationships would be returned, otherwise, return the full listing
$limit [array]: set limit on number of items returned (see Guide to Database Constraints)
$order [array]: set the ordering on the items returned (see Guide to Database Constraints)
Returns:
[array]: array of TSDRelation objects, or count of how many would be returned, or null on error

TSDRelation::isValid (  ) 

Determines if relationship is valid for the database.

A relationship is valid if the following requirements are met:

Returns:
[boolean]: whether relationship is valid

The documentation for this class was generated from the following file:
Generated on Wed Nov 24 02:04:55 2010 for Common by  doxygen 1.5.6