OpenCms 9.5 introduces nested containers, which provide developers a range of powerful new template options. Nested containers can for example be used to create a tab element with a defined list of tab headings but flexible tab contents that can be added by drag & drop. It’s even possible to use nested containers to generate a grid structure for template models starting with a “blank sheet of paper”. In this session, Andreas explains how nested containers can be defined in a formatter. He demonstrates how to generate different container configurations based on the formatter settings. Moreover, he shows how elements placed in nested containers can interact with the container to adjust their output according to the requirements of the page layout.

1. Andreas Zahner, Alkacon Software
Workshop Track Nested containers in action
03.11.2014

2. ●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

3. ●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?

4. ●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
What are nested containers?

5. ●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
What are nested containers?

6. ●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

7. ●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

8. ●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

9. ●Live Demo
9
Live Demo
Demo
Demo
Demo
Demo
デモ

10. ●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

11. ●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
Configuration – Container tag

12. ●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
Configuration – Container tag

13. ●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
Configuration – Container tag
[…]
<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>
[…]

14. ●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

15. ●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

16. ●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
Configuration – Element views

17. ●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
Configuration – Element views

18. ●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

19. ●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>
[…]

20. ●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

21. ●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>
[…]

22. ●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. 23
Example - Dynamic containers
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

24. ●Main template JSP with one container
24
Example - Dynamic containers
[…]
<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>

25. ●Tab formatter JSP that generates nested containers
25
Example - Dynamic containers
[…]
<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>
[…]

26. ●Live Demo
26
Live Demo
Demo
Demo
Demo
Demo
デモ

27. ●Any Questions?
27
Any Questions?
Fragen?
Questions ?
Questiones?
¿Preguntas?
質問

28. Andreas Zahner
Alkacon Software GmbH
http://www.alkacon.com
http://www.opencms.org
Thank you very much for your attention!
28