Templating introduction for beginners - Community Wiki

This page is intended as an overview of the templating system for absolute beginners. It's not a replacement for the Templating tutorial, but it might help to read this first before or after doing the tutorial to give you a sense of how the whole things fits together. There's also a couple of corrections to some out-of-date parts of the tutorial which will make you life easier if you read this first.

These are the elements that make up the Magnolia templating system :

CSS files (referenced from your template files)
Page Template JSP files (Must be associated with a node in the config/modules/templating/templates tree)
Paragraph template JSP files (Must be associated with a node in the config/modules/templating/Paragraphs tree)
Dialog definitions (created in the config/modules/templating/dialogs tree)

don't worry about the config tree stuff at the moment - I'll explain later.

Basically Magnolia itself manages a sort of hierarchical database. Each node of the database can contain other nodes and can also contain named bits of data (NodeData). Magnolia uses this database to store your pages (where the hierarchy reflects the page hierarchy of your site, and the contents of each page), and also to store it's own configuration information.

Each page of your site will be a node in this tree. Each "page" node will be associated with a Template file (a jsp file). The template is going to be a mixture of HTML and tags which tell it how to render the page. Most pages will contain "Paragraphs", which are chunks of stuff you can add to the page. When you make the page template you can list what types of paragraph are allowed on the page. Paragraphs are stored as nodes underneath the Page node in the content hierarchy - normally what a Page template does is simply iterate through the nodes it contains and tell Magnolia to render each node as a paragraph. Here's some template code that does that :

<cms:contentNodeIterator contentNodeCollectionName="mainColumnParagraphs">
    <div style="clear:both;">
        <cms:adminOnly>
            <cms:editBar/>
        </cms:adminOnly>
        <cms:includeTemplate/>
    </div>
</cms:contentNodeIterator>

(The bit inside the "adminOnly" tags is to draw an "editBar" control on the page when it's being used by an administrator or page author - the editbar lets the page author create new paragraphs etc.). The "contentNodeIterator" tag iterates over all the content nodes in the given collection on the page (you can have multiple collections if, for instance, you have multiple columns on your page or whatever). The "includeTemplate" tag is basically telling Magnolia to inline the appropriate paragraph template for each node.

Your Page Template jsp files need to be stored in the /templates/jsp folder in your Magnolia installation. You'll need to remember the path to where you saved it because you'll be using that in a minute. I recommend that you create a subdirectoy in the jsp folder for your own templates - it makes managing things easier.

When you've created a new page template JSP file you need to tell Magnolia about it - you have to create a new node in the config/modules/templating/templates tree in the "config" section of Magnolia. You will only be able to do this if you have suitable privileges - if the config tree isn't visible to you or you can't edit it then you will need to get your Magnolia administrator to give you more privileges. You create a new node which basically tells Magnolia where to find your template and what it's called - the easiest way is probably to copy and existing node for another template and edit it. Probably the most important part of the template declaration is the "path" attribute - that's the path to where you stored your template jsp file. There is a mistake in the existing Magnolia templating tutorial which is a bit of a killer - it forgets to mention that a Template needs to have a "title" attribute - without that it won't show up in the list of page templates, so you won't be able to actually use it for a page.

By the way - there is nothing magical or scary about all the strange text you will find in some of the template configs in Magnolia that.has.lots.of.full.stops.in.it.like.this - These are just internationalized strings, basically they allow the text in a particular node to show up differently in different languages. When you're creating your own templates and don't care about internationalization then you can just type whatever you want there - for instance the "title" node of you template could be "Josh's sexy page" it doesn't have to be something like "josh.sexy.page".

Right - Paragraphs are a little tricky to understand. They're actually fairly simple, but "Paragraph" is a stupid name which I find confusing. A "paragraph" is actually a node which contains a bunch of named bits of data of various types - an object, really. It's quite likely to represent an actual paragraph on a webpage of your site, but it doesn't have to - it's simply a chunk of data that can be read by a template to produce whatever output you want on the page. If you're creating your own type of paragraph you will make a Paragraph template (a JSP, just like a page template) that will read the data from the paragraph node and render it to html.
Your paragraph template gets passed a reference to the current paragraph node and can use it to extract this data to draw into the page. This bit of template code for instance, checks whether a paragraph has a title, and if so writes it to the page, and then writes the text of the paragraph to the page :

<cms:ifNotEmpty nodeDataName="title">
        <h2><cms:out nodeDataName="title" /></h2>
</cms:ifNotEmpty>
<cms:out nodeDataName="text" />

Basically this template is assuming that its paragraph node has two bits of data attached to it - one called "title" and one called "text". The names are arbitrary (as we'll see in a minute). As you might get the "ifNotEmpty" tag is checking whether there is any data for the "title" attribute and only writes the stuff inside it if there is. The "out" tag simply writes a text attribute to the page.

Like Page Templates, the JSP files for Paragraph templates need to be saved somewhere in the /templates/jsp subdirectory of your Magnolia installation.

Like Page Templates, paragraph templates need to have a declaration in "config/modules/templating/Paragraphs" before Magnolia will recognise them. Again the easiest thing to do is probably to copy an existing paragraph declaration and edit it. Most of the attributes are self-explanatory, except perhaps the "dialogPath" one - we'll be getting to that in a minute.

Ok - So the last piece of the puzzle is how we define the actual data that makes up a paragraph. Different types of "paragraph" may need different kinds of data - for instance in the project I'm working on right now I have a simple paragraph type for "text paragraph" which just takes a text string, and I have another paragraph type for "line of images" which has up to 5 images, and scales them into a kind of dividing line on the page. Each paragraph type needs different data. You define what kind of data your paragraph has by creating a "Dialog". A Dialog defines both what data will be created for a paragraph, and how the Dialog to edit that data will be laid out. You associate your new paragraph style with a particular dialog using the "dialogPath" property of your paragraph declaration - so when your users create a new paragraph Magnolia looks up what dialog to use according to this property and then presents it to the user to enter their data.

A Dialog is defined in the "config/modules/templating/dialogs" tree. Have a look at the standard paragraphs that ship with Magnolia - the easiest way to make a new paragraph is generally to copy one of the existing ones then delete anything you don't need from it and copy anything you do need from other dialogs. The main thing about Dialogs is that they contain a list of controls, each of which defines one of the bits of data that will be associated with the paragraph. The "name" property of each control specifies what that bit of data will be called - that's where the "title" and "text" names came from in the bit of paragraph template code above - they are the names given to the associated bits of data in the dialog definition.

Once all these parts are in place you've made a new page, and new paragraph style and a new dialog definition. Congratulations. Remember though, that there's no reason that you need to do all of these - you can make a new page layout that will use the existing paragraph definitions, for instance. You can even make a new Paragraph template that uses an existing dialog - perhaps you want another way to display text-with-an-image ? There's no need to make a new dialog for it, because there's already a textImage dialog - you can just associate your new paragraph template with the existing dialog.