class Collection extends ConcreteObject implements TrackableInterface (View source)

Properties

$error from  ConcreteObject
int|null deprecated $cID

The collection ID.

protected Version|null $vObj

The collection version object.

protected string|null $cHandle

The collection handle.

protected string|null $cDateAdded

The date/time when the collection has been created.

protected string|null $cDateModified

The date/time when the collection was last modified.

protected array $attributes

Methods

loadError($error)

No description

isError()

No description

getError()

No description

setPropertiesFromArray($arr)

No description

static 
camelcase($file)

No description

static 
uncamelcase($string)

No description

__destruct()

Destruct the class instance.

static Collection
getByID(int $cID, string|int|false $version = 'RECENT')

Get a collection by ID.

static Collection|null
getByHandle(string $handle)

Get a Collection by handle (provided that it's not a Page handle).

static int
reindexPendingPages()

(Re)Index all the collections that are marked as to be (re)indexed.

static Collection
createCollection(array $data)

Create a new Collection instance.

int|null
getCollectionID()

Get the collection ID.

string|null
getCollectionHandle()

Get the collection handle.

string|null
getCollectionDateLastModified()

Get the date/time when the collection was last modified.

string|null
getCollectionDateAdded()

Get the date/time when the collection has been created.

int
getVersionID()

Get the ID of the currently loaded version.

Version|null
getVersionObject()

Get the currently loaded version object.

addCollection(array $data)

Create a new Collection instance, using the same theme as this instance (if it's a Page instance).

loadVersionObject(string|int $cvID = 'ACTIVE')

Load a specific collection version (you can retrieve it with the getVersionObject() method).

$this|Page
getVersionToModify()

Get the Collection instance to be modified (this instance if it's a new or master Collection, a clone otherwise).

string
getNextVersionComments()

Get the automatic comment for the next collection version.

reindex()

No description

setAttribute(string|CollectionKey $ak, AbstractValue|mixed $value, bool $doReindexImmediately = true)

Set the attribute value for the currently loaded collection version.

mixed|null
getAttribute(string|CollectionKey $akHandle, string|false $displayMode = false)

Return the value of the attribute with the handle $akHandle of the currently loaded version (if it's loaded).

PageValue|null
getAttributeValueObject(string|CollectionKey $akHandle, bool $createIfNotExists = false)

Return the attribute value object with the handle $akHandle of the currently loaded version (if it's loaded).

clearCollectionAttributes(int[] $retainAKIDs = [])

Delete the values of the attributes associated to the currently loaded collection version.

clearAttribute(string|CollectionKey $ak, bool $doReindexImmediately = true)

Delete the value of a specific attribute key associated to the currently loaded collection version.

getSetCollectionAttributes()

Get the list of attribute keys for which the currently loaded collection version has values.

Area|null
getArea(string $arHandle)

Get an existing area associated to this collection.

bool
hasAliasedContent()

Does this collection contain blocks that are aliased in other pages?

getAreaCustomStyle(Area $area, bool $force = false)

Get the custom style of an area in the currently loaded collection version.

setCustomStyleSet(Area $area, StyleSet $set)

Set the custom style of an area in the currently loaded collection version.

resetAreaCustomStyle(Area $area)

Delete all the custom styles of an area of the currently loaded collection version.

string|null
outputCustomStyleHeaderItems(bool $return = false)

Retrieve all custom style rules that should be inserted into the header on a page, whether they are defined in areas or blocks.

null|false
relateVersionEdits(Collection $oc)

Associate the edits of another collection to this collection.

int|false
getPageTypeID()

Returns the ID of the page/collection type.

refreshCache()

Empty the collection-related cache.

Block[]
getGlobalBlocks()

Get the blocks contained in all the global areas in this collection.

array
getGlobalBlockIDs()

Get the IDs for blocks contained in all the global areas in this collection.

Stack[]
getGlobalStacksForCollection()

Get all the global stacks loaded in this collection.

Block[]
getBlocks(string|false $arHandle = false)

List the blocks in the currently loaded collection version (or in a specific area within it).

array
getBlockIDs(string|false $arHandle = false)

List the block IDs and the associated area handles in the currently loaded collection version (or in a specific area within it).

addBlock(BlockType $bt, string|Area $a, array $data)

Add a new block to a specific area of the currently loaded collection version.

int
getCollectionAreaDisplayOrder(string $arHandle, bool $ignoreVersions = false)

Get the next value of the display order (to be used when adding new blocks to an area).

rescanDisplayOrder(string $arHandle)

Fix the display order properties for all the blocks within the collection/area.

void
rescanDisplayOrderFromBlock(Block $block, string $arHandle, int $fromDisplay = null)

Fix the display order properties for all the blocks after this block in this area.

markModified()

Update the last edit date/time.

delete()

Delete this collection, and all its versions, contents and attributes.

duplicateCollection()

Create a clone of this collection, and all its versions, contents and attributes.

cloneVersion(string|null $versionComments, bool $createEmpty = false)

Clone the currently loaded version and returns a Page instance containing the new version.

PageValue|null
getAttributeValue(string|CollectionKey $ak) deprecated

No description

mixed|null
getCollectionAttributeValue(string|CollectionKey $akHandle) deprecated

No description

getCollectionTypeID() deprecated

No description

Details

loadError($error)

No description

Parameters

$error

isError()

No description

getError()

No description

setPropertiesFromArray($arr)

No description

Parameters

$arr

static camelcase($file)

No description

Parameters

$file

static uncamelcase($string)

No description

Parameters

$string

__destruct()

Destruct the class instance.

static Collection getByID(int $cID, string|int|false $version = 'RECENT')

Get a collection by ID.

Parameters

int $cID

The collection ID

string|int|false $version

the collection version ('RECENT' for the most recent version, 'ACTIVE' for the currently published version, 'SCHEDULED' for the currently scheduled version, a falsy value to not load the collection version, or an integer to retrieve a specific version ID)

Return Value

Collection

If the collection is not found, you'll get an empty Collection instance

static Collection|null getByHandle(string $handle)

Get a Collection by handle (provided that it's not a Page handle).

If there's there's no collection with the specified handle, a new Collection will be created.

Parameters

string $handle

the collection handle

Return Value

Collection|null

return NULL if $handle is the handle of an existing page

static int reindexPendingPages()

(Re)Index all the collections that are marked as to be (re)indexed.

Return Value

int

returns the number of reindexed pages

static Collection createCollection(array $data)

Create a new Collection instance.

Parameters

array $data

{

@var int|null $cID The ID of the collection to create (if unspecified or NULL: database autoincrement value)
@var string $handle The collection handle (default: NULL)
@var string $name The collection name (default: empty string)
@var string $cDescription The collection description (default: NULL)
@var string $cDatePublic The collection publish date/time in format 'YYYY-MM-DD hh:mm:ss' (default: now)
@var bool $cvIsApproved Is the collection version approved (default: true)
@var bool $cvIsNew Is the collection to be considered "new"? (default: true if $cvIsApproved is false, false if $cvIsApproved is true)
@var int|null $pThemeID The collection theme ID (default: NULL)
@var int|null $pTemplateID The collection template ID (default: NULL)
@var int|null $uID The ID of the collection author (default: NULL)

}

Return Value

Collection

int|null getCollectionID()

Get the collection ID.

Return Value

int|null

string|null getCollectionHandle()

Get the collection handle.

Return Value

string|null

string|null getCollectionDateLastModified()

Get the date/time when the collection was last modified.

Return Value

string|null

Examples

2017-12-31 23:59:59

string|null getCollectionDateAdded()

Get the date/time when the collection has been created.

Return Value

string|null

Examples

2017-12-31 23:59:59

int getVersionID()

Get the ID of the currently loaded version.

Return Value

int

Version|null getVersionObject()

Get the currently loaded version object.

Return Value

Version|null

Collection addCollection(array $data)

Create a new Collection instance, using the same theme as this instance (if it's a Page instance).

Parameters

array $data

{

@var int|null $cID The ID of the collection to create (if unspecified or NULL: database autoincrement value)
@var string $handle The collection handle (default: NULL)
@var string $name The collection name (default: empty string)
@var string $cDescription The collection description (default: NULL)
@var string $cDatePublic The collection publish date/time in format 'YYYY-MM-DD hh:mm:ss' (default: now)
@var bool $cvIsApproved Is the collection version approved (default: true)
@var bool $cvIsNew Is the collection to be considered "new"? (default: true if $cvIsApproved is false, false if $cvIsApproved is true)
@var int|null $pTemplateID The collection template ID (default: NULL)
@var int|null $uID The ID of the collection author (default: NULL)

}

Return Value

Collection

loadVersionObject(string|int $cvID = 'ACTIVE')

Load a specific collection version (you can retrieve it with the getVersionObject() method).

Parameters

string|int $cvID

the collection version ('RECENT' for the most recent version, 'ACTIVE' for the currently published version, 'SCHEDULED' for the currently scheduled version, or an integer to retrieve a specific version ID)

$this|Page getVersionToModify()

Get the Collection instance to be modified (this instance if it's a new or master Collection, a clone otherwise).

Return Value

$this|Page

string getNextVersionComments()

Get the automatic comment for the next collection version.

Return Value

string

Example: 'Version 2'

reindex()

No description

PageValue setAttribute(string|CollectionKey $ak, AbstractValue|mixed $value, bool $doReindexImmediately = true)

Set the attribute value for the currently loaded collection version.

Parameters

string|CollectionKey $ak

the attribute key (or its handle)

AbstractValue|mixed $value

an attribute value object, or the data needed by the attribute controller to create the attribute value object

bool $doReindexImmediately

Return Value

PageValue

mixed|null getAttribute(string|CollectionKey $akHandle, string|false $displayMode = false)

Return the value of the attribute with the handle $akHandle of the currently loaded version (if it's loaded).

Parameters

string|CollectionKey $akHandle

the attribute key (or its handle)

string|false $displayMode

makes The format of the attribute value

Return Value

mixed|null

Examples

When you need the raw attribute value or object, use this:
<code>
$c = Page::getCurrentPage();
$attributeValue = $c->getAttribute('attribute_handle');
</code>
If you need the formatted output supported by some attribute, use this:
<code>
$c = Page::getCurrentPage();
$attributeValue = $c->getAttribute('attribute_handle', 'display');
</code>
An attribute type like "date" will then return the date in the correct format just like other attributes will show you a nicely formatted output and not just a simple value or object.

PageValue|null getAttributeValueObject(string|CollectionKey $akHandle, bool $createIfNotExists = false)

Return the attribute value object with the handle $akHandle of the currently loaded version (if it's loaded).

Parameters

string|CollectionKey $akHandle

the attribute key (or its handle)

bool $createIfNotExists

Return Value

PageValue|null

clearCollectionAttributes(int[] $retainAKIDs = [])

Delete the values of the attributes associated to the currently loaded collection version.

Parameters

int[] $retainAKIDs

a list of attribute key IDs to keep (their values won't be deleted)

clearAttribute(string|CollectionKey $ak, bool $doReindexImmediately = true)

Delete the value of a specific attribute key associated to the currently loaded collection version.

Parameters

string|CollectionKey $ak

the attribute key (or its handle)

bool $doReindexImmediately

PageKey[] getSetCollectionAttributes()

Get the list of attribute keys for which the currently loaded collection version has values.

Return Value

PageKey[]

Area|null getArea(string $arHandle)

Get an existing area associated to this collection.

Parameters

string $arHandle

the handle of the area

Return Value

Area|null

bool hasAliasedContent()

Does this collection contain blocks that are aliased in other pages?

Return Value

bool

CustomStyle|null getAreaCustomStyle(Area $area, bool $force = false)

Get the custom style of an area in the currently loaded collection version.

Parameters

Area $area

the area for which you want the custom styles

bool $force

Set to true to retrieve a CustomStyle even if the area does not define any custom style

Return Value

CustomStyle|null

return NULL if the area does not have any custom style and $force is false, a CustomStyle instance otherwise

setCustomStyleSet(Area $area, StyleSet $set)

Set the custom style of an area in the currently loaded collection version.

Parameters

Area $area
StyleSet $set

resetAreaCustomStyle(Area $area)

Delete all the custom styles of an area of the currently loaded collection version.

Parameters

Area $area

string|null outputCustomStyleHeaderItems(bool $return = false)

Retrieve all custom style rules that should be inserted into the header on a page, whether they are defined in areas or blocks.

Parameters

bool $return

set to true to return the HTML that defines the styles, false to add it to the current View instance

Return Value

string|null

null|false relateVersionEdits(Collection $oc)

Associate the edits of another collection to this collection.

Parameters

Collection $oc

the collection that has been modified

Return Value

null|false

return false if the other collection is already associated to this collection, NULL otherwise

Examples

If a global area is modified inside this collection, you need to call $page->relateVersionEdits($globalArea)

int|false getPageTypeID()

Returns the ID of the page/collection type.

Return Value

int|false

refreshCache()

Empty the collection-related cache.

Block[] getGlobalBlocks()

Get the blocks contained in all the global areas in this collection.

Return Value

Block[]

array getGlobalBlockIDs()

Get the IDs for blocks contained in all the global areas in this collection.

Return Value

array

Return a list of arrays, each one is a dictionary like ['bID' => , 'arHandle' => ]

protected Stack[] getGlobalStacksForCollection()

Get all the global stacks loaded in this collection.

Return Value

Stack[]

Block[] getBlocks(string|false $arHandle = false)

List the blocks in the currently loaded collection version (or in a specific area within it).

Parameters

string|false $arHandle

The handle if the area (or falsy to get all the blocks in the collection)

Return Value

Block[]

array getBlockIDs(string|false $arHandle = false)

List the block IDs and the associated area handles in the currently loaded collection version (or in a specific area within it).

Parameters

string|false $arHandle

The handle if the area (or falsy to get all the blocks in the collection version)

Return Value

array

Return a list of arrays, each one is a dictionary like ['bID' => , 'arHandle' => ]

Block addBlock(BlockType $bt, string|Area $a, array $data)

Add a new block to a specific area of the currently loaded collection version.

Parameters

BlockType $bt

the type of block to be added

string|Area $a

the area instance (or its handle) to which the block should be added to

array $data

The data of the block. This data depends on the specific block type. Common values are: 'uID' to specify the ID of the author (if not specified: we'll use the current user), 'bName' to specify the block name.

Return Value

Block

int getCollectionAreaDisplayOrder(string $arHandle, bool $ignoreVersions = false)

Get the next value of the display order (to be used when adding new blocks to an area).

Parameters

string $arHandle

The handle of the area

bool $ignoreVersions

Set to true to ignore the collection version

Return Value

int

rescanDisplayOrder(string $arHandle)

Fix the display order properties for all the blocks within the collection/area.

Parameters

string $arHandle

the handle of the area to be processed

void rescanDisplayOrderFromBlock(Block $block, string $arHandle, int $fromDisplay = null)

Fix the display order properties for all the blocks after this block in this area.

This is useful for forcing a certain block order.

Parameters

Block $block

the block to begin the display order rescan from

string $arHandle

the handle of the area to be processed

int $fromDisplay

an optional integer to override the starting number, i.e start from 0 even though our block is 8

Return Value

void

Exceptions

Exception
BindingResolutionException

markModified()

Update the last edit date/time.

delete()

Delete this collection, and all its versions, contents and attributes.

Collection duplicateCollection()

Create a clone of this collection, and all its versions, contents and attributes.

Return Value

Collection

Page cloneVersion(string|null $versionComments, bool $createEmpty = false)

Clone the currently loaded version and returns a Page instance containing the new version.

Parameters

string|null $versionComments

the comments to be associated to the new Version

bool $createEmpty

set to true to create a Version without any blocks/area styles, false to clone them too

Return Value

Page

PageValue|null getAttributeValue(string|CollectionKey $ak) deprecated

deprecated Use of getAttributeValueObject()

No description

Parameters

string|CollectionKey $ak

Return Value

PageValue|null

mixed|null getCollectionAttributeValue(string|CollectionKey $akHandle) deprecated

deprecated use the getAttribute() method

No description

Parameters

string|CollectionKey $akHandle

Return Value

mixed|null

getCollectionTypeID() deprecated

deprecated use the getPageTypeID() method

No description