TSDRelation Class Reference
[Relationship Hierarchy Objects]

Represents link between two CSERD resources. More...

Inheritance diagram for TSDRelation:

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.

getParent ()

Does nothing because relationships don't have children or parents.

isValid ()

Determines if relationship is valid for the database.

listChildren ($constraints=array(), $limit=array(), $order=array(), $cnt=false)

Does nothing because relationships don't have children.

listValidChildren ($constraints=array(), $limit=array(), $order=array(), $cnt=false)

Does nothing because relationships don't have children.

set ($field, $value)

Needed to prevent invalid modifications of relationship.

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.

Protected Member Functions

populate ($version)

Populates relationship from database.

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:

id [int]: not relevant to the user (-)
sourceId [int]: first of two resource IDs that define the relationship (edit)
destId [int]: second of two resource IDs that define the relationship (edit)
description [string]: description of the relationship (edit)
version [string]: version of this relationship (either TSD::VERSION_DEV or TSD::VERSION_LIVE) (-)
status [string]: status of the version, relevant only for dev versions; is one of TSD::STATUS_NEW, TSD::STATUS_DELETED, TSD::STATUS_CHANGED, TSD::STATUS_APPROVED (live versions are always approved) (-)

Definition at line 51 of file TSDRelation.php5.

Constructor & Destructor Documentation

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

Creates new relationship object.

There are several ways to invoke this constructor:

new TSDRelation() -> creates brand new relationship
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
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
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

Definition at line 80 of file TSDRelation.php5.

References TSDObject::populate(), TSDObject::setAttr(), TSD::STATUS_NEW, TSD::VERSION_DEV, and 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

Definition at line 255 of file TSDRelation.php5.

References TSD::can(), TSDObject::checkInit(), isValid(), TSDObject::setAttr(), SObject::setError(), TSD::STATUS_APPROVED, TSD::STATUS_CHANGED, TSD::STATUS_DELETED, and TSD::VERSION_LIVE.

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

Definition at line 325 of file TSDRelation.php5.

References TSD::can(), TSDObject::checkInit(), isValid(), TSDObject::setAttr(), SObject::setError(), and TSD::STATUS_APPROVED.

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

Reimplemented from TSDObject.

Definition at line 192 of file TSDRelation.php5.

References TSD::can(), TSDObject::checkInit(), isValid(), TSDObject::setAttr(), SObject::setError(), TSD::STATUS_APPROVED, TSD::STATUS_CHANGED, and TSD::VERSION_DEV.

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

Reimplemented from TSDObject.

Definition at line 386 of file TSDRelation.php5.

References TSD::can(), TSDObject::checkInit(), isValid(), TSDObject::setAttr(), SObject::setError(), and TSD::STATUS_DELETED.

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

Reimplemented from TSDObject.

Definition at line 599 of file TSDRelation.php5.

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

Definition at line 489 of file TSDRelation.php5.

TSDRelation::getParent ( )

Does nothing because relationships don't have children or parents.

For internal use only.

Returns:: [null]: null

Reimplemented from TSDObject.

Definition at line 586 of file TSDRelation.php5.

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

Definition at line 508 of file TSDRelation.php5.

References TSD::getDBI(), SObject::getError(), TSDObject::limitToString(), TSD::MODE_ALL, TSD::MODE_APPROVED, TSD::MODE_CHANGED, TSD::MODE_DELETED, TSD::MODE_DEV, TSD::MODE_DEV_ACTIVE, TSD::MODE_DEV_UNAPPROVED, TSD::MODE_LIVE, TSD::MODE_NEW, and TSDObject::orderToString().

TSDRelation::isValid ( )

Determines if relationship is valid for the database.

A relationship is valid if the following requirements are met:

id is empty or a number greater than zero
sourceId is numeric and greater than zero
destId is numeric and greater than zero
sourceId is strictly less than destId
version is either TSD::VERSION_DEV or TSD::VERSION_LIVE
status is one of TSD::STATUS_NEW, TSD::STATUS_CHANGED, TSD::STATUS_DELETED, TSD::STATUS_APPROVED
if version is LIVE, then status must be TSD::STATUS_APPROVED

Returns:: [boolean]: whether relationship is valid

Reimplemented from TSDObject.

Definition at line 440 of file TSDRelation.php5.

References SObject::setError(), TSD::STATUS_APPROVED, TSD::STATUS_CHANGED, TSD::STATUS_DELETED, TSD::STATUS_NEW, TSD::VERSION_DEV, and TSD::VERSION_LIVE.

Referenced by approve(), cancel(), commit(), and delete().

TSDRelation::listChildren	(	$	constraints = `array()`,
		$	limit = `array()`,
		$	order = `array()`,
		$	cnt = `false`
	)

Does nothing because relationships don't have children.

For internal use only.

Parameters:

	$constraints	[array]: not used
	$limit	[array]: not used
	$order	[array]: not used
	$cnt	[boolean]: not used

Returns:: [null]: null

Reimplemented from TSDObject.

Definition at line 612 of file TSDRelation.php5.

TSDRelation::listValidChildren	(	$	constraints = `array()`,
		$	limit = `array()`,
		$	order = `array()`,
		$	cnt = `false`
	)

Does nothing because relationships don't have children.

For internal use only.

Parameters:

	$constraints	[array]: not used
	$limit	[array]: not used
	$order	[array]: not used
	$cnt	[boolean]: not used

Returns:: [null]: null

Reimplemented from TSDObject.

Definition at line 625 of file TSDRelation.php5.

TSDRelation::populate ( $ version ) [protected]

Populates relationship from database.

For internal use only.

This method is called by __construct() if a source and dest ID are provided to specify a relationship.

Parameters:

$version

[string]: either 'DEV' or 'LIVE': indicates which version of the relationship we should retrieve

Returns:: [boolean]: success or failure

Definition at line 132 of file TSDRelation.php5.

References TSDObject::checkInit(), TSDObject::setAttr(), SObject::setError(), TSD::STATUS_APPROVED, TSD::STATUS_NEW, and TSD::VERSION_DEV.

TSDRelation::set	(	$	field,
		$	value
	)

Needed to prevent invalid modifications of relationship.

For internal use only.

This prevents the user from modifying a LIVE version, or changing the sourceId/destId for a version that already exists in the database.

Parameters:

	$field	[string]: name of field
	$value	[string]: new value for field

Returns:: [boolean]: success or failure

Reimplemented from TSDObject.

Definition at line 109 of file TSDRelation.php5.

References SObject::setError(), and TSD::VERSION_LIVE.

The documentation for this class was generated from the following file:

tsd/TSDRelation.php5


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.
	getParent ()
	Does nothing because relationships don't have children or parents.
	isValid ()
	Determines if relationship is valid for the database.
	listChildren ($constraints=array(), $limit=array(), $order=array(), $cnt=false)
	Does nothing because relationships don't have children.
	listValidChildren ($constraints=array(), $limit=array(), $order=array(), $cnt=false)
	Does nothing because relationships don't have children.
	set ($field, $value)
	Needed to prevent invalid modifications of relationship.
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.
Protected Member Functions
	populate ($version)
	Populates relationship from database.

TSDRelation Class Reference [Relationship Hierarchy Objects]

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

TSDRelation Class Reference
[Relationship Hierarchy Objects]