oro/layout

Oro Layout Component

Oro Layout Component

Oro Layout component defines the object-oriented presentation of a page structure and provides tools to build, manage, and render the page., _(*1)

IMPORTANT: This component is not finished yet., _(*2)

Oro Layout Component provides tools for:, _(*3)

• defining the elements of the layout (blocks) that can be used to build different types of layouts, including HTML, XML, etc.
• managing the layout structure and themes.

Introduction

Before you begin working with layout, make sure you are familiar with the following key Oro Layout Component concepts:, _(*4)

• A layout is a set of widgets that are arranged in a hierarchical structure, where a widget is a logical block that contains certain content., _(*5)

• Neither the layout nor a widget know how they should be converted (or in other words, rendered) into the output string (e.g. HTML). To make this conversion, we use renderers, for example a renderer based on TWIG templates., _(*6)

• The root idea and implementation of Oro layouts are mostly similar to the Symfony's Forms component. However, the difference is that layouts support only one-way data flow. It means that content of layout widgets can be rendered based on data, but layouts cannot be used to process user-submitted data., _(*7)

• There are two core layout widgets, the block and the container:, _(*8)

  • The block represents a widget which cannot contain any other widgets. Examples of blocks can be a label, a chart, a grid, etc., _(*9)

  • The container is a structural widget which can contain other widgets. Examples of containers can be a header, a side bar, a page body, etc., _(*10)

High-Level Architecture

, _(*11)

The Oro Layout component includes three main layers:, _(*12)

• The Foundation layer provides the main architectural components used to build a layout.
• The Extensions layer extends the layout with more useful features, such as loading widgets from the DI container and working with layout inheritance.
• The View layer provides components responsible for translating a layout into rendering HTML, XML, or any other format.

The Oro Layout component provides several pluggable extensions out of the box:, _(*13)

• The Core extension provides all widget definitions (called block types) implemented by the component.
• The DI extension adds support for the Symfony's Dependency Injection component.
• The Themes extensions allows to build layouts based on other layouts and provide flexible configuration of layouts.

Layout Life Cycle

The layout usually goes through the stages outlined in the following table., _(*14)

The following example illustrates how a simple layout can be build., _(*15)

$context = new LayoutContext();
$context->getResolver()
    ->setRequired(['some_variable']);
$context->set('some_variable', 'some_value');

$layoutFactory = Layouts::createLayoutFactory();
$layout = $layoutFactory->createLayoutBuilder()
    ->add('root', null, 'root')
    ->add('header', 'root', 'header')
    ->add('logo', 'header', 'logo', ['title' => 'Hello World!'])
    ->getLayout($context);

echo $layout->render();

Also you can render only layout subtree instead of full tree. For this you should set rootId argument in LayoutBuilder::getLayout., _(*16)

$layout = $layoutFactory->createLayoutBuilder()
    ...
    ->getLayout($context, 'some_block_id');
echo $layout->render();

To improve your understanding of how the layout works, study the Layouts class, the getLayout method of the LayoutBuilder class and the BlockFactory class. pay close attention to the postExecuteAction method of theDeferredLayoutManipulator class and the LayoutRegistry class., _(*17)

Developer Reference

The following is the list of the most important classes of the Oro Layout component:, _(*18)

• LayoutManager is the main entry point to the Oro Layout component.
• Layouts is the static helper that can be used if a dependency injection container is not used in your application.
• Layout represents a layout which is ready to be rendered.
• LayoutBuilder provides a set of methods to build the layout.
• LayoutRegistry holds all layout extensions.
• RawLayout represents a storage for all layout data, including a list of items, hierarchy of items, aliases, etc. This is an internal class and usually you do not need to use it outside of the component.
• RawLayoutBuilder provides a way to build the layout data storage. This is an internal class and usually you do not need to use it outside of the component.
• DeferredLayoutManipulator allows to construct a layout without worrying about the order of method calls.
• BlockTypeInterface provides an interface for all block types.
• AbstractType can be used as the base class for all block block types.
• AbstractContainerType can be used as the base class for all container block types.
• BlockFactory implements the logic for building layout blocks and their views.
• DataProviderDecorator allows to calls methods with pre-defined prefix.
• ThemeExtension loads layout updates.
• ImportVisitor loads imports.