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.
singlearea can contain one component
listcan contain many components
noComponentcannot 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 theor per page template in the template definition.
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.
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
Rendering the area in the page script
To render the
main area in the page script:
- Edit the page script.
- Add the
cms.areatag in the body element.
- Provide the name of the area that should be rendered in the
nameparameter. In this case the area is
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.
- On your computer, browse to
/<CATALINA_HOME>/webapps/<contextPath>/templates, typically this is
- Create a new folder
areas, create a new text file
mainArea.ftland paste the following script in it.
The script includes two new tags:
listis 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.componentrenders content. The
contentparameter 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