Diving into sap.uxap: the Object Page Layout

Deep within the SAPUI5 and OpenUI5 toolkits lies a rather interesting library. Sat in a dimly lit corner, overshadowed by the all-singing, all-dancing sap.m, you notice it peering at you; beckoning you to explore… Late one Sunday you strike up the courage and prepare to embark on your journey. You take the first step. You open up the library and exclaim:”What on earth is an Object Page Layout!?”

Mystery aside, the sap.uxap library has been around for some time (SAPUI5 & OpenUI5 version 1.26). It provides (among other things) some unique solutions to the problem of displaying “objects” across any device.

My first steps have led me to the sap.uxap.ObjectPageLayout control. The heart of this library, it provides a framework for building an application to display information around an object in a clean, rather effective way. I will touch upon this framework later.

An object could be anything from a material, to an organisation to an employee, and this library provides an easy way to break up an object into different facets, and display them in a delightful manner.

This gave me an idea:

“What if I treat myself as an object, displaying my experience in an application utilising this cool stuff?”

A UI5 CV - an Object Page Layout walkthrough

The idea I went with to explore this library was to create a simple CV where I could provide information around myself and my experience. The ‘what’, however, is not the focus of this post, but rather the ‘how’. That being said it is worth saying that the example application was built with a use-case in mind, and doesn’t use all of the facets of the sap.uxap library, just those I felt were appropriate as I tinkered.

Here is an example of the Object Page Layout (Disclaimer: handsome thumbnail not included as standard):

Figure 1: UI5 CV version 1.0 !

Before I dissect the example, it’s worth exploring the underlying structure of the Object Page Layout.

Object Page Layout Structure

The Object Page Layout control is broken up into three main sections:

1) Header - The top-most section, split into title & content
2) Sections - The main content
3) Footer - A single bar at the very bottom

Let’s walk through the basic structure of these controls, and examine how my example application uses some (but not all) of the facets.

The Header

The header of an Object Page Layout control looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<ObjectPageLayout>
<headerTitle>
<ObjectPageHeader>
<breadCrumbsLinks>
<!-- Any amount of sap.m.Link controls -->
</breadCrumbsLinks>
<navigationBar>
<!-- A single sap.m.Bar control -->
</navigationBar>
<actions>
<!-- Either: -->
<!-- 1) Any amount of sap.ui.core.Control controls -->
<!-- 2) Any amount of sap.uxap.ObjectPageHeaderAction Button controls -->
</actions>
<sideContentButton>
<!-- A single sap.m.Button control -->
</sideContentButton>
</ObjectPageHeader>
</headerTitle>
<headerContent>
<!-- Either: -->
<!-- 1) Any amount of sap.ui.core.Control controls -->
<!-- 2) Any amount of sap.uxap.ObjectPageHeaderContent controls -->
</headerContent>
<!-- sections & footer -->
</ObjectPageLayout>

Figure 2: Example of an Object Page Layout Header

In the CV application example, the Header has been used to hold information similar to that which might reside on a business card. I have also configured the header to remain fixed at the top of the screen as the user scrolls, so this information is always visible.
Furthermore, I have configured a set of Action Buttons which, when pressed, will link to various locations including social media sites and sites of interest.
This is, in my humble opinion, the main use of the Header in this application - to store key “at-a-glance” information, supported by whatever actions are relevant to the object that is on display.

The Sections

The sections part of an Object Page Layout looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<sections>
<!-- Any amount of sap.uxap.ObjectPageSection controls -->
<ObjectPageSection>
<!-- Any amount of sap.uxap.ObjectPageSubSection controls -->
<ObjectPageSubSection>
<blocks>
<!-- Either: -->
<!-- 1) Any amount of sap.ui.core.Control controls -->
<!-- 2) Any amount of implemented sap.uxap.BlockBase controls -->
</blocks>
<moreBlocks>
<!-- Either: -->
<!-- 1) Any amount of sap.ui.core.Control controls -->
<!-- 2) Any amount of implemented sap.uxap.BlockBase controls -->
</moreBlocks>
<actions>
<!-- Any amount of sap.ui.core.Control controls -->
</actions>
</ObjectPageSubSection>
<ObjectPageSubSection>
<!-- ... -->
</ObjectPageSubSection>
</ObjectPageSection>
<ObjectPageSection>
<!-- ... -->
</ObjectPageSection>
</sections>
</ObjectPageLayout>
Figure 3: Example of an Object Page Layout Section

The Object Page Section is extremely robust and flexible. The ability to have multiple sub-sections, each able to have multiple blocks, allows for all kinds of content from different libraries across UI5.

As mentioned in the code sample above there are two ways to add content to a sub-section. The first is to just add the controls directly into an Object Page Sub Section.

The other uses something known as Blocks. In the above sample, the two aggregations are labelled “blocks” and “moreBlocks”. The former of these is the main aggregation for adding content, whereas “moreBlocks” contains content which is initially hidden, and is displayed on demand, via an automatically generated “See More” button. Version 1.0 of my CV application currently does not utilise this, but the UI5 Explored App has an example of this expand behaviour.

One of the benefits of using Blocks is that you can use XML Views to determine the content by extending the BlockBase control.

Extending the Block Base

By extending the sap.uxap.BlockBase control, one can create new Block controls which can be made specific for your sub-sections, or kept general and reusable.
Blocks use Views to contain content, which is, in my opinion, a much nicer way of including content, as it keeps your main View code much simpler.
They also allow you to define different XML Views for different behaviour. One example of this is the ability to define two separate Views, one for when the block is in Expanded mode, and one when it is in Collapsed mode. This is extremely useful when a block might have lots of content in it, and you don’t want to overwhelm the user.
Another reason to use Blocks is to utilise the built-in column layouts that the sap.uxap.ObjectPageSubSection control provides when it needs to display more than one block at a time. Code and a visualisation of some of these layout options can be found on the UI5 explored app.

The Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
sap.ui.define(['sap/uxap/BlockBase'], function (BlockBase) {
"use strict";
var QualificationBlock = BlockBase.extend("ui5.cv.blocks.QualificationBlock", {
metadata: {
views: {
Collapsed: {
viewName: "ui5.cv.view.Qualification",
type: "XML"
},
Expanded: {
viewName: "ui5.cv.view.Qualification",
type: "XML"
}
}
}
});
return QualificationBlock;
});

This is an example of a custom Block I have used in my example application. As you can see in the constructor, we define two Views in the metadata section - Collapsed & Expanded. In my example these are the same View, however this need not be the case.

This is how my custom block slots into my Section:

1
2
3
4
5
6
7
8
9
10
<ObjectPageSection title="Qualifications" titleUppercase="false">
<ObjectPageSubSection title="Qualifications">
<blocks>
<!--the 'blocks:' label below refers to the blocks directory in my application -->
<blocks:QualificationBlock id="QualificationBlock"/>
</blocks>
</ObjectPageSubSection>
</ObjectPageSection>

While this method generates more files and folders, I found it a much cleaner way of organising my content than directly putting my controls in the blocks aggregation of a sub-section.

Flexibility

One of the best parts about the controls within sap.uxap is that they are built in such a way as to work across any screen size - similarly to controls in sap.m, but with less layout code required.

Here is what the example application looks like when displayed using Google Chrome’s developer tools’ mobile preview:

Figure 5: Example displayed on a mobile device

Let’s breakdown how the example Application behaves when being displayed on a mobile device.

Header on a mobile device
Figure 5: Example of an Object Page Layout Header when displayed on a mobile device

The figure shows how the header title has squashed to fit the content, and placed a single overflow button to denote where the action buttons now live. Furthermore, the content of the header has reacted so that each element fits the smaller screen size.

Action Buttons on a mobile device
Figure 6: Example of Object Page Layout Header action buttons when displayed on a mobile device

When you click on the overflow button (...), this menu appears, which now shows the Button’s text and icons in a nice, mobile menu.

Sections on a mobile device
Figure 7a: Example of Object Page Layout Section on a mobile device pt.1 (Horizontal orientation) Figure 7b: Example of Object Page Layout Section on a mobile device pt.2 (Horizontal orientation)

In mobile mode the three lists in this section are automatically adjusted by default to use the available space as effectively as possible. This also adapts depending on Orientation

The End

Thus endeth the whirlwind account of my exploration into this control. It was ultimately a fun experience for me, and one I may consider building upon - be it by growing my example application further, or by exploring another area of UI5 I have always gazed at from afar, yet to discover the magic within!