Studio is a great tool for creating and managing Landing Pages. One of its most powerful features is a possibility to create custom Landing Page blocks with custom functionalities. In a previous tutorial about extending Studio with custom landing page blocks we have managed to create a new Landing Page block whose configuration is derived from PHP files, but the block configuration UI uses the default JS view designed for Landing Page blocks.
During the Web Summercamp 2016 in Rovinj, me and my colleague Kamil Musiał prepared a workshop about extending Studio with blocks that require a custom configuration user interface. In this tutorial, I'm going to provide you all the information required to build such an interface in writing.
Assuming that you already have an existing Studio Landing Page block we can move further to start creating the block's custom configuration user interface. Doing that will require several steps:
- Creating a JS plugin to add a custom block JS view to the Studio app,
- Creating a custom block JS view that implements a custom configuration popup interface,
- Creating a custom block configuration popup JS view with custom interface implemented,
- Optionally, creating a JS plugin to manage data required for your interface, e.g. getting information from external resources or making additional requests using REST API to fetch required data based on user interaction in the configuration popup,
- Optionally, custom CSS styling,
- Finally, the JS dependencies configuration.
In this article you will see the full code example which creates a Twitter post embed block for Landing Pages. The block's config form will allow editors to load a specified user's timeline and will provide the ability of selecting a tweet from the timeline for rendering the preview.
Create a plugin to add your custom block JS view to Studio app
This plugin does one thing: it adds a new block reference to Studio app. It adds a reference to Y.my.BlockView JS class that is located under the key custom. It's very important to use exactly the same name as a block type defined in your custom block PHP definition - BlockDefinition. In our case the PHP definition is located in the file Block/CustomBlock.php.
Create your custom block JS view
The view is going to be very simple. For our needs it will not implement any custom functionalities to the block view itself. We'll focus only on applying the custom config interface later in this article. The block's JS view should be placed in Resources/public/js/blocks/my-custom-blockview.js
In the view I redefined the values of two view attributes: viewClassName and editForm. These attributes have to be set in every block view or the app will not be able to detect a correct view and implement a custom config user interface. The custom config view is defined as a value of the editForm attribute. In this case, it's the instance of Y.my.CustomBlockConfigFormView.
Create a custom block config popup view
The next thing is to create a custom config form JS view. The basic example looks like the following:
It should be placed in Resources/public/js/config-forms/my-customblock-configformview.js.
Create custom block config view template
Every JS view in Studio requires a template. The same rule applies to our custom config view. The block we are implementing requires some HTML additions that extend the block's config functionalities by adding a container for an additional content.
Create JS dependencies config in yui.yml file
These are the basics of creating the custom block configuration forms. Every time you create a block you have to define:
- Landing Page Creator view plugin that adds a block,
- custom block view,
- custom block config view,
- custom block config template,
- JS dependencies config.
If you want to test a working example, please check the code from Github repository block-bundle on Github.com