Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

Pages are organized into smaller elements called areas. Areas are controllable blocks, rendered as div elements in the generated HTML. Areas make it possible to have exact control over the page layout and over what content can be placed inside the area.

There are three types of areas. The type defines how many components editors can add inside the area.

  • single area can contain one component
  • list can contain many components
  • noComponent cannot contain any editor-added components. The system creates the components automatically.

You can name your areas as you wish but some conventions exist. The main area is typically where primary content resides. For example, on a news page the actual news story would be in the main area. Other page components such as headers, footers, and navigation would reside in their own areas.

Creating an area definition

Areas can be defined globally for the whole site in the site definition or per page template in the template definition.

Node name

Value

 modules

 

 templating

 

 templates

 

 pages

 

 helloWorld

 

 areas

 

 main

 

 templateScript

/templates/areas/mainArea.ftl

 type

list

Properties:

  • main: Name of the area
    • type: Set value to list. This will create a list type area where you can add many components.
    • templateScript: Set value to /templates/areas/mainArea.ftl. This is a path to the area script. You will write it in a moment.

Making components available in the area

Each area can define what components are available inside it. You do this by creating a list of components that editors can add into the area. Availability is an important control mechanism. It allows you to control page consistency at a very low level. When you control what components editors can add and where, you ensure that information architecture on the page does not get out of hand.

The system creates the component selector dialog automatically. When an editor selects one component that component's own dialog is displayed.

In this example we make a text block component available in the main area. The component will be configured in a moment.

Node name

Value

 modules

 

 templating

 

 templates

 

 pages

 

 helloWorld

 

 areas

 

 main

 

 availableComponents

 

 textBlock

 

 id

templating:components/textBlock

 templateScript

/templates/areas/mainArea.ftl

 type

list

The id property works the same way the dialog property you saw above. It locates the component definition. The first part before the colon (:) is the name of the module folder where the component definition resides. The second part is a relative path.

<module name>:<relative path to component>

In this case the component will be defined in the Templating module so the first part is templating. The relative path starts with a components folder, followed by a path to the component content node. Since the textBlock component definition will be right under the components folder, the path is components/textBlock.

templating:components/textBlock

Rendering the area in the page script

To render the main area in the page script:

  1. Edit the page script.
  2. Add the cms.area tag in the body element.
  3. Provide the name of the area that should be rendered in the name parameter. In this case the area is main.

Freemarker:

<html>
   <head>
      [@cms.init /]
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
      <title>${content.title!}</title>
   </head>
   <body>
      <h1>${content.title!}</h1>
      <p>${content.text!}</p>
      [@cms.area name="main" /]
   </body>
</html>

JSP:

<%@ taglib prefix="cms" uri="http://magnolia-cms.com/taglib/templating-components/cms" %>
<html>
    <head>
        <cms:init/>
        <title>${content.title}!</title>
    </head>
    <body>
        <h1>${content.title}</h1>
        <p>${content.text}</p>
        <cms:area name="main" />
    </body>
</html>

This instructs the script to render the main area. There is nothing to render yet so we need an area script.

Creating an area script

Like pages, areas have their own scripts. The primary purpose of an area script is to render any components inside the area.

  1. On your computer, browse to /<CATALINA_HOME>/webapps/<contextPath>/templates, typically this is /apache-tomcat/webapps/magnoliaAuthor/templates.
  2. Create a new folder areas.
  3. In areas, create a new text file mainArea.ftl and paste the following script in it.

Freemarker:

<div id="main">
[#list components as component ]
   [@cms.component content=component /]
[/#list]
</div>

JSP:

<%@ taglib prefix="cms" uri="http://magnolia-cms.com/taglib/templating-components/cms" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<div id="main">
    <c:forEach items="${components}" var="component">
        <cms:component content="${component}" />
    </c:forEach>
</div>

The script includes two new tags:

  • list is a Freemarker directive that evaluates a collection. In this case it is a collection of components inside the area. Any operations defined within the list are executed for each collection item.
  • cms.component renders content. The content parameter determines what that content is, in this case a component inside the area.

If you just want to render components inside the area, you don't need an area script! An area definition alone is adequate. However, if you want to render any custom HTML like the div element in this example, then write an area script.

Save the area script and refresh the Hello page. The page now has a main area. The area toolbar shows the name of the area. Areas also have an end marker, a narrower green bar at the bottom. It helps you see the dimensions of the area. In the middle is a gray placeholder for components. You cannot add the text block component into the area yet because we have not defined it yet. Let's do that next.

Next: Creating a component