Create your own HTML template

In this tutorial you will learn how to create your own template for MacSnapper.

There is also a reference template, called clean.cshtml, available to start with.

The XML document

MacSnapper will produce a simple XML document when exporting a lesson.

The following XML document will be used as an example in this tutorial:

<lesson>
    <title>Open Accounts Preferences</title>
    <step position="1">
        <title>Open Preferences</title>
        <directory>Open_Preferences</directory>
        <detail>Click "System preferences..."</detail>
        <image>Open_preferences.png</image>
    </step>
    <step position="2">
        <title>Click Accounts</title>
        <detail></detail>
        <image>Click-accounts.png</image>
    </step>
    <lesson>
        <title>Setting Permissions</title>
        <step position="1">
            <title>Open Terminal</title>
            <directory>Open_Preferences/Open_Terminal</directory>
            <detail></detail>
            <image>Open_terminal.png</image>
        </step>
    </lesson>
</lesson>

MacSnapper will produce an XML file for each lesson and will contain all sub lessons.

Anatomy of a template bundle

A MacSnapper template is a bundle (folder) and contains two essential files, lesson.html and Info.plist.

A folder with the extention *.cshtml and containing the above two files is sufficient to call it a template bundle. Also there are a few other folders which you create within your template bundle.

Contents of a template bundle

lesson.html: Regular HTML file with additional "tpl" directives. It must be a well formed XML file
Info.plist: a property list file containing meta information about the template
thumbnail.png: a thumbnail image of your template look. Preferred size is 150x100 pixels
images: your images used in the template (not the step images)
css: your stylesheet (*.css) files.
styles: your stylesheet files. Each .css file will be listed as different style in MacSnapper. Add your stylesheet to this directory if you want to support different styles like colors, fonts, etc.
assets: this folder will be copied to the output directory. Use it. It's yours.

The folders images, css, styles and assets will be copied to the export directory.

You must not create a template bundle from scratch. Instead, duplicate and rename the template clean.cshtml, which is a simple and complete template example.

If you want, you can design a lesson.html file with your preferred WYSIWYG editor, or use a text editor.

Where should I place my template bundle ?

MacSnapper will search for template bundles in its Application Support folder

/Users/<you>/Library/Application Support/MacSnapper/Templates/

MacSnapper will search also yor Desktop for templates. This is very handy for template developers

/Users/<you>/Desktop/

About Info.plist

Info.plist contains information about the template.

The following example is the Info.plist file of the "clean" template.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>company</key>
	<string>Kedisoft</string>
	<key>name</key>
	<string>Clean</string>
	<key>id</key>
	<string>com.kedisoft.templates.clean</string>
	<key>ignoreFont</key>
	<true/>
	<key>defaultStyle</key>
	<string>blue</string>
</dict>
</plist>

Defined keys in Info.plist

company: Your company name (or any string value if you are just developing the template for yourself)
name: Template name. This is what the user will see.
id: A unique identifier. MacSnapper will manage you template using the id and not the template name.
ignoreFont: Set this to true, if you want to display lesson and step detail texts using your own font definitions. Set this to false if you want MacSnapper to generate span tags with font definitions as defined by the user within the application. (Default is 'false')
defaultStyle: A css filename without extension placed in the stylesheets directory. This is useful to define a default style sheet if you have multiple sheets. If you not define a default style, MacSnapper will use the first css file found in the stylesheets directory. If you don't have a css file in the stylesheets directory, the default stylesheet will be 'basic'.

Variables defined in templates

There are some variables which you can use in lesson.html

@root: path to the export directory
@css: path to the css directory
@styles: path to the styles directory
@style: style name seelcted by user. This is the selected css filename without extension.
@images: path to images directory

The next examples will show you the usage of these variables.

TPL directives

Kedisoft has developed some directives to construct XHTML by using the input XML data.

To add TPL directives, define the following namespace

<html xmlns:tpl="http://www.kedisoft.com/tpl">

All directives are attributes. Example:

<h1 tpl:replace="title">A title to replace with</h1>

Following directives are available

tpl:replace = "xpath"

Replaces the content of an element with the result of the given xpath, applied on the source XML.

You can also combine multiple xpath directives in tpl:replace. Place all xpath directives between brackets.

Format:

"{xpath1}{xpath2}..."

Outside the brackets you can add static text.

Example:

"{@position}. {title}" -> "1. Open Preferences"

@position is an XML attribute and title is an XML element as defined in lesson-v1.xsd.

tpl:loop = "xpath"

Applies the node, where tpl:loop is placed, to all source XML nodes returned by the given xpath directive.

Example:

<div tpl:loop="step">
    <h1 tpl:replace="title">A title</h1>
</div>

Result:

<div>
    <h1>Open Preferences</h1>
</div>
<div>
    <h1>Click Accounts</h1>
</div>

xpath directives within a loop (like "title" in the above example) are relative to the nodes returned by tpl:loop="xpath"

tpl:attribute = "htmlattr:xpath"

With tpl:replace you can add content to an element. However, to add XHTML attributes you can use tpl:attribute.

Format:

tpl:attribute="<attrname>:xpath"

Example:

<img tpl:attribute="src:image"/>

Result

<img src="Open_preferences.png"/>

You can also combine xpath directives and static texts.

Example:

<img tpl:attribute="src:../steps/{image}"/>

Result:

<img src="../steps/Open_preferences.png"/>

You can add attributes when you design. These will be removed in the resulting XHTML file. However, it is very useful while you design your template.

Example:

<img src="dummy.png" tpl:attribute="src:../steps/{image}"/>

Result:

<img src="../steps/Open_preferences.png"/>

tpl:goto="label" and tpl:label="a name"

you can redirect the next output node by using tpl:goto. tpl:goto will set the next output node to the labeled node.

Example:

<div tpl:label="lesson-label">
    <h1 tpl:replace="title">Lesson title</h1>
    <h2>Sub lessons</h2>
    <div tpl:loop="lesson" tpl:goto="lesson-label"/>
</div>

Result:

<div>
    <h1>Open Accounts Preferences</h1>
    <h2>Sub lessons</h2>
    <div>
        <h1>Setting Permissions</h1>
        <h2>Sub lessons</h2>
    </div>
</div>

tpl:if="xpath"

prevents the template from writing out an XHTML node. The <h2> tag in the above example will always be written out. We want to write the header for sub lessons only if sub lessons exist.

Example:

<h2 tpl:if="lesson">Sublesson</h2>

Use tpl:if to check

whether an element exists or not

or an element is empty

The step at position "2" in our example input XML file has an empty <detail> tag. To prevent the template from writing out empty <div> tags, we can use tpl:if

<div class="step-detail" tpl:if="detail"> ... </div>

Summary

Designing templates for MacSnapper is very easy. The clean template is almost a completed template and you can start designing you own template by modifying this template.

If you have questions or suggestions, just drop me an email.

Thanks for reading.