Templating Basics

A template is a model page, which defines how the content of real pages should be laid out, decorated (enhanced with colors and graphics), and typographically styled.

A template is very similar to a real page, except that it does not appear in any site maps. Instead, a template serves as a framework that page-specific content is inserted into. However, templates can be previewed and managed exactly like regular pages, using the Website Editor.

Every real page points to a template that it will use as its framework. Reformatting a page is as simple as pointing the page to a new template. In the Website Editor you do this by selecting Template > Change Template from the page view menu. You can also change all pages in a site to use a new template by selecting Template > Change for All Pages from the site view menu.

How Templates Work

When ExSite has to draw a page, it has to start from some basic block of HTML. To do this, it looks for a content item named "page", which contains the base HTML framework into which all secondary content is inserted. Typically the "page" content item is defined by the template. (In principle, any web page can define its own "page" content item, and this is sometimes useful to override the templated layout for a particular page only, while still using all of the template's image files.)

The "page" item contains the base HTML for the page, with various content-management tags that tell ExSite how to find auxiliary content, such as style sheets, images, scripts, and body content. ExSite begins by parsing the content of the "page" item, finding each secondary content item that is referenced within it.

Each secondary content item has a name, and ExSite searches for content under that name, in the following locations:

• in the current page
• in the current page's template
  • the template's template, if there is one
    • ...etc
• in the libraries of the current site
  • in the libraries of the parent site
    • ...etc

As soon as a match is found, ExSite substitutes that content item in place of the content management tag. If no match is found, ExSite substitutes nothing in its place.

Since other content items can also contain content management tags, this process can continue to several levels depth, until ExSite is satisfied that all content references have been satisfied.

Content Management Tags

ExSite uses a special set of tags embedded in the HTML to tell itself to insert new content at those positions before sending it out for viewing/publishing. There are five types of special content management tags that ExSite recognizes:

HTML Substitution (<!--content(name)-->)

these tags are replaced with the named block of HTML. If the named content is not HTML (eg. it is an image), then ExSite creates some HTML to display the content appropriately.

Content-URL Substitution ([[name]])

these tags are replaced with a URL to the named content item. This is normally used when referring to external files such as images, scripts, or stylesheets.

Page-URL Substitution ({{page}})

these tags are replaced with a URL to the named page. The page can be specified by its filename (eg. {{index.html}}) or its numeric page ID.

Meta-data Substitution (<!--$meta-->)

these tags are replaced with the named metadata (eg. title, description, keywords, etc.)

Dynamic Web Application Substitution (<!--&Module(...)--> and <!--&&Module(...)-->)

these tags are replaced with whatever content the named web application module provides to the page.

These are described in more detail below.

Expert-level ExSite users may wish to code these tags directly into their HTML, but this is not necessary. The ExSite HTML editor has friendly tools for automatically inserting the appropriate tags in the correct format.

URL substitutions

Content-URL tags of the form [[xyz]] can be used anywhere you have a SRC= attribute in your HTML, especially IMG tags:

>img src=[[logo]] height=50 width=50 border=0 align=left>

This type of substitution also works for linked stylesheets, and externals scripts (note the quoting, which is optional but recommended in most cases):

<link rel="stylesheet" type="text/css" href="[[stylesheet]]">
<script type='text/javascript' src='[[my_script]]'>

It can also be used inside javascript, as in this example of a rollover-image function call that uses image "home0" for the normal image, and "home1" for the rollover image:

<a href="index.html" onMouseOut="MM_swapImgRestore()" onMouseOver="MM_swapImage('home','','[[home1]]',1)">
<img src="[[home0]]" width="36" height="15" border="0">
</a>

For images, it is often convenient to give the content item the same name as the original file. For example, this raw HTML:

<img src="ourlogo.jpg" height="50" width="50" border="0" align="left">

can be templated with this:

<img src="[[ourlogo.jpg]]" height="50" width="50" border="0" align="left">

This allows you to very quickly run through a regular HTML file and convert all SRC= attributes by simply adding the square brackets. Designers who are accustomed to working directly with filenames may also find it more readable. If the original image name includes a path, the path should be removed from the content name to leave just the file name.

HTML substitutions

CMS tags of the form <!--content(xyz)--> can be placed anywhere in your HTML file. This tag is always replaced with HTML. If the content being substituted is already in HTML format, then it is simply swapped into place.

Any HTML content that is substituted into a page may contain other substitution tags embedded in it. The Content Management System will continue trying to expand these new tags until it cannot proceed any further. This process can continue to any depth.

WARNING: It is possible to accidentally code self-referential content loops -- for example, when your page body contains a tag like <!--content(body)-->. ExSite may not be able to generate your page in these cases.

Creating Templates

Creating a Template from an Existing Web Page

1. Make a copy of a representative page, including images.

   This is easily done using your browser's "save as complete webpage" function. This will save your webpage as an HTML file, and save all the auxiliary files, such as stylesheets and graphics, in a subfolder.

2. Create the template in ExSite

   Go to your website in ExSite's Website Manager (the page that shows all your web pages as icons), and from the menu, select Template > Import Template. Provide some basic info about your template, including a publication directory name (for example "Green_Template"). Choose "static" publishing, unless you know what you're doing (more info). You will also be asked to upload the copy of the webpage (the HTML file you saved in the previous step).

3. Upload Auxiliary Files

   ExSite will scan your template, looking for extra files that it needs. It will list all of the files it finds, and ask you to upload each of them. Browse for each file until ExSite knows where they all are, and then proceed to the next step.

   ExSite may not find every file that it needs. It is good at spotting files that are directly referenced in the HTML (eg. <IMG SRC="filename.jpg">), but usually misses files that are referenced in stylesheets (eg. background-image:url(filename.jpg)). Missing files can always be imported later.

4. Fine-Tune Your Template

   At this point, your template is created, and is technically useable. However in practice, there is some manual fine-tuning that will be necessary. In particular, it will probably be necessary to edit the template's page object (in simple text mode), in order to:

   • remove any non-template text/HTML from the sample page you imported, and replace it with appropriate CMS tags. For example, the main body of page text should probably be replaced with a CMS tag like this:

   <!--content(body)-->
   

   • repeat the above for any other sections of content that should be managed separately from the body, such as sidebars, footers, etc.
   • edit any meta-data tags to remove page-specific meta-data such as titles, and replace it with special CMS tags to substitute the appropriate meta-data at a later time. More information is here.
   • template your menus. In the simple case, you can have hard-coded menus, in which case you should template your page links (more information here). Otherwise, you will use a menu plug-in, such as SimpleMenu, which can dynamically build context-sensitive menus for you.
   • double-check that all external files are being correctly referenced. Sometimes ExSite can miss files, especially if they are hard to spot inside CSS or Javascript. If some files have been overlooked in these places, they will have to be tagged by hand. More information is here

Creating a Template from Scratch

This procedure is more involved than a simple import, but it gives you plenty of control over the details.

1. Make a copy of a representative page, including images.

   This is easily done using your browser's "save as complete webpage" function. This will save your webpage as an HTML file, and save all the auxiliary files, such as stylesheets and graphics, in a subfolder.

2. Create the template in ExSite

   Go to your website in ExSite (the page that shows all your web pages as icons), and from the menu, select Website > New Template. Provide some basic info about your website, including a publication directory name (for example "Green_Template").

   You may be prompted to select a parent template. Ignore this step (select nothing) if you are working with a brand new template.

3. Open your new template

   Go back to the website view (use the path box beside the typewriter icon), and select the icon for your new template. (Templates have an icon showing drafting tools.) It will open up, but be empty of content.

4. Create the "page" object

   The first thing to do is create the framework for the entire page. From the menu, select Page > New Content Item. The name of this content item must be "page". The category should be "design", and the allowed mime-types should be "HTML". (Different choices are possible, but not normal in this case.) Press the "Next" button.

   Using the file browse field, select the representative page (typically an HTML file) that you saved in step 1. Press the "Next" button when you are done.

   Lastly, you will need to include a short comment explaining this update. Enter "import" or something like that. Press the "FINISH" button. You will be taken back to the template view, where you will see the "page" object you just created.

5. Update your "page" object

   You imported a regular page, but now you must convert it to a template by modifying the HTML to use ExSite content management tags, instead of regular HTML tags. From the page menu, select Update > update page.

   ExSite will render the page in its WYSIWYG editor. There may be lots of holes, because we haven't loaded the images yet, but ignore that for now. We need to work directly with the HTML tags, so change the update method to "Edit using a simple text editor". This will change the WYSIWYG editor to one that shows the raw HTML.

6. Modify all external content URLs

   External content URLs are tags that point to images, stylesheets, scripts, and other items that are stored in separate files. For example:

   An external stylesheet:

   <link href="solutions_files/exware.css" rel="stylesheet" type="text/css">
   

   An image:

   <img src="solutions_files/ex-logo.gif" width="42" height="42" alt="">
   

   A javascript argument referring to an image file:

   onmouseover="MM_swapImage('solutions','','images/solutions_alt.gif',1)"
   

   Replace all external file names with a simple name enclosed in double-square brackets. The simple name can be any unique name that you will use to reference that file, but it's often easiest just to re-use the original file name. Do not include any directories or other URL data that was included in the original URL. For example, the above 3 tags could be converted to this:

   <link href="[[exware.css]]" rel="stylesheet" type="text/css">
   
   <img src="[[ex-logo.gif]]" width="42" height="42" alt="">
   
   onmouseover="MM_swapImage('solutions','','[[solutions_alt.gif]]',1)"
   

   This new notation tells ExSite that you want those files to be managed by the content management system.

   Make a note of each file that you reference this way, as they will have to be imported into the content management system later (step 11).

7. Modify internal links

   An internal link is a link to a page in the same website. For example:

   <a href="index.html">Home</a>
   

   You can replace all internal links with file names enclosed in double-braces, for example:

   <a href="{{index.html}}">Home</a>
   

   This notation allows the content manager to make the correct link to the file, regardless of whether the page is published to an HTML file, is not published yet (and only exists in the database), is never published (due to security or dynamic content requirements), or changes its status at some time in the future. It also allows webmasters to navigate through the site with various content management features enabled on each page.

   You do not have to change your internal links to use this notation, but if you do not, then the links will not work until the pages are published, nor if the pages are ever switched to dynamic rendering or members-only access.

   External links (to other sites) should not be changed.

8. Define your main content areas

   Identify the main body of your page, and replace it all with a single tag:

   <!--content(body)-->
   

   This tells the content management system to substitute the body into that position. It also keeps the body separate from the template itself.

   If your page has a complex structure, with more than one content area that can be edited, you can repeat this step for each such area. Give each new area its own name (eg. "sidebar", "footnote", ...).

   If you have sections of content that you want to appear on every page, then leave them in place as part of the template.

9. Edit your meta-data

   Meta-data is additional information hidden inside the page, such as titles, descriptions, and so on.

   Titles look like this:

   <title>Solutions in action</title>
   

   Titles can be templated like this:

   <title><!--$title--></title>
   

   Descriptions look like this:

   <meta name="description" content="description of this webpage">
   

   Descriptions can be templated like this (note the curious comment-inside-a-tag notation):

   <meta name="description" content="<!--$description-->">
   

   Similarly, you can substitute meta-data anywhere into your page, using the <!--$meta--> tags. meta can be one of:

   • title
   • description
   • keywords
   • filename
   • label [the menu label used for this page]
   • mtime [last modification time of the meta-data, timestamp format]
   • page_id [a numeric identifier for the page]
   • site_title
   • site_description

10. Save your updated page object

    After making your changes, click "Next" and then enter a comment such as "added templating tags", for auditing purposes.

    You can always return to updating the page object to refine, fix, or add new templating instructions. To do this, repeat steps 5-9.

11. Import your external files

    For each external content file templated in step 6, you must import the file into the content management system. The easiest way to do this if you have multiple files, is to use the Page > Bulk import menu function from the page view. This allows you to upload up to 10 files at a time. Use the selector at the top to determine whether the content is "editorial" or "design" content. (For templates, "design" is usually the correct choice.) All bulk uploaded files will be named and referenced by their original file name.

    If you want more detailed control over the naming and configuration of particular content items, then you can upload them individually using the Page > New Content Item menu option. This allows you to customize the naming and access control details of each content item:

    • from the template screen (where you see the page icon), select from the menu Page > new content item.
    • give each content item a name that is the same as the filename (or whatever name you specified in step 6).
    • most imported content files in templates are "design" content, unless you want regular site editors to be able to modify these files.
    • optionally, specify the allowed content types for this content item (eg. image). Leave this blank to allow any content.
    • Upload the external file on the next screen. Upload the files from wherever you saved them in step 1.
    • Include a brief comment (eg. "import") after each update, or accept the default comment.

After you have imported your external files, try previewing your template. From the page menu, select View > preview. Your template should display like a normal web page, except with no core content. If you see that some images or other items are missing or misformatted, you can return to any of the above steps to correct those problems.

Using Your New Template

• On a new web page

  When you create a new page in the Website Editor, you will be prompted to select the template to base the new page on. Select your new template on this screen.

• On an old web page

  In the Website Editor page view for the page, select Template > Change Template. Select your new template for this page here. Republish the page to make the change public.

• On all of your old web pages

  In the Website Editor website view for the page, select Template > Change for All Pages. Select your new template for this page here. Republish the page to make the change public.

• On future web pages

  In the Website Editor website view, select Website > Configure Site. Select the default template for this website near the bottom of this form.

Experts only: when creating new pages, the Website Editor allows you to customize the layout for that page only. This is done by unchecking the "Skip Customize Layout step" box on the template selection screen. This has the effect of copying the template's page object into the new page, with the option to edit it. This effectively lets you customize or tweak the design/layout for this page only. If you want to have an altered layout that is re-useable, you need to create a derived template that can be shared. If the default layout of the template is acceptable, leave this box checked.

Publishing Templates

Although templates are models of pages, and not real pages, it is a good idea to publish them anyway. That is because templates typically incorporate numerous auxiliary files such as images, scripts, and stylesheets, and it can be a serious performance drag to fetch these files out of the content management system's database on every view. It is much better to publish them out to regular files, which not only means they are fetched faster by the webserver, but they work better with most web caching systems that will recognize them as simple cacheable files.

Publish a template in the same way you publish regular pages, ie. by selecting the publish template option from the template menu, or by publishing the entire site. Template files are published into the htdocs area of the website, in a folder named _Templates/[template_name]/.

The HTML for the template will also be published, if the template is set to publish statically.