Add a block type #

A block type has three parts: a definition in explayouts.ini, a handler class that declares its parameters, and a template per design. The example is a Notice block: a short text in a highlighted box, in two view types, info and warning. It reuses an existing handler, so no PHP is written.

Contents #

1. The definition
2. The handler
3. The template
4. Activate, clear, find it in the palette
5. Use it
6. Your own handler

1. The definition #

extension/mysite/settings/explayouts.ini.append.php:

<?php /* #?ini charset="utf-8"?

[BlockSettings]
AvailableBlocks[]=notice

# A new block type: a highlighted notice with a text an editor types
[BlockDefinition_notice]
Name=Notice
Handler=expLayoutsTextBlockHandler
ViewTypes[]=info
ViewTypes[]=warning
Category=basic

*/ ?>

Where the line counts. Since explayouts 1.4.42, explayouts' own explayouts.ini.append.php no longer starts AvailableBlocks[] (nor AvailableQueries[], SiteAccessMatch[] and AllowedTemplateRoots[]) with a reset line. Your extension's AvailableBlocks[]=notice is kept wherever the extension is listed in ActiveExtensions[]: for blocks the position no longer matters, and a block listed twice is offered once (./console exp:ini where explayouts.ini/BlockSettings/AvailableBlocks admin shows the list in effect). To replace the whole list, write the reset line where it is read after every extension: settings/override/explayouts.ini.append.php or a siteaccess (./console exp:ini clear explayouts.ini/BlockSettings/AvailableBlocks[] <scope>). The extension order still matters for template overrides and DesignExtensions[] (Your own design extension).

2. The handler #

expLayoutsTextBlockHandler declares one parameter:

'content' => array( 'name' => 'Content', 'type' => 'textarea', 'default' => '' ),

The editor builds the block's form from the handler's getParameters(); the field appears on the Design tab.

3. The template #

The media design includes explayouts/block/<definition>.tpl for every block, so the template is extension/mysite/design/media/templates/explayouts/block/notice.tpl:

{if and( is_set( $block.parameters.content ), $block.parameters.content|ne( '' ) )}
<aside class="notice notice-{$block.view_type|wash}" role="note">
    <p>{$block.parameters.content|wash|nl2br}</p>
</aside>
{/if}

The design's block.tpl wraps it in <div class="ngl-block ngl-notice ngl-vt-<view type> ..."> and applies the common options (spacing, CSS class, container).

4. Activate, clear, find it in the palette #

./console exp:cache clear --tag=template,content,ini

Open a layout in the editor and the palette's Basic group has Notice:

5. Use it #

Drag Notice into a zone. It arrives with the view type default; select it, open Design, choose warning, type the text into Content, and Publish layout.

The published page renders:

<div class="ngl-block ngl-notice ngl-vt-warning whitespace-top-none whitespace-bottom-none">
  <div class="container">
    <aside class="notice notice-warning" role="note"><p>Prices of the training plans change on 1 November.</p></aside>
  </div>
</div>

It is plain until the design styles .notice (Styling your blocks).

Your own handler #

For other fields, write a class that implements expLayoutsBlockHandlerInterface with getParameters() (the fields: name, type, default) and getValues( $block ) (what the template gets in $block.values), put it in extension/mysite/classes/, run php bin/php/ezpgenerateautoloads.php -e, and name it in Handler=. The handlers of extension/explayouts/classes/ (for example explayoutstextblockhandler.php, explayoutstplblockhandler.php) are short examples.

Related pages #

• Add a view type
• How a block maps to its templates
• Your own template blocks
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.