This site has been archived and you can no longer log in or post new messages. For up-to-date community resources please visit ezplatform.com

eZ Community » Blogs » Core Development team » Extending eZ Studio with new blocks

By

Extending eZ Studio with new blocks

Thursday 21 July 2016 2:41:59 pm

  • Currently 4 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Learn how to create a new Landing Page block in eZ Studio.

The eZ Studio's Landing Page feature lets you compose powerful, dynamic pages from easily customizable blocks. You can find more about Landing Pages in our documentation: https://doc.ez.no/display/USER/Creating+content+-+Landing+Page.

While a number of useful, universal blocks are provided out-of-the-box, sometimes you might need a new Landing Page block that has not been implemented yet. If it is a block specific for your project, you have to build a definition for it with PHP.

In this tutorial I explain how to do just that. I assume here you have your own bundle that extends eZ Studio. If not, please generate a new one with the following command: 'php app/console generate:bundle' (the command should run from the eZ Platform root folder).
If you need more information about bundles please check the documentation page about bundles: https://doc.ez.no/display/DEVELOPER/Bundles.

All the changes described below that are required to create a new block will be done inside your bundle folder.

Block definition

Without specifying the block definition, eZ Studio won't be able to handle dynamic block configuration that will come after saving information in the block config form. The block definition requires at least two methods to be implemented: 'getTemplateParameters' and 'createBlockDefinition'.
The first method is responsible for passing data from the block definition (which acts like a view) to a template.
The second method creates the block definition. There you will define your block structure.
If you want block validation, you will need to implement a third method called 'checkAttributesStructure', where you can validate the required block fields.

The explanation above might look a bit enigmatic without seeing the code, so let's take a look at an example:

The code above should be placed in the following location: 'Block/CustomBlock.php'.

A new Custom block on the block list

A new Custom block on the block list

As you probably noticed, defining a new block's structure is pretty straightforward. You create a new 'BlockDefinition' instance containing some 'BlockAttributeDefinition' instances. There are many types of block attributes:

  • integer
  • string
  • url
  • text
  • embed
  • select
  • multiple

If you create a block attribute with types: 'integer', 'string', 'url', the user will see an input field on the frontend side. In case of defining a block attribute definition with 'embed' type, the user will see a button leading to settings (widget).

'Embed' block with Settings button

'Embed' block with Settings button

When the button is clicked, the Universal Discovery Widget will appear and there the user can choose a Content item that should be added to the block as its content.

Universal Discovery Widget

Universal Discovery Widget

The 'text' block attribute will provide a textarea field where users will be able to input more text. When choosing either a 'select' type or a 'multiple' type, the user will see a select/dropdown field and will be able to choose one of predefined values. See the code example above to see how to define select field options.

Another parameter worth looking at is the 'extra views' param. This allows you to hardcode a template in the PHP code instead of providing a template config. However, please keep in mind that this is not the recommended way and we advise you to use the presented template configuration.

Block template

The Block template is needed to display block content on a webpage. It is a template for content selected from the eZ Studio block configuration popup. This makes the block template a mandatory requirement in order to show content on your site.

Block configuration popup with content style options

Block configuration popup with content style options

For simplicity's sake, we'll define a simple layout with a static header containing a block name and a dynamic content that will come from the block's configuration popup fields.
The sample template might look like this:

Rendered block

Rendered block

The template code will be stored in the 'Resources/views/' folder in a file named 'custom.html.twig'.

Block extension

A block definition and a block template are not enough to have the eZ Studio app already extended. You have to do two more things. One of them is defining a block extension class that will provide block configuration to the eZ Studio app.

The code above should be placed in the following location: 'DependencyInjection/MyBlockExtension.php'.

In the extension class you have to define at least the 'load' method. It is used to provide information about your custom block definition class. If you have block templates defined with the config, then you can attach it to the eZ Studio app by creating a 'prepend' method. It loads your block templates config (in the example above the block template config is stored in the file 'blocks.yml'). The config is prepended to the 'ez_systems_landing_page_field_type' config.

Block configuration files

The only thing left to do is to create block configuration files, one with services config and another with templates config.

Block services config

The file is located under 'Resources/config/services.yml'.

The basic config file looks like this:

Block templates config

The file is located under 'Resources/config/blocks.yml':

Each block can have multiple templates. Each template should be defined under 'views' root. In the example above, there is only one block view template defined called 'custom'.

Summary

And that's all there is to it. I hope that you will find this post useful and that it will help you build new, amazing blocks for your Landing Pages.

Using the code from this article you will be able to create Landing Page blocks that use default UI for blocks in eZ Studio. The creation of custom user interfaces by extending JS views in eZ Studio is not possible yet.

As a bonus, if you want to have base files for the Landing Page block bundle, then you might want to fork this repository from github created by one of eZ Developers: https://github.com/kamilmusial/EzLandingPageBlockTemplateBundle.

Proudly Developed with from