Message-ID: <1366907110.2534.1485845359229.JavaMail.confluence@ip-10-127-227-164> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_2533_804384104.1485845359229" ------=_Part_2533_804384104.1485845359229 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html The LandingPage Field Type

The LandingPage Field Type

=20
=20
=20
=20
=20

This page describes features available only in eZ Studio.

=20
=20
=20
=20
=20
=20
=20
Overview
=20

Landing Page Field Type defines the layout= structure of the Landing Page

=20
Name Internal name Expected input
Landing page ezlandingpage string (JSON)

 

With the Landing Page Field Type you can define a = layout with multiple zones within a sing= le Landing Page.

Within each zone, editors can create blocks, the basic= segments of a Landing Page, that contain particular content categories. Sp= ecific Content items, called block items, can be added = to these blocks.

The configuration of layout and blocks is stored in the default_layouts.yml file. For more information about = configuration, refer to the EzLandingPageFieldTypeBundle Configuration cha= pter.

This organization of the layout structure is particularly useful for man= aging homepages.

 

=20
=20
=20
=20
In this topic
 =20
=20 =20
=20
=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

Layout

=20
=20
=20
=20
=20
=20

Layout is the way in which a Landing Page is divided = into zones.

=20
=20
=20
=20
=20
=20

  • By default, Studio Demo Bundle provides several preset layouts.

    <= p style=3D"text-align: center;">3D"Layout Select a = Layout window with different layouts to choose

 

 

A Landing Page can have = one of two general layout types:

    • Static page is a type of Landing Page with a very b= asic content structure. It offers very flexible editing of content and layo= ut at the same time, which is useful for example in simple marketing campai= gns.

      The Static Landing Page is beyond the scope of the firs= t stable release (eZ Enterprise 2016.)

    • Dynamic page is a type of Landing Page with an advance= d content structure. It introduces the possibility to manipulate the struct= ure of pages. The dynamic structure is based on zones and easily deployable= blocks.

 

  • You can use any type of layout from the Studio Demo bundle or you can c= reate a new one from scratch. You can de= fine as many layouts as you need.
=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

Zones

=20
=20
=20
=20
=20
=20

As mentioned above, a layout is composed of zones.  Zones are organized structures that are deployed o= ver a layout in a particular position .

The placement of zones is defined in a template which is a part of the l= ayout configuration. You can modify the template, hard-coded in HTML, in or= der to define your own system of zones.

 

=20
=20
=20
=20
=20
=20

Zone structure

=20
=20
=20
=20
=20
=20

Each zone contains the following parameters:

Name Description
<zone_id> Required. A unique zone ID
<name> Required. Zone name
=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

<= span class=3D"confluence-anchor-link" id=3D"TheLandingPageFieldType-Definin= gazonelayout">Defining a zone layout

=20
=20
=20
=20
=20
=20

You can define a new layout file (e.g. in Twig) for a zone and include i= t in a Landing page layout.

A Zone is a container for blocks. The best way to display blocks in the = zone is to iterate over a blocks array and render the blocks in a loop.

 For eZ Studio, the data-studio-zone attribute is required to allow dropping the Content into specific zones.<= /p>

=20
=20
=20
=20
=20
=20

Example of a zone layout:

zone.html.twig
=20 
<div data-studio-zone=3D"{{ zones[0].id }}">=09=09=09=09=09=
=09=09=09=09=09
=09{# If a zone with [0] index contains any blocks #}
=09{% if zones[0].blocks %}=09=09=09=09=09=09=09=09=09=09=09=09=09
    =09{# for each block #}
=09=09{% for block in zone[0].blocks %}=09=09=09=09=09=09=09=09=09=09=09=09
    =09=09{# create a new layer with appropriate id #}
=09=09=09<div class=3D"landing-page__block block_{{ block.type }}">=
=09=09=09
       =09=09=09{# render the block by using the "ez_block:renderBlockActio=
n" controller #}
=09=09=09=09{{ render_esi(controller('ez_block:renderBlockAction', {=09=09
           =09=09=09=09{# id of the current content #}
=09=09=09=09=09=09'contentId': contentInfo.id,=09=09=09=09=09=09=09
        =09=09=09=09{# id of the current block #}
=09=09=09=09=09=09'blockId': block.id=09=09=09=09=09=09=09=09=09=09
       =09=09=09=09}))=20
=09=09=09=09}}
    =09=09</div>=09=09
=09=09{% endfor %}=09
=09{% endif %}
</div>
=20
=20
=20
=20
=20
=20
=20

Blocks

=20
=20
=20
=20
=20
=20

Blocks are the basic segment of a Landing Page= and integral parts of a zone. Each zone can contain a number of blocks.

Blocks can be placed on a Landing Page using drag-and-drop and later cus= tomized.

=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

Creating a new block

=20
=20
=20
=20
=20
=20

Creating a cla= ss for the block

=20
=20
=20
=20
=20
=20

The class for the block must implement the BlockType interface:

=20 
 EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\B=
lockType
=20
=20
=20
=20
=20
=20
=20

Most methods are implemented in a universal way by using the AbstractBlockType abstract class:

=20 
 EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\A=
bstractBlockType
=20
=20
=20
=20
=20
=20
=20

If your block does not have specific attributes or a structure, you can = extend the AbstractBlockType class, which contains simple generic converters designated for the bloc= k attributes.

Example:

=20 
<?php
namespace AcmeDemoBundle\Block;

use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\Abstra=
ctBlockType;

/**
* RSS block
* Renders feed from a given URL.
*/
class RSSBlock extends AbstractBlockType
{
   // Class body
}
=20


=20
=20
=20
=20
=20
=20

Describing a = class definition

A block must have a definition set using two classes:

=20
=20
=20
=20
=20
=20

The BlockAttributeDefinition <= /code> class defines the attributes of a block:

Attribute Type Definition
$id string block attribute ID
$name string block attribute name
$type string block attribute type, available options are:
  • integer
  • string
  • url
  • text
  • embed
  • select
  • multiple
$regex string block attribute regex used for validation
$regexErrorMessage string message displayed when regex does not match
$required bool TRUE if attribute is required<= /td>
$inline bool indicates whether block attribute input sho= uld be rendered inline in a form
$values array array of chosen values
$options array array of available options


=20
=20
=20
=20

The BlockDefinition class describes a bl= ock:

Attribute Type Definition Note

$type

 string block type  
$name string block name  
$category string block category  
$thumbnail string path to block thumbnail image  
$templates array array of available paths of templates

Retrieved from the config file = (default_layouts.yml)
$attributes array array of block attributes (objects of  BlockAttributeDefinition  class)  


=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

When extending AbstractBlockType you must implement at least 3 methods:

createBlockDefinition()

This method must return an  EzSystems\LandingPageFiel= dTypeBundle\FieldType\LandingPage\Definition\BlockDefinition  object.

Example of a Gallery block:

=20 
/**
 * Creates BlockDefinition object for block type.
 *
 * @return \EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Defi=
nition\BlockDefinition
 */
public function createBlockDefinition()
{
    return new BlockDefinition(
        'gallery',
        'Gallery Block',
        'default',
        'bundles/ezsystemslandingpagefieldtype/images/thumbnails/gallery.sv=
g',
        [],=20
        [
            new BlockAttributeDefinition(
                'contentId',
                'Folder',
                'embed',
                '/^([a-zA-Z]:)?(\/[a-zA-Z0-9_\/-]+)+\/?/',
                'Choose an image folder'
            ),
        ]
    );
}
=20
getTemplateParameters(BlockValue $block= Value)

This method returns an array of parameters to be displayed in rendered v= iew of block. You can access them directly in a block template (e. g.= via twig {{ title }} ).

 

When parameters are used in the template you call them directly without = the parameters array name:

Correct Not Correct
&= lt;h1>{{ title }}</h1> = <h1>{{ parameters.title }}</h1>

 

Example of the getTemplateParameters() method implementatio= n:

=20 
/**
* @param \EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\=
BlockValue $blockValue
*
* @return array
*/
public function getTemplateParameters(BlockValue $blockValue)
{
=09$attributes =3D $blockValue->getAttributes();
=09$limit =3D (isset($attributes['limit'])) ? $attributes['limit'] : 10;
=09$offset =3D (isset($attributes['offset'])) ? $attributes['offset'] : 0;
=09$parameters =3D [
=09=09'title' =3D> $attributes['title'],
=09=09'limit' =3D> $limit,
=09=09'offset' =3D> $offset,
=09=09'feeds' =3D> $this->RssProvider->getFeeds($attributes['url']=
),
=09];
=09
=09return $parameters;
}
=20

 

checkAttributesStructure(array $attribu= tes)

This method validates the input fields for a block. You can specify your= own conditions to throw the InvalidBlockAttributeException ex= ception.

This InvalidBlockAttributeException exception has the follo= wing parameters:

Name Description
<= strong>blockType na= me of a block
<= span class=3D"pl-s1"> attribute <= span class=3D"pl-s1"> name of the block's attribute = which failed validation
<= span class=3D"pl-s1"> message = <= span class=3D"pl-s1"> a short information about an error =
<= span class=3D"pl-s1"> pr= evious <= span class=3D"pl-s1"> previous ex= ception, null by default

 

Example:

=20 
/**
 * Checks if block's attributes are valid.
 *
 * @param array $attributes
 *
 * @throws \EzSystems\LandingPageFieldTypeBundle\Exception\InvalidBlockAttr=
ibuteException
 */
public function checkAttributesStructure(array $attributes)
{
    if (!isset($attributes['url'])) {
        throw new InvalidBlockAttributeException('RSS', 'url', 'URL must be=
 set.');
    }

    if (isset($attributes['limit']) && (($attributes['limit'] < =
1) || (!is_numeric($attributes['limit'])))) {
        throw new InvalidBlockAttributeException('RSS', 'limit', 'Limit mus=
t be a number greater than 0.');
    }

    if (isset($attributes['offset']) && (($attributes['offset'] <=
; 0) || (!is_numeric($attributes['limit'])))) {
        throw new InvalidBlockAttributeException('RSS', 'offset', 'Offset m=
ust be a number no less than 0.');
    }
}
=20

When the class is created make sure it is added to a container.

=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

Adding the = class to the container

=20
=20
=20
=20
=20
=20

 The services.yml file must contain info about you= r block class.

The description of your class must contain a tag which provides:

  • tag name: landing_page_field_type.block_type
  • tag alias: <name of a block>

 

An example:

=20 
acme.landing_page.block.rss: =09=09=09=09=09=09=09=09=09=09=09# ser=
vice id
       class: AcmeDemoBundle\FieldType\LandingPage\Model\Block\RSSBlock # b=
lock's class with namespace
       tags: =09=09=09=09=09=09=09=09=09=09=09=09=09=09=09# service definit=
ion must contain tag with=20
           - { name: landing_page_field_type.block_type, alias: rss}=09# "l=
anding_page_field_type.block_type" name and block name as an alias
=20
=20
=20
=20
=20
=20
=20

 

=20
=20
=20
=20
=20
=20

Rendering Landing Page

=20
=20
=20
=20
=20
=20

Landing page rendering takes place while editing or vi= ewing.

When rendering a Landing Page, its zones are passed to the layout as a <= code>zones array with a blocks array each. You can simp= ly access them using twig (e.g. {{ zones[0].id }}= ).

Each div that's a zone or zone's container should have data attributes:<= /p>

  • data-studio-zones-container for a div c= ontaining zones
  • data-studio-zone with zone ID as a valu= e for a zone container

 

To render a block inside the layout, use twig render= _esi() function to call ez_block:rend= erBlockAction . 

ez_block is an alias to EzSystems\LandingPageFieldTypeBundle\Control= ler\BlockController

 

An action has the following parameters:

  • contentId - ID of content which can be = accessed by contentInfo.id
  • blockId - ID of block which you want to= render

 

Example usage:

=20 
{{ render_esi(controller('ez_block:renderBlockAction', {
=09=09'contentId': contentInfo.id,
    =09'blockId': block.id
=09})) 
}}
=20

 

As a whole a sample layout could look as follows:

landing_page_simple_layout.html.twig
=20 
{# a layer of the required "data-studio-zones-container" attribute,=
 in which zones will be displayed #}
<div data-studio-zones-container>
=09 {# a layer of the required attribute for the displayed zone #}
=09 <div data-studio-zone=3D"{{ zones[0].id }}">=09=09=09=09=09=
=09=09=09=09=09
=09=09{# If a zone with [0] index contains any blocks #}
=09=09{% if zones[0].blocks %}=09=09=09=09=09=09=09=09=09=09=09=09=09
    =09=09{# for each block #}
=09=09=09{% for block in blocks %}=09=09=09=09=09=09=09=09=09=09=09=09
    =09=09=09{# create a new layer with appropriate id #}
=09=09=09=09<div class=3D"landing-page__block block_{{ block.type }}">=
;=09=09=09
        =09=09=09{# render the block by using the "ez_block:renderBlockActi=
on" controller #}
=09=09=09=09=09{{ render_esi(controller('ez_block:renderBlockAction', {=09=
=09
            =09=09=09=09{# id of the current content #}
=09=09=09=09=09=09=09'contentId': contentInfo.id,=09=09=09=09=09=09=09
            =09=09=09=09{# id of the current block #}
=09=09=09=09=09=09=09'blockId': block.id=09=09=09=09=09=09=09=09=09=09
        =09=09=09=09})) 
=09=09=09=09=09}}
    =09=09=09</div>
=09=09=09{% endfor %}
=09=09{% endif %}
    </div>
</div>
=20

 

 

=20
=20
=20
=20
=20
=20

Viewing template

=20
=20
=20
=20
=20
=20

Your view is populated with data (parameters) retrieved from the getTemplateParameters() method which must be imple= mented in your block's class.

Example:

=20 
/**
    * @param \EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Mo=
del\BlockValue $blockValue
    *
    * @return array
    */
   public function getTemplateParameters(BlockValue $blockValue)
   {
       $attributes =3D $blockValue->getAttributes();
       $limit =3D (isset($attributes['limit'])) ? $attributes['limit'] : 10=
;
       $offset =3D (isset($attributes['offset'])) ? $attributes['offset'] :=
 0;
       $parameters =3D [
           'title' =3D> $attributes['title'],
           'limit' =3D> $limit,
           'offset' =3D> $offset,
           'feeds' =3D> $this->RssProvider->getFeeds($attributes['=
url']),
       ];
       return $parameters;
   }
=20
=20
=20
=20
=20
=20
=20

Implementation Exa= mple

=20
=20
=20
=20
=20
=20

Block Class

TagBlock.php
=20 
<?php
/**
 * @copyright Copyright (C) eZ Systems AS. All rights reserved.
 * @license For full copyright and license information view LICENSE file di=
stributed with this source code.
 */
namespace EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\=
Block;

use EzSystems\LandingPageFieldTypeBundle\Exception\InvalidBlockAttributeExc=
eption;
use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Definition\B=
lockDefinition;
use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Definition\B=
lockAttributeDefinition;
use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\Abstra=
ctBlockType;
use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\BlockT=
ype;
use EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\BlockV=
alue;

/**
 * Tag block
 * Renders simple HTML.
 */
class TagBlock extends AbstractBlockType implements BlockType
{
    /**
     * Returns array of parameters required to render block template.
     *
     * @param array $blockValue Block value attributes
     *
     * @return array Template parameters
     */
    public function getTemplateParameters(BlockValue $blockValue)
    {
        return ['block' =3D> $blockValue];
    }

=09/**
 =09 * Creates BlockDefinition object for block type.
 =09 *
 =09 * @return \EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\=
Definition\BlockDefinition
 =09 */
    public function createBlockDefinition()
    {
        return new BlockDefinition(
            'tag',
            'Tag Block',
            'default',
            'bundles/ezsystemslandingpagefieldtype/images/thumbnails/tag.sv=
g',
            [],
            [
                new BlockAttributeDefinition(
                    'content',
                    'Content',
                    'text',
                    '/[^\\s]/',
                    'Provide html code'
                ),
            ]
        );
    }

=09/**
 =09 * Checks if block's attributes are valid.
=09 *
=09 * @param array $attributes
=09 *
=09 * @throws \EzSystems\LandingPageFieldTypeBundle\Exception\InvalidBlockA=
ttributeException
=09 */
    public function checkAttributesStructure(array $attributes)
    {
        if (!isset($attributes['content'])) {
            throw new InvalidBlockAttributeException('Tag', 'content', 'Con=
tent must be set.');
        }
    }
}
=20

service.yml con= figuration

services.yml
=20 
ezpublish.landing_page.block.tag:
    class: EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model=
\Block\TagBlock
    tags:
        - { name: landing_page_field_type.block_type, alias: tag }
=20

Block template

tag.html.twig
=20 
{{ block.attributes.content|raw }}
=20
=20
=20
=20
------=_Part_2533_804384104.1485845359229 Content-Type: image/png Content-Transfer-Encoding: base64 Content-Location: file:///C:/af918576c0365dadd34b26056af46801 iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAAA3NCSVQICAjb4U/gAAAAFVBMVEX/ //9wcHBwcHBwcHBwcHBwcHBwcHA3RenHAAAAB3RSTlMAZoiZzN3/SzZomQAAAAlwSFlzAAALEgAA CxIB0t1+/AAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTNui8sowAAAAUdEVYdENy ZWF0aW9uIFRpbWUANi8xLzEzOKlF0AAAACFJREFUCJljYCATsCgwqIAZTMnMyRAhsTABCIMxkVxT GQCLcwHyUKXpLgAAAABJRU5ErkJggg== ------=_Part_2533_804384104.1485845359229--