opencms days 2014 - nested containers in action

Andreas Zahner, Alkacon Software

Workshop Track

Nested containers in

action

03.11.2014

● Introduction ● What are nested containers?

● Possible use cases ● Flexible template models

● Tab / Accordion element

● Configuration ● The <cms:container> tag

● Formatter configuration

● Element views

● Limitation

● JSP access ● Access parent element information

● Example usage for flexible templates ● Dynamic container creation

2

Agenda

● Short definition: Nested containers are

containers that are placed inside other

containers

● They can be created by formatter JSPs or

included JSP elements

● Advantage: by using nested containers, more

flexible pages and contents can be created

3

What are nested containers?

● Nested containers are not part of the content itself

● If you place the content that renders the nested container a second time on the same or a different page, the elements in the nested container will not be inserted. For each element instance of the content that renders the nested container, the container is completely independent.

● Nested containers are tight to a container page element

● If you move a content that renders a nested container on a page (and the formatter does not change), the element in the nested container will move with it. If you remove the content, or change its formatter, the nested container will vanish and its elements are not visible anymore.

4


● Nested containers are similar to normal containers managed by the container page

● When a content that creates a nested container is added to a page, the container will be stored similar to a top-level container in the container page

● The only additional information is the element ID of the container's parent element

● When an element that created a nested container is removed from a page, also the information about the nested container is removed from the container page

5


● Template frameworks using a grid layout like

Bootstrap are often used to create responsive

websites

● In the common approach the layout of the grid

columns is defined by the template developer and

fixed in the template JSP

● It is not possible to have a more flexible structure

without changing and enhancing the template JSP

●

6

Use cases – Flex. template models

● Nested containers can be used to create

different grid column variations

● This allows editors the creation of more

complex layouts by using e.g. pre-defined rows

● These rows dynamically create containers

where the contents can be dragged into by

editors

7

Use cases – Flex. template models

● Usually, the possible contents of a single tab

are defined in the XSD of the content type

● Instead of this approach, for each single tab of

a tab / accordion, nested containers can be

used

● This allows the flexible usage of various

already present different content types like

texts, images, icon boxes, etc.

8

Use cases – Tab / Accordion

● Live Demo

9

Live Demo

Demo

Demo Demo

Demo

デモ

● New attributes for the <cms:container> tag

● editableby: a comma separated list of OpenCms

principals that are allowed to edit the container

content.

If empty it defaults to ROLE.ELEMENT_AUTHOR

● param: passes a parameter as string that can be

read by elements inside the container

10

Configuration – Container tag

● Other attributes for the <cms:container> tag

● name: a unique name for the container

● type: a type for the container, it can be used to

select the formatter that is used to render a

content in this container

● maxElements: the number of elements that can

be placed inside, the default is 100

● width: the width of the container

● tag: defines the tag that the <cms:container> tag

is translated to. The default tag is <div>

11


● Other attributes for the <cms:container> tag

● tagClass: a space separated list of CSS class

names that are inserted as value of the "class“

attribute in the tag

● detailview: defines if on a detail page the detail

content should be shown in this container

● detailonly: defines if the container is visible only

on detail pages

12


● A container that has no content elements inside

can show a default output in the page editor. To

enable this feature, place any kind of HTML

code in the body of the <cms:container> tag

13


[…]

<cms:container name="..." type="..." editableby="..." param="...">

<div class="servive-block rounded-3x servive-block-dark-blue">

<h2 class="heading-md">Empty container</h2>

<p>Drag content elements here.</p>

</div>

</cms:container>

[…]

● If a formatter creates nested containers,

OpenCms needs this information to render the

page correctly.

● Therefore, in the formatter configuration of the

content creating nested containers, the option

„Nested Containers“ has to be checked

14

Configuration – Formatter

● Depending on the use case, nested containers

might overlap their parent containers

● Because of this, it can be difficult to place

contents in nested container structures

● Solution: the usage of different element views,

where only specific content types can be

dragged in containers

15

Configuration – Element views

● How to create and use an element view:

● Create a new file of type „Element view“ in the

Explorer view in the menu „Other options“

● Edit the file to configure the appearance

● Edit the resource type configurations in the

module or subsitemap configuration to assign

specific types to the view

16


● Setting the visibility of the element view is

possible by using permissions on the element

view file

● Only users with at least the role „Editor“ can

switch to that view

17


● Currently, OpenCms supports a nested

container structure of maximum 5 levels

● This limit is fixed and cannot be increased at

the moment

18

Configuration – Limitation

● Using the EL, it is possible to get information

about the container where the element is

placed into

19

JSP access – Container info

<%@page buffer="none" session="false" trimDirectiveWhitespaces="true" %>

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

[…]

<ul>

<li>Name: ${cms.container.name}</li>

<li>Type: ${cms.container.type}</li>

<li>Maximum elements: ${cms.container.maxElements}</li>

<li>Nested container: ${cms.container.nestedContainer}</li>

</ul>

[…]

● With „${cms.element.parent}“, the element info

of type CmsContainerElementWrapper can be

obtained

● If the method returns null, no parent element

exists

● The wrapper provides access to the type info,

the resource and the eventual settings

20

JSP access – Parent element info

● EL usage for parent element info

21

JSP access – Parent element info

<%@page buffer="none" session="false" trimDirectiveWhitespaces="true" %>

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

[…]

<c:if test="${cms.element.parent != null}">

<dl>

<dt>Type ID</dt>

<dd>${cms.element.parent.resource.typeId}</dd>

<dt>Path</dt>

<dd>${cms.element.parent.sitePath}</dd>

<dt>Setting example</dt>

<dd>marginbottom: ${cms.element.parent.setting.marginbottom.value}</dd>

<dt>Parent present</dt>

<dd>${not empty cms.element.parent.parent}</dd>

</dl>

</c:if>

[…]

● The new OpenCms 9.5 demo uses nested

containers

● The basic template models can be created and

edited only by users with the „Developer“ role

● The template JSP has only one container

● Template rows can be dragged in this „page“

container

● Users with „Editor“ role can drag pre-configured

layout rows in the template row containers

which are editable by them

22

Example - Dynamic containers

23


Page container

Template row head with one container

Template row foot with one container

Template row content with one container

Layout row 1 with 2 containers

Content Content

Layout row 1 with 3 containers

Content Content Content

● Main template JSP with one container

24


[…]

<head>

[…]

<cms:enable-ade/>

<cms:headincludes type="css" closetags="false" />

<cms:headincludes type="javascript" />

</head><body>

[…]

<cms:container name="page-complete" type="page" width="1200" maxElements="15" editableby="ROLE.DEVELOPER" />

[…]

</body>

</html>

● Tab formatter JSP that generates nested

containers

25


[…]

<cms:formatter var="content" val="value" rdfa="rdfa">

[…]

<div class="tab-content">

<c:forEach var="label" items="${content.valueList.Label}" varStatus="status">

[…]

<cms:container name="tab-container${status.count}" type="layoutrowsonly" tagClass="tab-pane ${status.first? 'active':''}" maxElements="2">

<div class="alert alert-warning fade in">

<h4><fmt:message key="bootstrap.tabs.emptycontainer.headline"/></h4>

<p><fmt:message key="bootstrap.tabs.emptycontainer.text"/></p>

</div>

</cms:container>

</c:forEach>

</div>

[…]

</cms:formatter>

[…]

● Live Demo

26

Live Demo

Demo

Demo Demo

Demo

デモ

● Any Questions?

27

Any Questions?

Fragen? Questions ?

Questiones?

¿Preguntas? 質問

Andreas Zahner

Alkacon Software GmbH

http://www.alkacon.com

http://www.opencms.org

Thank you very much for your

attention! 28