SiteTool v0.3.0 documentation

HowTo Guides ¶

Contents

HowTo Guides

Turn a page into a template ¶

Create a copy of index.html and name it something like tobetemplate.html
Create the Templates directory

Run this command:

due move -s ./ tobetemplate.html Templates/main.dwt

This will move the page to the Templates directory, update all the links it contains and leave the rest of the site alone. The -s option tells due ehere the site root is. You should now be able to view the main.dwt file in the browser and everything will still be correctly linked.

Next you need to add editable regions.

Add editable regions to a template ¶

Editable regions in templates require markup like this:

<!-- TemplateBeginEditable name="breadcrumbs_bottom" -->
<!-- TemplateEndEditable -->

Any content which is between the two HTML comments is treated as editable and can be changed in the pages which use the template. In this case the editable region is named breadcrumbs_bottom.

Your template must have the following region which contains the <title> tag:

<!-- TemplateBeginEditable name="doctitle" --><title>James Gardner</title><!-- TemplateEndEditable -->

The template will usually also have editable regions named header, content, nav and footer but these are optional.

Tip

It is often a good idea to replace the existing content in the heading and content editable regions of the template with placeholder text such as HEADING GOES HERE and CONTENT GOES HERE so that you don’t have to delete lots of old content from the original page each time you create a new page from the template.

Apply a template to a page ¶

Now that you have created a template you’ll want to apply it to a page.

First add this immediately after the first <html> tag right at the top of the page:

<!-- InstanceBegin template="Templates/main.dwt" codeOutsideHTMLIsLocked="false" -->

Replace Templates/main.dwt with the relative path from the page to the template.

Now, for each editable region in the template you’ll need to mark up the corresponding editable region in the page, but instead of using a pair of comments with the string TemplateBeginEditable and TemplateEndEditable in them, you use InstanceBeginEditable and InstanceEndEditable. Here’s the page markp for the title:

<!-- InstanceBeginEditable name="title" --><title>James Gardner</title><!-- InstanceEndEditable -->

The whitespace and line breaks should be unimportant.

Once you have updated the page you can reapply the template to correct any whitespace issues. Run this command:

due update -T -S index.html -s .

Create a new page using a template ¶

Now that you have a template you can create a new page.

$ due create Templates/main.dwt faq/index.html
INFO: Saving file '/home/james/Desktop/spy/faq/index.html'...
INFO: Updating any context items...
Page created successfully.

The page faq/index.html gets created from the template but with all links and paths updated correctly.

Editing a page region ¶

You can edit a page region with any editor but due also provides a set of command line tools to help. Here’s how to edit the content of the page you just created:

$ due set faq/index.html -ia content

The command loads whichever command line editor is specified in your EDITOR environment variable. When you save the temp file you are editing the content of the region you are editing within the page gets updated:

INFO: Updating file /home/james/Desktop/spy/faq/index.html...
INFO: Saving file '/home/james/Desktop/spy/faq/index.html'...
Successfully updated

I’ve written the command with the -i and -a options after the file itself because you generally update multiple regions for each page (heading, title, content etc) so having the region name at the end makes it a bit easier to edit the command for each region.

Adding navigation components ¶

Most web sites have a main navigation component with a particular link highlighted depending on which part of the site the visitor is in. If the navigation menu looks the same on every page of your site you can simply include it in the template, otherwise you need to create different navigation menus for each section. There are a number of approaches you can take for this:

use a different template for each navigation
create a new editable region and a set of library components for each of the possible navigation menus, putting the appropriate library component in each page
develop a custom context item which automatically generates the correct navigation menu for you

Option 1 is useful if the sections have a different template or theme anyway, option 3 is best for really large sites where the time spent coding the context item would be shorter than that required to apply the library components and keep them up to date but for most small sites, option 2 is best.

The easiest way for small sites is just to create library components.

Our navigation menu looks like this with the active list item having the id="active" attribute added:

<div id="navcontainer">
    <div class="center">
        <ul id="navlist">
            <li id="active"><a href="./" accesskey="1">Home</a></li>
            <li><a href="instructions/index.html" accesskey="2">Instructions</a></li>
            <li><a href="faq.html" accesskey="3">FAQ</a></li>
            <li><a href="contact.html" accesskey="4">Contact</a></li>
       </ul>
    </div>
</div>

Create a Library directory then create four library components, one for each section, and put them in the Library directory. Name the four files as follows:

Library/nav_home.lbi
Library/nav_instuctions.lbi
Library/nav_faq.lbi
Library/nav_contact.lbi

Each one should be identical except that the id="active" attribute should be on the navigation item which should be highlighted for that section.

Now you need to add the navigation items to each of the pages in the site. Choose the component which will be used the most, in this case instructions, and create a new region in the template with that library item embedded like this:

<!-- TemplateBeginEditable name="breadcrumbs_bottom" -->

<!-- #BeginLibraryItem "../Library/nav_instructions.lbi" -->
<div id="navcontainer">
    <div class="center">
        <ul id="navlist">
            <li id="active"><a href="./" accesskey="1">Home</a></li>
            <li><a href="instructions/index.html" accesskey="2">Instructions</a></li>
            <li><a href="faq.html" accesskey="3">FAQ</a></li>
            <li><a href="contact.html" accesskey="4">Contact</a></li>
       </ul>
    </div>
</div>
<!-- #EndLibraryItem -->

<!-- TemplateEndEditable -->

Notice that we haven’t just included the HTML but also marked the content as a library item. That way whenever the Library/nav_instructions.lbi changes, every page containing it can be updated too.

Now update all the pages like this to give every page using the template the instuctions navigation:

due update -rT -s .

Now you have to go through all the other pages which shouldn’t have the instructions navigation and update them to use the appropriate library item. Again, make sure you add the correct #BeginLibraryItem comments so that the contents can be updated later if necessary.

Deploy a site ¶

Re-generate the sitemap:

due sitemap -c about.html sitemap.html

Create a list of all the orphaned files (which you don’t want on the server because they aren’t linked from anywhere so no-one can find them anyway):

due orphan -c about.html --relative  > orps.txt

Then sync the site, excluding the orphaned files:

due deploy -c about.html --exclude-from orps.txt