SnapVersion Class Reference
[File Objects]

Wrapper class for Snap2 versions. More...

Inheritance diagram for SnapVersion:

List of all members.

Public Member Functions

__call ($name, $args)

__construct ($id= '')

approveForDev ()

Marks a version as visible on the dev site.

approveForLive ()

Marks a version as visible on the live site.

defunct ()

Mark this version as being defunct (inactive).

deny ()

Return a 'Pending' version to the 'In Progress' state.

destroy ()

Permanently delete version.

getAllPaths ()

INSERT BRIEF DESCRIPTION HERE.

getCanonicalPath ()

Retrieves canonical path of this version.

listActions ($constraint=array(), $limit=array(), $order=array())

Retrieves list of actions performed on this version.

steal ()

Take control of an 'In Progress' version.

submit ()

Marks a version as 'Pending'.

systemDestroy ()

toCacheDump ()

update ($newCM)

Updates the content of a version.

Static Public Member Functions

static lookup ($path)

Retrieve version by path.

static retrieve ($id)

Retrieves version by ID.

Public Attributes

const STATUS_DEFUNCT

Version is in 'Defunct' state (zombie).

const STATUS_DEV

Version is in 'Dev' state (visible on dev site).

const STATUS_LIVE

Version is in 'Live' state (visible on live site).

const STATUS_PENDING

Version is in 'Pending' state (ready to be approved for dev or live).

const STATUS_PRIVATE

Version is in 'In Progress' state (can be edited).

Static Public Attributes

static $ATTRIBUTES

static $STAT_NAMES

static $STAT_VALUES

Protected Member Functions

_canApproveForDev ()

_canApproveForLive ()

_canDefunct ()

_canDeny ()

_canDestroy ()

_canSteal ()

_canSubmit ()

_canUpdate ($newCM=null)

loadContentModule ()

loadPrevVersion ()

loadResource ()

logAction ($action)

populate ()

Detailed Description

Wrapper class for Snap2 versions.

A version represents a particular revision of content for a resource. A resource may contain multiple versions, but a version belongs to only one resource. A version will be in one of many states:

In Progress: version is being developed and revised; not ready to be put on the website
Pending: version is waiting to be approved for display on the website; it can also be denied and put back in the 'In Progress' state
Dev: version is visible on the dev site only (currently, newdev is the only dev site)
Live: version is visible on the live site, and also the dev site if there is no dev version for the resource
Defunct: version is not active in any way and can either be destroyed (completely removed from Snap) or copied to create a new version; old dev and live versions are defuncted if they are replaced by a new dev or live version.

Most of the code in this class exists to facilitate the lifecycle described above. Versions also keep track of when these lifecycle changes occur, and a listing of those actions can be retrieved with listActions(). It is important to note that the version, not the resource, actually stores the content. A resource represents a logical piece of content, a version actually contains it.

Constants:

STATUS_PRIVATE: Version is in 'In Progress' state
STATUS_PENDING: Version is in 'Pending' state
STATUS_DEV: Version is in 'Dev' state (visible on dev site)
STATUS_LIVE: Version is in 'Live' state (visible on live site)
STATUS_DEFUNCT: Version is in 'Defunct' state (zombie)

Attributes:

id: Version ID
created: Date/time when version was created
modified: Date/time when version was last modified
author: User ID of user who created or last edited the version
status: Current state of version (one of the STATUS_* constants)
ordinal: Essentially, the index of the version within its resource
content: Raw content of version (use getContentModule() instead of querying the content directly)
resourceId: ID of resource to which this version belongs
prevVersionId: ID of version from which this version was copied, if this version was, in fact, copied

Fields:

resource: SnapResource object to which this version belongs
contentModule: SnapContent object derivative which represents the content in this version
prevVersion: SnapVersion object from which this version was copied, or null if there was no copy

Definition at line 47 of file SnapVersion.php5.

Constructor & Destructor Documentation

SnapVersion::__construct ( $ id = '' )

For internal use only.

Definition at line 91 of file SnapVersion.php5.

References populate(), and SnapObject::setSave().

Member Function Documentation

SnapVersion::__call	(	$	name,
		$	args
	)

For internal use only.

Implements canXxx() methods

Reimplemented from SnapObject.

Definition at line 219 of file SnapVersion.php5.

SnapVersion::_canApproveForDev ( ) [protected]

For internal use only.

Definition at line 452 of file SnapVersion.php5.

SnapVersion::_canApproveForLive ( ) [protected]

For internal use only.

Definition at line 467 of file SnapVersion.php5.

SnapVersion::_canDefunct ( ) [protected]

For internal use only.

Definition at line 483 of file SnapVersion.php5.

SnapVersion::_canDeny ( ) [protected]

For internal use only.

Definition at line 513 of file SnapVersion.php5.

SnapVersion::_canDestroy ( ) [protected]

For internal use only.

Definition at line 498 of file SnapVersion.php5.

SnapVersion::_canSteal ( ) [protected]

For internal use only.

Definition at line 388 of file SnapVersion.php5.

SnapVersion::_canSubmit ( ) [protected]

For internal use only.

Definition at line 437 of file SnapVersion.php5.

SnapVersion::_canUpdate ( $ newCM = null ) [protected]

For internal use only.

Definition at line 408 of file SnapVersion.php5.

SnapVersion::approveForDev ( )

Marks a version as visible on the dev site.

The version must be in the 'Pending' state to be marked as dev. You must also have the ApproveDev permission on the version's resource, or AdminResource to approve for dev. The old dev version becomes defunct after this operation.

Returns:: [boolean]: success or failure

Definition at line 632 of file SnapVersion.php5.

SnapVersion::approveForLive ( )

Marks a version as visible on the live site.

The version must either be in the 'Pending' state or the 'Dev' state to be approved for live. You must also have the ApproveLive permission on the version's resource, or AdminResource. The old live version is marked as defunct, and if this version was dev previously, there will no longer be a dev version for the resource.

Returns:: [boolean]: success or failure

Definition at line 702 of file SnapVersion.php5.

SnapVersion::defunct ( )

Mark this version as being defunct (inactive).

Once a version is defuncted, it can no longer be used in any capacity, except to be copied from. To defunct a version, it must not already be defunct (for obvious reasons), and you must have the Edit permission to defunct an 'In Progress' or 'Pending' version, ApproveDev to defunct a 'Dev' version, ApproveLive to defunct a 'Live' version, or AdminResource to defunct all states. If the version was dev or live, then there will no longer be a dev or live version for the resource.

Returns:: [boolean]: success or failure

Definition at line 806 of file SnapVersion.php5.

SnapVersion::deny ( )

Return a 'Pending' version to the 'In Progress' state.

The use case for this method is that a version may need more work before it could be considered ready for approval. In order to deny a version, the version must be in the 'Pending' state and you must have ApproveDev or ApproveLive permission on the version's resource, or AdminResource.

Returns:: [boolean]: success or failure

Definition at line 918 of file SnapVersion.php5.

SnapVersion::destroy ( )

Permanently delete version.

When a version is destroyed, any external files associated with its content are deleted, and the version is removed from the database. This operation cannot be undone. You must have AdminResource on the version's resource to perform this operation.

Returns:: [boolean]: success or failure

Definition at line 874 of file SnapVersion.php5.

SnapVersion::getAllPaths ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1060 of file SnapVersion.php5.

SnapVersion::getCanonicalPath ( )

Retrieves canonical path of this version.

The canonical path of a version is just the canonical path of its resource with '@' and the version's ordinal appended. For example, '//test/foo@5'.

Returns:: [string]: canonical path of version, or false if version is invalid

Definition at line 1048 of file SnapVersion.php5.

SnapVersion::listActions	(	$	constraint = `array()`,
		$	limit = `array()`,
		$	order = `array()`
	)

Retrieves list of actions performed on this version.

Actions are things like "Edit", "Submit", etc. That is, changes in state of a version. This is useful for tracking progress. This method will list those actions for just this version. The result array consists of subarrays which contain three fields: 'uid', which is the user ID of the user who performed the action; 'action', which is a string naming the action; 'actionTime', which is a MySQL timestamp of when the action occurred; and 'id', which is the ID of the version upon which the action was performed.

This method allows you to trim down the result set and sort it, mostly arbitrarily. The first parameter can be an array that specifies constraints that are converted into a WHERE clause on the database query. See [[SWAT_Model2::Simple_Entities]] for more on how to specify a constraint array. The second parameter lets you limit the number of results. As a simple number, a 'LIMIT x' is appended to the query. If an array of two numbers is given, then the first number specifies the offset to start the resultset at and the second specifies the number of records after that. The final parameter specifies how to order the results. If the elements in the array are not associative, then they are passed directly to the ORDER BY clause as is. If they are associative, then the key specifies the column and the value specifies either ASC or DESC.

Parameters:

	$constraint	[array]: trim down results by conditions
	$limit	[array]: limit number of results by count and offset
	$order	[array]: sort results

Returns:: [array]: array of action info arrays (see description above), or null on error

Definition at line 1014 of file SnapVersion.php5.

SnapVersion::loadContentModule ( ) [protected]

For internal use only.

Dyanmic loader that loads content module for this version

Definition at line 159 of file SnapVersion.php5.

References SnapContent::getContentModule(), SnapObject::getId(), SnapObject::getType(), and SnapCache::updateById().

SnapVersion::loadPrevVersion ( ) [protected]

For internal use only.

Dynamic loader that loads previous version object from which this version was copied

Definition at line 170 of file SnapVersion.php5.

References SnapObject::getId(), SnapObject::getType(), retrieve(), and SnapCache::updateById().

SnapVersion::loadResource ( ) [protected]

For internal use only.

Dynamic loader that loads resource for this version

Definition at line 148 of file SnapVersion.php5.

References SnapObject::getId(), SnapObject::getType(), SnapResource::retrieve(), and SnapCache::updateById().

SnapVersion::logAction ( $ action ) [protected]

For internal use only.

Puts a user action in the log

Parameters:

$action

[string]: name of action to log

Definition at line 197 of file SnapVersion.php5.

References Snap2::getCurrentUser(), SnapObject::getId(), and SnapDBI::startTransaction().

static SnapVersion::lookup ( $ path ) [static]

Retrieve version by path.

Use this method to retrieve a version if you know its path. There is no other way to retrieve a version by path, so don't even try.

Parameters:

$path

[string]: path to version

Returns:: [SnapVersion]: version object pointed to by path, or null on failure or invalid path

Definition at line 274 of file SnapVersion.php5.

References Snap2::checkInit(), SnapCache::getByPath(), and SConfig::getOption().

Referenced by SnapObject::convertReference(), and Snap2::lookup().

SnapVersion::populate ( ) [protected]

For internal use only.

Reimplemented from SnapObject.

Definition at line 113 of file SnapVersion.php5.

References SnapObject::checkValid(), SnapDBI::firstRow(), SnapDBI::freeResult(), SnapObject::getId(), SnapDBI::getNumRows(), SnapObject::getType(), SnapDBI::query(), SObject::setError(), SnapObject::setValid(), SObject::setWarning(), and SnapCache::updateById().

Referenced by __construct().

static SnapVersion::retrieve ( $ id ) [static]

Retrieves version by ID.

Use this method to retrieve a version if you know its ID. Do not construct a version directly, or bad things will happen.

Parameters:

$id

[integer]: ID of version to retrieve

Returns:: [SnapVersion]: version object for ID, or null on failure or invalid ID

Definition at line 244 of file SnapVersion.php5.

References Snap2::checkInit(), SnapCache::getById(), and SnapCache::putById().

Referenced by SnapBulkAction::bulkApprove(), SnapObject::convertReference(), SnapResource::loadDevVersion(), SnapResource::loadLiveVersion(), and loadPrevVersion().

SnapVersion::steal ( )

Take control of an 'In Progress' version.

Only the current author of a version can edit it. If you have Edit permission, or AdminResource on the version's resource, then you can steal the version and now you can edit it. The version must be in the 'In Progress' state to steal it.

Returns:: [boolean]: success or failure

Definition at line 956 of file SnapVersion.php5.

SnapVersion::submit ( )

Marks a version as 'Pending'.

If a version is in the 'In Progress' state it can be marked as ready for approval (or denial) using this method. You must have the Edit permission on the version's owning resource, or AdminResource.

Returns:: [boolean]: success or failure

Definition at line 595 of file SnapVersion.php5.

SnapVersion::systemDestroy ( )

For internal use only.

Destroys content for this version; called by SnapResource::doDestroy()

Definition at line 184 of file SnapVersion.php5.

References SnapObject::setValid().

SnapVersion::toCacheDump ( )

For internal use only.

Reimplemented from SnapObject.

Definition at line 106 of file SnapVersion.php5.

SnapVersion::update ( $ newCM )

Updates the content of a version.

This method modifies the content of the version. You must pass in a content module which contains information about the new content. That content module should be created directly and then modified with an appropriate modification function (see the documentation of the relevant content module for more). Typically, you would call this method in the following fashion: $cm = new SnapContentXml($version); $cm->setXML('...some xml string...'); $version->update($cm); You must have the Edit permission on the version's resource to update the version. AdminResource and the ADMIN privilege also work. The version must also be in the 'In Progress' state to be updated.

Parameters:

$newCM

[SnapContent]: content module describing new content

Returns:: [boolean]: success or failure

Definition at line 548 of file SnapVersion.php5.

Member Data Documentation

SnapVersion::$ATTRIBUTES [static]

Database attributes

Definition at line 84 of file SnapVersion.php5.

Referenced by SnapSearch::execute().

SnapVersion::$STAT_NAMES [static]

Array that associates status constants with friendly names, like 'In Progress'

Definition at line 62 of file SnapVersion.php5.

SnapVersion::$STAT_VALUES [static]

Array that associates standard friendly names, like 'In Progress', with status constants

Definition at line 73 of file SnapVersion.php5.

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

snap2/objects/SnapVersion.php5


Public Member Functions
	__call ($name, $args)
	__construct ($id= '')
	approveForDev ()
	Marks a version as visible on the dev site.
	approveForLive ()
	Marks a version as visible on the live site.
	defunct ()
	Mark this version as being defunct (inactive).
	deny ()
	Return a 'Pending' version to the 'In Progress' state.
	destroy ()
	Permanently delete version.
	getAllPaths ()
	INSERT BRIEF DESCRIPTION HERE.
	getCanonicalPath ()
	Retrieves canonical path of this version.
	listActions ($constraint=array(), $limit=array(), $order=array())
	Retrieves list of actions performed on this version.
	steal ()
	Take control of an 'In Progress' version.
	submit ()
	Marks a version as 'Pending'.
	systemDestroy ()
	toCacheDump ()
	update ($newCM)
	Updates the content of a version.
Static Public Member Functions
static	lookup ($path)
	Retrieve version by path.
static	retrieve ($id)
	Retrieves version by ID.
Public Attributes
const	STATUS_DEFUNCT
	Version is in 'Defunct' state (zombie).
const	STATUS_DEV
	Version is in 'Dev' state (visible on dev site).
const	STATUS_LIVE
	Version is in 'Live' state (visible on live site).
const	STATUS_PENDING
	Version is in 'Pending' state (ready to be approved for dev or live).
const	STATUS_PRIVATE
	Version is in 'In Progress' state (can be edited).
Static Public Attributes
static	$ATTRIBUTES
static	$STAT_NAMES
static	$STAT_VALUES
Protected Member Functions
	_canApproveForDev ()
	_canApproveForLive ()
	_canDefunct ()
	_canDeny ()
	_canDestroy ()
	_canSteal ()
	_canSubmit ()
	_canUpdate ($newCM=null)
	loadContentModule ()
	loadPrevVersion ()
	loadResource ()
	logAction ($action)
	populate ()

SnapVersion Class Reference [File Objects]

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

SnapVersion Class Reference
[File Objects]