View layer¶
All entities in Netgen Layouts (layouts, blocks, mapping rules, forms) are rendered through the same API called the view layer. View layer revolves around three concepts:
- View
- Match configuration
- View context
View¶
All entities in Netgen Layouts specify their own view, which defines what
variables will be available in the Twig templates when the entity is rendered.
For example, layout view (identified by layout_view
identifier), specifies
that all layout templates will have a variable called layout
, which will
hold the currently rendered template, while item view (identified by
item_view
identifier), specifies that all block item templates will have two
variables: item
, which holds the currently rendered block item, and
view_type
, which will hold the item view type with which the item is
rendered.
There are a handful predefined views available in Netgen Layouts, but most interesting ones are ofcourse views for rendering layouts, blocks and block items. The other ones are used by administration interface of Netgen Layouts (list of mappings, layouts and shared layouts) and are rarely needed, e.g. when developing custom mapping targets and conditions.
Match configuration¶
Match configuration is a single rule which specifies which template will be rendered for a specific view when all configured conditions are met. Those conditions are called matches, and services which perform the matching process are called matchers.
View context¶
View context is a set of match configuration rules and each view context is used in different parts of Netgen Layouts. View contexts are what makes it possible for example to use different templates for frontend and backend for your layout types and blocks. Match configurations in a view context are processed sequentially and template from first configuration that matches the rules will be used to render the value.
Netgen Layouts uses five view contexts to render its’ templates: default
for
rendering the frontend templates, ajax
for rendering collection pages
rendered view AJAX, app
for rendering the layout editing app templates and
admin
and value
view contexts for rendering the administration
interface.
Configuring the view layer¶
The following configuration shows an example on how to configure layout_view
and block_view
views, specifying some match rules in two different view
contexts (default
and app
).
netgen_layouts:
view:
# The identifier of the view
layout_view:
# The name of the view context
default:
# The identifier of a match configuration (unused, but needs to specified in YAML)
# The first match configuration for which all conditions match will be picked up and used to render the view
layout_1:
# The template that will be used when conditions specified below match
template: "@App/layout/layout_1.html.twig"
# The list of custom parameters that will be injected in the template if the conditions specified below match
parameters:
param1: value1
param2: value2
# The list of conditions that will need to match for this rule to be used
match:
layout\type: layout_1
layout_2:
template: "@App/app/layout/layout_2.html.twig"
match:
layout\type: layout_2
block_view:
app:
title:
template: "@App/block/title.html.twig"
match:
block\definition: title
text:
template: "@App/app/block/text.html.twig"
match:
block\definition: text
# This configuration is used to specify a fallback template for
# a view/context combination. It is used when none of match rules
# were able to select the template. It is implemented as a separate
# configuration in order not to depend on bundle order and priority of
# configuration when merging Symfony semantic config.
default_view_templates:
# The identifier of the view
block_view:
# Key is the name of the view context, and the value is a
# default template
my_context: '@App/block/block.html.twig'
Tip
If you use Ibexa CMS, view configuration is siteaccess aware. This means you can have different templates for different siteaccesses or siteaccess groups for the same block views or layout types.
For example, you can use the following config to use two different templates
for my_layout
layout type for eng
and cro
siteaccesses:
netgen_layouts:
system:
eng:
view:
layout_view:
default:
my_layout:
template: "@App/layouts/my_layout_eng.html.twig"
match:
layout\type: my_layout
cro:
view:
layout_view:
default:
my_layout:
template: "@App/layouts/my_layout_cro.html.twig"
match:
layout\type: my_layout
Tip
For parameters that you inject into your templates, you can use expression
language to build dynamic parameters. Expression language currently has one
variable available named view
which holds the view object which is being
displayed. To use the expression language, prefix the parameter value with
@=
:
block\my_block:
template: '@App/my_template.html.twig'
match:
block\definition: my_block
parameters:
custom_param: '@=view.parameter("custom_param")'
Custom view contexts¶
If, for some reason, you would want to render some layouts or blocks by hand in your PHP code, you can create custom view contexts (and custom templates, ofcourse) on the fly and use them directly when rendering the layouts or blocks, without touching and compromising the existing frontend templates.
So for example, to render a block view with your custom view context called
my_context
, you would define a configuration similar to this:
netgen_layouts:
view:
block_view:
my_context:
title:
template: "@App/block/my_context/title.html.twig"
match:
block\definition: title
and then somewhere in your controller:
// $this->blockService is an instance of Netgen\Layouts\API\Service\BlockService
$block = $this->blockService->loadBlock(
\Ramsey\Uuid\Uuid::fromString('38052fd1-78c1-4e08-8eb3-b4615f0be37d'),
);
// $this->viewBuilder is an instance of Netgen\Layouts\View\ViewBuilderInterface
return $this->viewBuilder->buildView($block, 'my_context');
Note
You don’t need to return Symfony Response
object from your controllers,
instead, you can just return the built view object. Netgen Layouts will
render it on the fly with a built in event listener.
List of built in views¶
The following lists all built in views with their identifiers, supported interfaces and the list of variables available in the rendered template.
List of built in matchers¶
The following lists all built in view matchers. As a rule of thumb, all matchers accept either a scalar or an array of scalars as their value. If an array is provided, the matcher will match if any of the values in the provided array is matched.
Note
While you can use all matchers in all views, most of the combinations do not
make sense and will simply not match. For example, using layout\type
matcher in block_view
view will never match since block_view
renders
a block, while layout\type
matches on layout type of a rendered layout.
block\definition
block\view_type
block\locale
block\collection\identifier
layout\type
layout\shared
zone\identifier
zone\layout_type
item\value_type
item\view_type
parameter\type
rule_condition\type
rule_condition\is_group_condition
rule_target\type
form\type
form\block\definition
form\block\locale
form\query\type
form\query\locale
form\config\config_key
form\config\value_type
policy_limitation\type