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

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

All Web pages created with Magnolia are based on templates. Templates ensure that page structure and presentation remain the same while the content varies from one page to another. The system generates pages by merging a template with corresponding content from the repository, a process known as rendering.

DiagramConcept

STK separation of concerns
Standard Templating Kit separates duties:

  • HTML structure (template) is created with Freemarker or Java Server Pages
  • Business logic is written in Java or Groovy
  • Content is stored in a JSR-283 compliant Java Content Repository
  • Design is controlled with CSS
  • Client-side functionality is done with JavaScript

Rendering engine
Rendering is the process where templates are merged with content. It generates a stream of HTML that can be displayed in a browser. The rendering filter submits a content node to the rendering engine, which kicks off the following process:

  1. The rendering engine reads the template definition assigned to the content. The template definition provides the engine with details such as a path to the template script and the templating language used (FreeMarker, JSP).
  2. Based on the templating language, the engine selects a renderer. Renderers for FreeMarker and JSP are shipped with Magnolia. You can also use your own custom renderer.
  3. The renderer is executed and a model is created. The model is a Java Bean. This is where your business logic resides. The model can execute any Java code to retrieve data from the JCR repository or from an external source.
  4. The renderer calls the assigned template script and passes the current content and model to it. Freemarker interpolations like ${content.title} are replaced with actual values and directives like #list are processed.

Template map

The following elements make up the Magnolia template mechanism:

  •  Template definition assigns the template a name and makes it available to the system. The name is used to reference the template. The template definition also tells the system which dialog is used to edit content and which script is used to render the content.
  •  Template script renders the content. The script is written in FreeMarker, JSP or a custom templating language. The script instructs the renderer where to place the content on the page and also contains placeholders for content elements such as headings and images.
  •  Dialog is an HTML form with input fields. Editors type content into the fields and the dialog saves it in the repository. Most templates have a dialog.
  •  Content node is retrieved from the repository. It may contain text and references to images that need to be rendered. The content node has a reference property that assigns it to a particular template definition. This is how the system knows which template to use when it renders a piece of content.
  •  Model is a Java object that contains template logic. We recommend that you put templating logic in the model rather than trying to do too much in a template script. A template renderer executes the model before it calls the template script. The model can retrieve data, perform a calculation or do anything the template needs.

Pages and paragraphs
Content nodes in the JCR hierarchy are rendered as headings, paragraphs and images on the finished page.

  1. An article about basketball in the New York Times Sports sections has the following page properties:
    • title rendered as an H1 element on the page, "Bulls and the Thunder Make a Stand"
    • date and author rendered on the dateline
    • abstract to provide an introductory paragraph
  2. The next element on the page is the main collection which contains paragraphs.
  3. Paragraph 0 is a text paragraph ("LeBron James scored 13...") with a matching image. The image file and its caption and credit are stored in the document management system (DMS).
  4. Paragraph 00 consist of text and an optional subtitle element "THUNDER 101, LAKERS 96".
  5. The page ends with a footer singleton paragraph which is a kind of placeholder. It can contain content such as a copyright statement.

Tags rendered as page elements
Tag library allows developers to customize the authoring environment and create templates in a fast, efficient and re-usable way. Examples of tags rendered as page elements:

  1. The mainBar tag creates a toolbar at the top of the page for setting page properties.
  2. The main area of the page includes a contentNodeIterator tag. It looks for any paragraphs that reside inside the main area and includes their paragraph scripts using the includeTemplate tag. Note that the paragraph with the basketball players is not rendered by the page script but the included paragraph script below it. The editBar associated with this paragraph is added in the paragraph script, not in the page script.
  3. A newBar creates a toolbar that allows authors to add new paragraphs on the page.
  4. The footer section also uses the includeTemplate tag. It calls another paragraph script (not displayed) that creates navigation links and a copyright statement.

Areas
Page layout is controlled by CSS. The page templates shipped with the Standard Templating Kit organize the page layout using areas. These are controllable blocks, typically rendered as div elements, that help you customize the layout. Each div element has an ID attribute and an associated style definition. The diagram illustrates some key elements on an article page template. For example, the element that renders the vertical navigation on the left is <div id="nav">.

Inclusion
Page and paragraph templates can call other templates through inclusion. Templates at higher level can include lower-level templates using Freemarker's #include directive. This approach allows you to modularize and repurpose your template scripts. It also has the benefit of keeping scripts brief and readable.

  • No labels