[DOCU-323] Provide documentation for @area freemarker directive Created: 19/Sep/12  Updated: 03/Nov/15

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: Joerg von Frantzius Assignee: Ruth Stocks
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File page-level-properties.png    

 Description   

One of the largest changes in Magnolia 4.5 is the concept of areas being brought down to the level of configuration, and the accompanying "@area" freemarker directive.

After thorough googling and searching in your documentation, I could not find any information on the "@area" directive, only one article about blossom.

Please provide documentation about the "@area" freemarker directive, it's missing badly...



 Comments   
Comment by Joerg von Frantzius [ 20/Sep/12 ]

So far the only way of finding information about it is to look into the STK FTL templates. One example to be found there is:

[@cms.area name="logo" content=content/]

As for the semantics of this, the only information available is in the sourcecode of info.magnolia.templating.freemarker.AreaDirective. In particular, it is very hard to understand what the "content" attribute's meaning is.

Comment by Antti Hietala [ 26/Sep/12 ]

The content attribute tells a script which content node it should operate on. Scripts typically operate on the "current" content node. For a page-level script the current node is the page, for an area-level script the current node is the area, and for a component-level script the current node is the component. However, there are cases where you want the script to operate on a different content. This is where the content attribute comes handy.

For example, the intro area has no content of its own. It doesn't contain any components either since it is of type noComponent. Instead, the area operates on the page content. It edits and renders the page title and abstract. We achieve this using the content attribute.

In the main.ftl script we tell the main area "hey main area, you should operate on the current content node, which is the page because I am a page-level script".

/templating-kit/pages/main.ftl
<div id="wrapper-3">
    [@cms.area name="platform"/]
    [@cms.area name="main" content=content/]
    [@cms.area name="extras"/]
</div>

In the mainArea area script we again pass the same instruction down to the intro area: "hey intro area, you should operate on the current content node which is (still) the page".

/templating-kit/pages/section/mainArea.ftl
<div id="main" role="main">
    [@cms.area name="breadcrumb" content=content/]
    [@cms.area name="intro" content=content/]
    [@cms.area name="opener"/]
    [@cms.area name="content"/]
</div><!-- end main -->

Now the intro area edits page content. While the intro area resides inside the main area div on the page, the title and the abstract really belong to the page. They are the page's properties, not the area's. So it makes sense to store those properties under the page node in the content structure.

We will include this in our areas documentation. A basic area property reference is available in http://documentation.magnolia-cms.com/reference/areas.html

Comment by Joerg von Frantzius [ 21/Nov/12 ]

Hi Antti,

thanks for the explanation here in the ticket. Did you per chance include this in the official documentation somewhere?

Also, talking about [http://documentation.magnolia-cms.com/reference/areas.html|the basic area property reference], is there any difference between omitting "availableComponents" node in an area definition and giving it the type "noComponent"?

Or, the other way round, what happens when you both give it the type "noComponent" and list some "availableComponents"?

Comment by Antti Hietala [ 30/Nov/12 ]

Hi Jörg,

I did a quick test. Doesn't look like there is any difference. Setting type=noComponent has the same effect as omitting the availableComponents node:

  • If the area has no components and you do either of the above, the system does not render the area bar.
  • If the area already has a component and you do either of the above, the system does not render the area but it renders the component and the component is editable.

Information about the content attribute was added here. http://documentation.magnolia-cms.com/templates/stk/template-scripts.html#Directives

Generated at Mon Feb 12 01:08:02 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.