The Anatomy of the Template File

At a minimum a template folder (whether a lesson template or a manual template) must contain a template file. This is the file that tells ScreenSteps how to process a lesson or manual for output. This lesson describes the anatomy of a template file.

Introduction

Introduction

A template file is a text file that consists of up to eight sections - Configuration, Content, Lesson Description, Step, Step Title, Step Instructions, Media:Image and Media:Image Full-Size.

Each section starts with "[-- START SECTION_NAME --]" and ends with "[-- END SECTION_NAME --]". The start and end entries appear on their own line (1).

ScreenSteps defines variables that you can use within a section to specify where ScreenSteps content should be placed. Let's look at each section in turn.

The Configuration Section

The Configuration Section

The Configuration section is where you set the template properties. ScreenSteps uses different properties depending on whether you are exporting a lesson or the table of contents for a manual.

Properties

web safe - true/false

applies to: lesson, table of contents

If true then all file names will be made web safe. Default is "false".

web safe delimiter - string

applies to: lesson

Sets the character used to replace spaces and other invalid characters when generating web safe output. The default is "_".

text style - html, xml, plain, xml-html, textile, markdown, markdown unescaped, bbcode, restructuredtext

applies to: lesson, table of contents

This setting specifies how styled text is handled (i.e. step instructions). "html" will output instructions using HTML tags for formatting (<strong>, <i>, <p>). "xml" will output unformatted text using the defined text encoding and then encodes any xml entities. "plain" will output unformatted text. "xml-html" will output HTML formatted text that has xml entities encoded. "textile", "bbcode", "restructuredtext" and "markdown" will convert the output using the specified markup's formatting. URLs are preserved but colors will be lost.

'markdown unescaped' will not escaped any markdown characters that appear in your content. You can use this if you want to write your lessons using the markdown syntax. Using 'markdown' will escape special markdown characters that appear in your ScreenSteps content.

Default is "html".

text encoding - utf8, iso

applies to: lesson, table of contents

How to encode the text. If text encoding is set to iso and text style is set to HTML then characters will be encoded as HTML entities if need be. Default is "utf8".

newline - unix, windows, mac

applies to: lesson, table of contents

Specifies what to use for newlines. "unix" uses ASCII 10, "windows" uses ASCII 13 + 10 and "mac" uses ASCII 13. The default is "unix".

lesson folder - string

applies to: table of contents

The folder to store lessons in when exporting a manual.

media folder - string

applies to: lesson

Path where the media will be output to. This path is relative to the folder you select when exporting.

font family - lucida, helvetica, georgia, courier, trebuchet

applies to: lesson, table of contents

This property defines what the %FontFamily% variable in the Content section will be. The default templates included with ScreenSteps define five different font families in the CSS file based on these five values.

image format - png, jpeg

applies to: lesson

The image format to use when exporting step images. Default is "png".

jpeg quality - integer

applies to: lesson

Compression quality to use if image format is "jpeg". Default is 85.

step image position - top, right, bottom

applies to: lesson

Where to position the image in relation to the step instructions. Default is "right".

max image width on side - integer or empty

applies to: lesson

The maximum width an image can have it it appears on the side of the step instructions. Image will be resized to fit. Set to empty for no limit.

max image height on side - integer or empty

applies to: lesson

The maximum height an image can have it it appears on the side of the step instructions. Image will be resized to fit. Set to empty for no limit.

max image width when centered - integer or empty

applies to: lesson

The maximum width an image can have it it appears above or below the step instructions. Image will be resized to fit. Set to empty for no limit.

max image height when centered - integer or empty

applies to: lesson

The maximum width an image can have it it appears above or below the step instructions. Image will be resized to fit. Set to empty for no limit.

replace content start - string

applies to: lesson

The string used to locate the beginning of ScreenSteps output. Used when exporting to blog/web so that ScreenSteps only replaces lesson content and not any additional content that may have been added since posting the lesson.

replace content end - string

applies to: lesson

The string used to locate the end of ScreenSteps output. Used when exporting to blog/web so that ScreenSteps only replaces lesson content and not any additional content that may have been added since posting the lesson.

Variables Available in this Section

@LESSON_NAME - The name of the project the user provides when exporting the session.

applies to: lesson

The Media:Image Section

The Media:Image Section

Applies to: lesson

The media:image section is the text that will be used for each image in your lesson. In this HTML example each image will be placed in an <img> tag that is wrapped in a <div> tag.

Variables Available in this Section

  • %source% - the relative path of the image.
  • %width% - the width of the image.
  • %height% - the height of the image.
  • %MediaNumber% - the number of the media in the lesson starting from 1.
  • %MediaNumberZeroBased% - the number of the media in the lesson starting from 0.
  • %FileName% - the name of the media file.
  • %FileNameNoExtension% - the name of the media file without the extension.
  • %StepTitle% - the step title.
  • %WebSafeStepTitle% - a cleansed version of the step title that is web safe.
  • %StepNumber% - the indexed step number. Steps are only indexed if the step has a title.
  • %StepIndex% - the actual step number, regardless of whether or not the step has a title.
  • %StepIndexZeroBased% - same as %Index% but starts counting at 0 rather than 1.

The Media:Image Full-Size Section

The Media:Image Full-Size Section

Applies to: lesson

If you include this section in the template file then any image that needs to be downsized in order to fit within the maximum width and height limits will have a full-size version exported as well. In this case Media:Image Full-Size will be used instead of Media:Image.

Variables Available in this Section

  • %fullsize_source% - the relative path of the image.
  • %fullsize_width% - the width of the image.
  • %fullsize_height% - the height of the image.
  • %MediaNumber% - the number of the media in the lesson starting from 1.
  • %MediaNumberZeroBased% - the number of the media in the lesson starting from 0.
  • %FileName% - the name of the media file.
  • %FileNameNoExtension% - the name of the media file without the extension.

The Step Title Section

The Step Title Section

Applies to: lesson

Use this section to format how the step title will be displayed. This section is not processed if the step has no title.

Variables Available in this Section

  • %Title% - the step title.
  • %WebSafeTitle% - a cleansed version of the step title that is web safe.
  • %StepNumber% - the indexed step number. Steps are only indexed if the step has a title.
  • %Indexed% - 'true' if the step has a title. 'false' if not.
  • %Index% - the actual step number, regardless of whether or not the step has a title.
  • %IndexZeroBased% - same as %Index% but starts counting at 0 rather than 1.

The Step Instructions Section

The Step Instructions Section

Applies to: lesson

Use this section to format how the step instructions will be displayed. This section is not processed if the step has no instructions.

Variables Available in this Section

  • %Instructions% - the step instructions.
  • %InstructionsPlain% - the step instructions without any styling.
  • %StepNumber% - the indexed step number. Steps are only indexed if the step has a title.
  • %Indexed% - 'true' if the step has a title. 'false' if not.
  • %Index% - the actual step number, regardless of whether or not the step has a title.
  • %IndexZeroBased% - same as %Index% but starts counting at 0 rather than 1.

The Step Section

The Step Section

Applies to: lesson

Use this section to format how the step will be displayed.

Variables Available in this Section

  • %STEP_TITLE% - the value of the Step Tile section.
  • %STEP_INSTRUCTIONS% - the value of the Step Instructions section.
  • %MEDIA_IMAGE% - the value of the Media:Image or Media:Image Full-Size section.
  • %Title% - the step title.
  • %Instructions% - the step instructions.
  • %InstructionsPlain% - the step instructions without any styling.
  • %ImagePosition% - the value of the 'step image position' template variable.
  • %StepNumber% - the indexed step number. Steps are only indexed if the step has a title.
  • %Indexed% - 'true' if the step has a title. 'false' if not.
  • %Index% - the actual step number, regardless of whether or not the step has a title.
  • %IndexZeroBased% - same as %Index% but starts counting at 0 rather than 1.

The Lesson Description Section

The Lesson Description Section

Applies to: lesson, table of contents

Use this section to format how the lesson description will be displayed. This section is not processed if the lesson has no description.

Variables Available in this Section

  • %LessonDescription% - the lesson description.
  • %LessonDescriptionPlain% - the lesson description without any styling.

The Navigation Section

The Navigation Section

Applies to: lesson

This section will be processed for each step in the lesson that is indexed (has a title). Use it to create step navigation within the HTML page.

Variables Available in this Section

  • %Title% - the step title.
  • %StepNumber% - the indexed step number. Steps are only indexed if the step has a title.
  • %Index% - the actual step number, regardless of whether or not the step has a title.
  • %IndexZeroBased% - same as %Index% but starts counting at 0 rather than 1.

The Lesson Link:Previous Section

The Lesson Link:Previous Section

Applies to: lesson in a manual

This section is available if a lesson is being exported as part of a manual. Use it to create a link to the previous lesson in the manual.

Variables Available in this Section

  • %PreviousLessonLink% - the link to the previous lesson in the manual.
  • %PreviousLessonTitle% - the title of the previous lesson in the manual.
  • %TableOfContentsLink% - the link to the manual table of contents.

The Lesson Link:Next Section

The Lesson Link:Next Section

Applies to: lesson in a manual

This section is available if a lesson is being exported as part of a manual. Use it to create a link to the next lesson in the manual.

Variables Available in this Section

  • %NextLessonLink% - the link to the next lesson in the manual.
  • %NextLessonTitle% - the title of the next lesson in the manual.
  • %TableOfContentsLink% - the link to the manual table of contents.

The Lesson Section

The Lesson Section

Applies to: table of contents

Use this section to format each lesson that will appear in the Lessons section.

Variables Available in this Section

  • %LessonTitle% - the lesson title.
  • %LessonLink% - the link to the lesson.
  • %LessonDescription% - the lesson description.
  • %LESSON_DESCRIPTION% - the value of the Lesson Description section.

The Lessons Section

The Lessons Section

Applies to: table of contents

Use this section to format how the lessons in a section will be formatted.

Variables Available in this Section

  • %LESSON% - the value of the Lesson section.

The Section Section

The Section Section

Applies to: table of contents

Use this section to format how the lessons in a section will be formatted.

Variables Available in this Section

  • %SectionTitle% - the section title.
  • %LESSONS% - the value of the Lessons section.

The Content Section

The Content Section

Applies to: lesson, lesson in a manual, table of contents

This section is where you bring all of the other sections together to form the main document.

Variables Available in this Section (Lesson)

  • %FontFamily% - the value of the font family template property.
  • %FontFamilyFonts% - outputs the full list of font families for the %FontFamily%. Can be used directly in a CSS style.
  • %LessonTitle% - the name of the lesson.
  • %LessonTags% - a comma delimited list of tags assigned to the lesson.
  • %LESSON_DESCRIPTION% - the value of the Lesson Description section.
  • %LESSON_STEPS% - the combined value of the Step section for all steps.
  • %NAVIGATION% - the value of the Navigation section.

Additional Variables Available for Lessons in a Manual

  • %LESSON_LINK:PREVIOUS% - the value of the Lesson Link:Previous section.
  • %LESSON_LINK:NEXT% - the value of the Lesson Link:Next section.
  • %TableOfContentsLink% - the link to the manual table of contents.
  • %ManualTitle% - the name of the manual.
  • %ChapterTitle% - the name of the chapter the lesson is in.
  • %LessonNumber% - the lesson number within the manual.
  • %TotalLessons% - the total number of lessons in the manual.
  • %ChapterLessonNumber% - the number of the lesson within the chapter.

Variables Available in this Section (Table of Contents)

  • %FontFamily% - the value of the font family template property.
  • %FontFamilyFonts% - outputs the full list of font families for the %FontFamily%. Can be used directly in a CSS style.
  • %ManualTitle% - the name of the manual.
  • %SECTIONS% - the value of the Sections section.

8 Comments

Tony Palombo

Is it possible to modify a lesson HTML template to include the table of contents for the entire manual?

Trevor DeVore

Not currently.

Kate

Is it possible to modify a manual and lesson HTML templates to include steps into the table of contents?

Trevor DeVore

@Kate It is not. The table of contents can only list chapters and lessons.

David

I would like to use higher level variables in iterating sections.

i.e.
I want to access the following varialbes from within the IMAGE section
%LessonTitle% - the step title.
%WebSafeLessonTitle% - a cleansed version of the step title that is web safe.

Ben

Great, I'm really glad I finally managed to import my lessons from ScreenSteps to InDesign.

Everything works perfectly, except if there is an accent in the title of a lesson. Then all the links for the images are messed up in the xml code AND in the folder.
Either the "é" are removed, or changed for a weird character or they're just here !

Since it's random there is no way to sort it out with a find/change.

Any idea or suggestion ?
Should I post my XML code here ?

Trevor DeVore

@Ben - you should send the XML and an example file that fails to support@bluemangolearning.com.

Ben

Thank you for your quick reply Trevor.
After playing with the code and doing some tests, I found a solution.

I post my results here if they can be helpful for people who would like to import XML into InDesign :

Settings for configuration has to be :
...
web safe= true
text style= xml
text encoding= utf8
...
Then for InDesign to recognize the path for the images, it needs to be changed to :

Thanks again

Add your comment

E-Mail me when someone replies to this comment