Extending Studio

About Us

Kamil Musiał

PHP Symfony Developer

@kkmusial

Piotr Nalepa

Senior UI Developer

@sunpietro

We are from eZ Systems Polska | Katowice

What is eZ Platform EE?

eZ Platform EE is the extended version

of eZ Platform containing:

• The Studio,

• Flex Workflow,

• Form Builder,

• Date Based Publishing,

• Recommendation Engine.

The Studio - features

Using the Studio you can:

• Preview live website,

• Create landing pages using blocks,

• Manage landing pages,

• Schedule content display,

• Build forms.

The Studio – live website preview

The Studio – landing page management

The Studio – content scheduling

The Studio – Form Builder

eZ Platform EE – features in the Content Editor

• Flex Workflow,

• Date Based Publishing

Content Editor - Flex Workflow

Content Editor - Date Based

Publishing

Date Based Publishing – CRON config

Using ezsystems-cron bundle:

date_based_published.cron.publish_scheduled:

class: '%date_based_published.cron.publish_scheduled.class%'

tags:

- { name: console.command }

- { name: ezpublish.cron.job, schedule: '* * * * *' }

Changes publication status based on a publication date in CRON job.

eZ Platform development stack

PHP (Symfony) & JavaScript (YUI3)

So how to extend eZ Platform EE?

Adding new landing page blocks 1/2

To create new blocks you have to:

• Configure blocks definitions by implementing PHP classes,

• Or, use the YAML configuration (the newest thing!).

Create block in PHP - Twig

(ezblock.html.twig)

{{ text_field }}

Create block in PHP - BlockType class

• implements interface:

EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\M

odel\BlockType

or

• extend abstract boilerplate:

EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\M

odel\AbstractBlockType

Create block in PHP - BlockType class

Methods to implement:

• getTemplateParameters(BlockValue $blockValue): array,

• createBlockDefinition(): BlockDefinition,

• checkAttributesStructure(array $attributes)

Create block in PHP - BlockType class

getTemplateParameters(BlockValue $blockValue): array

• contains logic,

• return values for view

Create block in PHP - BlockType class

createBlockDefinition(): BlockDefinition()

Returns a definition containing block parameters and array of its attributes:

\EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\De

finition\BlockDefinition

Create block in PHP - BlockType class

BlockAttributeDefinition

Block form contains fields based on attribute type.

Available types:

• integer,

• string,

• text,

• embed,

• select (supports multiple select)

Developer can create new attribute types - look at DemoBundle

Create block in PHP - BlockType class

public function createBlockDefinition()

{

return new BlockDefinition(

'ezblock', // Block type (unique)

'eZ Block', // Name of block

'default', // Block category (currently unsupported)

'ezblock.svg', // icon for thumbnail

[], // extra views that can be hardcoded

[

new BlockAttributeDefinition(

'text_field', // Attribute's ID (unique)

'Text field', // Attribute' name

'text', // Attribute's type

'/[^\\s]/', // regex for frontend validation

'Sample content', // regex validation fail message

true, // is field required?

false, // should this attribute input be displayed inline to the

previous?

[], // default value

[] // available options (for select)

),

]

);

}

Create block in PHP - BlockType class

checkAttributesStructure(array $attributes)

• advanced attribute validation (after front end validation) - 3rd party APIs, DB calls

etc.

• throws exception for invalid attributes: \EzSystems\LandingPageFieldTypeBundle\Exception\InvalidBlockAttributeExcep

tion

Create block in YAML - Twig - no changes

(ezblock.html.twig)

{{ text_field }}

Create block in YAML - Config

Extended Simplified

blocks:

ezblock:

initialize: true

name: eZ Block

category: default

thumbnail: ezblock.svg

views:

default:

template:

ezblock.html.twig

name: Default view

attributes:

text_field:

name: Text Field

type: text

regex: /.*/

regexErrorMessage:

'error'

blocks:

ezblock:

initialize: true

thumbnail: ezblock.svg

views: ezblock.html.twig

attributes:

text_field: text

Create block in YAML

Form:

Create block in YAML

Rendered block:

Create block in YAML + PHP

initialize: false

class EzBlock extends ConfigurableBlockType

{

public function getTemplateParameters(BlockValue $blockValue)

{

$attributes = $blockValue->getAttributes();

$attributes['text_field'] .= " Additional info";

return $attributes;

}

}

ez_systems.landing_page.block.ez_block:

class:

EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\Block\EzBlock

tags:

- { name: landing_page_field_type.block_type, alias: ezblock }

arguments:

- '@ezpublish.landing_page.block_definition_factory'

Create block in YAML + PHP

Rendered block:

The JS app structure

App

Service + plugins

View + plugins

The communication between JS app layers

• From the bottom to top: addTarget() when creating a new view instance,

• Invoke the fire() method to send an event up to services,

• Using callbacks

Adding new landing page blocks 2/2

To implement custom UI for new blocks you have to (in JavaScript):

• Create a plugin that adds new blocks definitions to landing page creator/editor,

• Create custom views for each new kind of blocks,

• Create custom config popups for each new kind of blocks.

Creating a JS plugin to add new block definition

Y.my.Plugin.AddEzBlockView = Y.Base.create('addEzBlockViewPlugin',

Y.Plugin.Base, [], {

initializer: function () {

this.get('host').addBlock('ezblock', Y.my.EzBlockView);

},

}, {

NS: 'addEzBlockViewPlugin'

});

Y.eZ.PluginRegistry.registerPlugin(Y.my.Plugin.AddEzBlockView, [

'landingPageCreatorView',

'dynamicLandingPageCreatorView',

'dynamicLandingPageEditorView'

]);

Creating a landing page block JS view

Y.my.EzBlockView = Y.Base.create('myEzBlockView', Y.eZS.BlockView, [], {

}, {

ATTRS: {

viewClassName: {

value: 'my.EzBlockView',

readOnly: true

},

editForm: {

valueFn: function () {

return new Y.my.EzBlockConfigFormView({bubbleTargets:

this});

}

}

}

});

Creating a block config popup JS view

Y.my.EzBlockConfigFormView = Y.Base.create('myEzBlockConfigFormView',

Y.eZS.BlockPopupFormView, [], {

anyKindOfMagicMethod: function () {}

});

Adding new fields to Form Builder

To add new fields custom UI to Form Builder you have to (in JavaScript):

• Create a plugin that adds new fields definitions to the Form Builder,

• Create custom views for each new kind of fields,

• Create custom config form for each new kind of fields.

Creating a JS plugin to add new field definition

Y.my.Plugin.AddCustomFieldView =

Y.Base.create('addCustomFieldViewPlugin', Y.Plugin.Base, [], {

initializer: function () {

this.get('host').addFormFieldViewsMapItem('customField',

Y.my.CustomFieldView);

},

}, {

NS: 'addCustomFieldViewPlugin'

});

Y.eZ.PluginRegistry.registerPlugin(Y.my.Plugin.AddCustomFieldView,

['fbFieldsTabView']);

Creating a form builder field JS view

Y.my.CustomFormFieldView = Y.Base.create('customFormFieldView',

Y.fb.BaseFormFieldView, [], {

}, {

ATTRS: {

type: {

value: 'custom'

},

configForm: {

valueFn: function () {

return new Y.my.CustomFormFieldConfigFormView({

bubbleTargets: this,

viewModel: this.get('model')

});

}

},

}

});

Creating a form builder field config form JS view

Y.my.CustomFormFieldConfigFormView =

Y.Base.create('myCustomFormFieldConfigFormView',

Y.fb.FormFieldConfigFormView, [], {

anyKindOfMagicMethod: function () {}

});

eZ Platform EE v2

Additional resources

https://ezplatform.com/Blog/Extending-eZ-Studio-with-new-blocks

https://ezplatform.com/Blog/Learn-how-to-implement-a-custom-UI-for-Landing-Page-block-

configuration-popup

http://yuilibrary.com/yui/docs/api/

Thank you!