Handling Adding, Saving & Rendering

Handling the Adding of a Block

When a block type is dragged from the Add Panel onto a page, the following things occur:

  1. If there is no add.php template, we automatically skip to step 5 (?) below.

  2. If the block does not support inline editing, a Concrete CMS dialog is displayed, set to the dimensions specified in the block controller's $btInterfaceWidth and $btInterfaceHeight variables.

    If this block does support inline editing, the dialog is not displayed and editing begins within the page itself.

  3. The add() method in the controller is run (if it exists) allowing any necessary data to be injected into the add template. Optional. If there are default parameters that the combined template uses, they can be set from within this method.

  4. The add.php template is rendered and returned to the browser. This content is injected either directly into the page (if inline editing is supported) or otherwise into the modal dialog.

  5. When the block is saved, the Controller's validate() method is run. If a Concrete\Core\Error\Error object with errors is returned, these are displayed and the process terminates. Otherwise, the save() method is run.

  6. The completed block is rendered to the page (see Handling the Rendering of a Block below).

Handling the Editing of a Block

A block may be edited by clicking and choosing "Edit" from the menu. When this occurs, the following takes place:

  1. The Controller's edit() method is run (if it exists), allowing any necessary data to be injected into the edit template.

  2. All database columns for this block (from the block's $btTable) are queried and automatically injected for use within the template.

  3. The edit.php file is rendered and returned to the browser.

    Variables from both the database and controller are available in the local scope, so if the $btTable has a column entitled content you can simply do this in edit.php:

    <input type="text" name="content" value="<?= $content ?>">
    
  4. When the block is saved, the server runs the same processes as when adding the block for the first time (see above).

  5. The completed block is rendered to the page (see Handling the Rendering of a Block below).

Tip: Since the "add" and "edit" forms are usually extremely similar, you can avoid repetition by placing the code in edit.php and simply include this from add.php.

<?php $view->inc('edit.php') ?>

Handling the Rendering of a Block

When a block is rendered to a page (after being added/edited) the following things occur:

  1. The Controller's view() method is run (if it exists), allowing any necessary data to be injected into the view template.

  2. All database columns for this block (from the block's $btTable) are queried and automatically injected for use within the template.

  3. The view.php file (or a custom template, if selected) is rendered.

    Variables from both the database and controller are available in the local scope, so if the $btTable has a column entitled content you can simply do this in view.php:

    <div class="ccm-block-type-custom-block-field"><?= $content ?></div>