This is the documentation for concrete5 version 5.6 and earlier. View Current Documentation

Loading an Existing Block Object

When you want to interact with a block object, it will likely be in one of several typical situations. Here is how you'd go about getting that block object or array of objects, given your context.

You want to grab all blocks in an area on any page

$page->getBlocks($areaName);

Grabs all the generic block objects that live within the given area on that page.

$page = Page::getCurrentPage(); 	$blocks = $page->getBlocks('Main');

You're working in a theme's template, and you want to grab all the blocks from within a specific area. Editable areas within themes are declared in the following way:

	$a = new Area('Main'); 	$a->display($c);

You can grab all the blocks from this area within the page template by modifying this code as followS:

	$a = new Area('Main'); 	$blocks = $a->getAreaBlocksArray($c);

In both of these examples, the $blocks array is an array of generic block objects.

Simply grab a block by its ID.

$b = Block::getByID($bID);

Returns all information about a block object based solely on its ID.

Grab a block by ID, while in its area/page context

Since blocks can live on multiple pages, it's frequently important to specify which page and area you want to retrieve a block from. This will populate additional fields in the generic block object:

$b = Block::getByID($bID, $page, $areaHandle);

Grab a block by name

Block objects may be named, and can be retrieved by this name.

$b = Block::getByName($blockName);

In All of these cases, the item returned is either a block object, or an array of block objects. These are *generic* block objects, meaning they hold information that is common to all blocks, regardless of type.

The Generic Block Object

The generic block object is an object that stores data common to all concrete5 blocks, regardless of type. Examples of this data include

  • The block's name
  • The block's type
  • When this block was created
  • A custom template (if available)

and more. When dealing with blocks, most methods return the generic block object, which is an object of the Block class.

Basic Data

$block->getBlockID()

Returns the ID of the block.

$block->getBlockTypeID()

Returns the ID of the block's type.

$block->getBlockTypeName()

Returns the name of the block type for the current block.

$block->getBlockTypeHandle()

Returns the handle of the block type for the current block.

$blockType = $block->getBlockTypeObject()

Returns a BlockType object for the block's type.

$block->getBlockFilename()

If the block has a custom template, returns that filename value.

$block->getAreaHandle()

Gets the current area handle for the block.

$block->getBlockUserID()

Returns the user ID of the user who created the block.

$block->getBlockDateAdded()

Returns the date the block was created.

$block->getBlockDateLastModified()

Returns the date the block was last updated.

$block->isAlias($page = null)

Queries the block to see whether it is an alias or an original. If a page object is not provided, the current page is retrieved from the block's context and used.

$block->isGlobal()

Returns true if the block exists within a global scrapbook.

$block->getOriginalCollection()

Returns the original page object where this block exists as an original.

$block->getBlockCollectionObject()

If the current block object specifies a page, returns that Page object. If not, returns the result of $block->getOriginalCollection().

$block->getNumChildren()

Returns the total number of times a block is aliased to this current block object (assuming this block is an original.)

$block->getInstance() and $block->getController()

Returns the instance-specific block object for this block (more on this in the next section.)

$pages = $block->getCollectionList()

Gets a list of pages that include this block.

Style Data

$block->getBlockCustomStyleRule()

Returns a CustomStyleRule object from a block, if one exists.

$block->resetBlockCustomStyle()

Resets the block's custom design.

$block->setBlockCustomStyle($customStyleRule)

Takes a CustomStyle object. Updates a block to point to a custom style by ID.

Updating core properties of the Block object

$block->update($data)

Takes an array of key/value pairs. Updates the block object with the current timestamp, and then passes this array through to the save() function of the block instance.

$block->setName($name)

Updates a block's name.

$block->setCustomTemplate($template)

Updates a block's custom template.

$block->alias($page)

Aliases a block to a new page.

$block->move($newPage, $area)

Moves a block to a new page, in the specific area.

$block->duplicate($newPage)

Duplicates a block to a new page.

$block->delete()

Deletes a block. If the block is an original, all data about the block will be deleted. If not, just that particular page/version/area instance will be removed.

$block->refreshCache()

Deletes the cache of the current block object.

Working with Block Assets

$block->inc($filename)

Includes a file found in the block's directory.

$block->getBlockPath()

Returns a path to where the block type's files are located.

Rendering a Block Object

$block->display($view = 'view', $args = array())

Renders a view for a particular block. Passes arguments to the included template through an optional associative array.

Instance-Specific Data

The previous section details all the methods available to the generic block object, which is what most of the methods dealing with blocks return. However, when dealing with most blocks, what you're actually interested in is that block's presentational data, which is stored in the instance-specific fields. For example, while an image block, a content block, and page list block all have a name, a last updated date, and a block type ID, the data that makes them unique is of far greater importance.

Getting the Block's Controller

These fields are contained within the block's instance of a BlockController object. This object can be returned by running this method:

$controller = $block->getInstance()

The $controller object will be different depending on the type of block being accessed. A content $block will return an object of the ContentBlockController type. A slideshow block will return an object of the SlideshowBlockController type, and so on.

These objects are always available from within the blocks/block_name/controller.php file for the particular block. You can learn more about which methods are available from the controller by checking out the MVC Approach page.

Loading Conversation