Making Your First Advanced Template documentation for the dotCMS Content Management System

In the previous tutorial you created a staff content type and you were able to add staff content from the Content tab.  Adding the Staff type content on a page, however requires either a staff type Container/Template be created, or a dynamic listing of staff on any page.  First, we will show the Container/Template method for placing static "Staff" type content on a section of a page, then we'll show how to create a dynamic listing of staff towards the end of these tutorials.

The first thing you are probably asking yourself is - "what is a Container and why do I need one on a dotCMS template?"  Links at the bottom of this page will give you more information on both, but basically Containers act like server-side "include" files and can be used to place re-usable HTML elements across many templates and pages.  But the best way to understand what a container is/does, is to create one and use it on a dotCMS page.  This easy tutorial should take only a few minutes, so don't be intimidated. 

Now let's create a Container that allows users to contribute the staff content type we created in the previous tutorial.

*Create a Container for the "Staff" Content Type

  1. Log into your dotCMS installation.  From the Website tab, click on "Containers" in the drop down menu
  2. Click the "+Add Container" button on the top, right-hand side of the page
  3. Type "Staff Content Container" in the title field
  4. Type "Accepts Staff Content and displays name, title, and email" in the description field
  5. Set the Max. Contents field to 5
  6. In the Content Type field, select the "Staff" Content Type we created earlier
  7. Click the "+Add Variable" button under the required Code field
  8. Click the "Add" button next to "Last Name" and then add a comma and space after the variable in the code field
  9. Click the "+Add Variable" button under the required Code field again
  10. Click the "Add" button next to "First Name"
  11. Wrap both of the velocity variables inside some HTML styling like this Ex: <h3>$!{lastName}, $!{firstName}</h3>
  12. Press enter on you keyboard to go to the next lin in the code field and click on the "+Add Variable" button again
  13. Click the "Add" button next to "title"
  14. Place HTML wrapping around the title field to italicize and add a line break Ex: <em></em><br />
  15. Press enter on you keyboard to go to the next lin in the code field and click on the "+Add Variable" button again
  16. Click the "Add" button next to "email"
  17. Wrap both the title line and the email variable in an HTML paragraph tag.  The code in your code field should now look like this:
  <b>$!{lastName},   $!{firstName}</b><br />
  <em>$!{title}</em><br />
  1. Click the "Save/Publish" button on your container.

Your container is now ready for to be used by one or more templates to place staff type content and to display some limited information about a staff member.  Now all we need it a Template to call our container and a page that uses that template.  

Now that you have created a Staff Content Type and a Container that is formatted to allow "Staff" content contribution, let's customize a template to use the "Staff" content container.

Your First Advanced Template

The dotCMS includes some example templates.  We will copy one of those templates, take a look at the elements that comprise a template, and parse our new container in the template.  We'll then create a page using your custom template and place some content on a section of the page that is calling your custom "Staff" content container.

Creating an Advanced Template

  1. Click on the Templates option on the Website tab on the backend of the dotCMS
  2. There should be a starter template called "3 Column (Narrow Right, Wide Left Bar)" that came with dotCMS when you downloaded the dotCMS.  Right-click on the template title and select "Copy"
  3. You should now see a Template called "3 Column (Narrow Right, Wide Left Bar) (COPY)", click on this template title to edit the template.
  4. Rename the title and description of the Template to indicate that it is to be used for "staff" pages - Ex. title: 3 Column (Narrow Right, Wide Left Bar) - Staff Ex. description: Three columns with staff in right column
  5. Below the description field you will see a template code field.  In the template code field you will see both HTML and velocity code that are run on any page using this template.  We want to add staff content on the right hand side of the body of our pages, so leave the header and footer sections as they are and find the following Velocity code lines:
## Container: Starter - Body Container 2
## This is autogenerated code that cannot be changed

Highlight and delete these three lines only, but leave your cursor in that space, ready to insert a new container in the next step

  1. Click the "add container" button at the top of the template code area.  In the "Select a Container" light box, click the drop down list of containers on your site and select the custom "Staff Content Container" you created at the beginning of this tutorial, and then click "Add".  Three lines of code should be added that refer to your container and parse or "include" the container code in the template.
  2. Click the "save and publish" button
Congratulations! You have customized your first template and you are now ready to use this template with a page and place staff content on that page in the right hand column.
  1. Click on the Website tab
  2. Right-click on any existing folder (or create a new one), select "+New", and "HTML Page"
  3. Give your page a title Ex: My First Staff Page  (don't worry about the Page URL field as it will auto-populate)
  4. Click on the Template drop down list and choose your custom template (Ex: 3 Column (Narrow Right, Wide Left Bar) - Staff)
  5. Click "save and publish" which will open your page in edit mode
  6. Click the "+Add Content" button in the right column of the page and select "New Content" from the drop down menu
  7. You will now notice that the Content Type is set to "Staff" and the fields that are displayed are the fields that you created when you made your "Staff" content type in the first lesson of these tutorials.  Fill out the required fields for a staff member and click "Save/Publish".
  8. You should now be looking at a piece of staff content whose presentation or styling are displayed as you instructed it to in the container you created.  It should look something like this:
Ezell, William
Chief Toy Operator
  1. You will be able to add up to 5 staff pieces of content on the page (remember we set max contents to 5 on container)

To recap, advanced templates use standard HTML and combined with velocity to parse containers and provide the "layout" for the page.  Containers format the way that content is placed and displayed on each section of the page by allowing content contribution of only certain content types.  dotCMS pages are nothing more than a page title, a URL, and a link to a template.  

In the last two sections of the webmaster tutorials we will show you how to dynamically display ANY content type on ANY section of a dotCMS page.   However, the next tutorial will continue to improve your template by addressing how to create crumbtrails and navigation menus.