Object Page Blocks

The contents of the sections and subsections of the ObjectPageLayout control are organized into blocks.

Blocks are composite OpenUI5 controls that have the following purpose:

Support multiple display modes
Promote reuse
Are the means of holding section/subsection contents

Blocks are not strictly dedicated to the ObjectPageLayout, they can also be used outside of it. However, using them within this control provides additional features:

Lazy Loading: Only the blocks that are currently displayed and those in their direct proximity are instantiated
Column Layout: Blocks provide information to the subsection only on the width they should be using for an optimal experience

Blocks API & Guidelines

Blocks that are used in an ObjectPageLayout have to comply with the following rules regarding their API. They must:

Extend BlockBase.js
Declare their expected data model
Support the Modes described in sap.uxap.ObjectPageSubSectionMode.type: Collapsed and Expanded
Implement a different rendering for each of the layout modes
Come with their own controller (if needed). This controller should just react to the internal events of the block. The ObjectPageLayout controller manages only the page, the sections and subsections.
Follow OpenUI5 naming guidelines: see Related Information

Blocks should be implemented with views (one view, or one view per mode). We recommend using the XML view if no templating is needed. Furthermore, Block views should use one distinct model per expected logical entity. As a second step, you could consider using a tool to automatically parse the view and detect the models used (and their properties) and generate documentation.

You should always use relative binding{MyEntity>MyProperty}. This will also make reuse easier as the Blocks can then be used with any kind of OpenUI5 model (ODataModel, JSONModel, XMLModel, UxAPModel).

Example

Let’s consider an Employee Goals block which displays an employee together with his or her goals. In one backend service, goals may be a navigation property of employees, but in another this may not be the case. For this reason, when implementing the Employee Goals block, you should use 2 distinct models in the block views.

One Employee model for the employee entity:

<Text text="{Employee>FirstName}"></Text>

One Goals model for the goal collections:

<List items="{Goals>}">

Model Mapping

BlockBase implements a mechanism to allow model mapping: mapping a block model (corresponding to an expected logical entity) to an inherited model and a path/context in this model. The syntax for this is as follows:

<mappings>
    <uxap:ModelMapping externalModelName="â€¦" externalPath="/Employee" internalModelName="Contact" />
</mappings>

BlockBase interprets this in the following order:

Look for a model with name ModelName (in the propagated models)
Set this model on itself with MyBlockEntity name
Create a context corresponding to the path

Note

This model mapping is not mandatory; models used in a view can also be provided by standard OpenUI5 techniques (model inheritance, setModel.).

Example

An application wants to use the Employee Goals blocks described above. These are therefore embedded into a Page that has a model named ApplicationModel in which Goals are a navigation property of employees:

<EmployeeGoals>
    <mappings>
        <uxap:ModelMapping externalModelName="ApplicationModel" externalPath="/Employee('121')" internalModelName="Employee" />
        <uxap:ModelMapping externalModelName="ApplicationModel" externalPath="/Employee('121')/Goals" internalModelName="Goals" />
    </mappings>
</EmployeeGoals>

A second application uses the same blocks, but in its service, Goals and Employees are unrelated entities:

<EmployeeGoals>
    <mappings>
        <uxap:ModelMapping externalModelName="ApplicationModel2" externalPath="/Employee('121')" internalModelName="Employee" />
        <uxap:ModelMapping externalModelName="ApplicationModel2" externalPath="/Goals" internalModelName="Goals" />
    </mappings>
</EmployeeGoals>

Standard Block Implementation

The standard block implementation is to just extend the BlockBase control of the sap.uxap library and inherit the default implementation of setMode and rendering. setMode in BlockBase supports two different ways of building blocks:

Restriction

The BlockBase control supports XML views only.

Single view blocks: Here, a single XML view is used for all layout modes. This XML view should be named .view.xml.

Multiple view blocks: Here, different views are provided for the different layout modes.

These views should be added in the views section of the Block metadata (this section is added by the BlockBase class)

For each mode, the BlockBase class must declare a view name and type:

sap.uxap.BlockBase.extend("<BlockName>", {
        metadata: {
            views: {
                Collapsed: {
                    viewName: "<collapsedViewName>",
                    type: "XML"
                },
                Expanded: {
                    viewName: "<expendedViewName>",
                    type: "XML"
                }
            }
         }
     });