Blocks follow a loose implementation of a MVC. From within controller.php, a number of methods may be used to pass data to the various templates described within _Directory Setup_ (link to previous page.)

Properties

The following variables should be defined by your block's controller class.

$btTable

This is the core block type table that you are saving data into. Many blocks will only require this table.

$btInterfaceWidth

$btInterfaceHeight

These variables define, in pixels, the width and height of your block's window when added or edited.

Optional Properties

$btIncludeAll

If you wish your block to exist on all versions of a page (i.e. - outside of concrete5 version control) you may set this variable to 1.

Methods

$controller->add()

This function is automatically run when the block is placed in add mode. That makes it useful when paired with $controller->set() or $controller->addHeaderItem()

$controller->on_start()

Fires automatically when a block is interacted with. If you're thinking of putting something in the block's __construct() method, use on_start() instead. It is run only when necessary and is less likely to be a performance drain.

$controller->on_page_view()

This function is automatically run when the block is viewed from within a page. That makes it useful when with $controller->addHeaderItem(). This is the only way to inject items into the page's header from within a block.

$controller->view()

This function is automatically run when the block is viewed. That makes it useful when with $controller->set().

$controller->edit()

This function is automatically run when the block is edited. That makes it useful when paired with $controller->set() or $controller->addHeaderItem().

$controller->save($args)

$args is an associated array, and is usually filled with the contents of the $_POST array (when either added or saved.) The BlockController save() method will actually rarely need to be overridden, as it inspects the columns of the block's core database table and looks through the $_POST to find matching columns, and saves data automatically.

$controller->set($key, $value)

Takes a string $key and a mixed $value, and makes a variable of that name available from within a block's view, add or edit template. This is typically used within the add(), edit() or view() function.

$controller->render($view)

Renders a view that's in the block's folder. Does not require .php on the end of the filename.

public function view() { 		$this->render("view_special"); 	} 

$bp = $controller->getPermissionsObject()

Returns the permissions object for this controller's block.

$controller->duplicate($newBlockID)

Run automatically when a block is duplicated. This most likely happens when a block that is in an approved version is updated. A block controller may override this function to provide specific duplicate-only functionality.

$controller->delete()

Automatically run when a block is deleted. This removes the special data from the block's specific database table. If a block needs to do more than this this method should be overridden.

$controller->addHeaderItem($file)

Takes a path to a CSS or JavaScript file and automatically includes it when a page is run. Will work with block's in add and edit mode as well.

$controller->getBlockTypeName()

Returns the name of the block's type.

$controller->getInterfaceWidth()

Returns the width that the block thinks it needs to be, when adding or editing.

$controller->getInterfaceHeight()

Returns the height that the block thinks it needs to be, when adding or editing.

$controller->getBlockTypeDescription()

Returns the description of the block type.