[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: |
|
| 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:
Information about the content attribute was added here. http://documentation.magnolia-cms.com/templates/stk/template-scripts.html#Directives |