What is an HTML template?
The Clarify HTML template system provides a way to export content into a variety of custom formats. The primary use for HTML templates is to create HTML content, but templates can be customized to create any type of content that is text-based. For example, you might create a custom template to export to XML, Markdown, MediaWiki or other formats.
Clarify uses the PHP engine to process the template files. Clarify converts manuals and articles into PHP objects that can be accessed from within template scripts.
An HTML template is a folder which contains the necessary template files. A template folder is comprised of the following items:
- config.xml: The configuration file provides instructions about how Clarify should prepare your content prior to passing it off to the PHP engine.
- ./Content folder: The Content folder contains all of the files necessary to export a template. At a minimum it will contain an article folder. If you have supporting PHP files that are used in your HTML template then you would place them in the Content folder.
- ./Content/article folder: The article folder contains all of the files that will be exported when exporting an article.
The config.xml file can set any of the following properties:
- article_structure: controls the nesting of steps in the PHP object. Default value is hierarchal which nests substeps under steps. Set to flat to get a non-hierarchal list of steps with no nesting.
- hi_res_images: specifies whether or not to export images taken on high-resolution monitors with full resolution. The default behavior is true in which case all image data is exported but the image dimensions in the PHP object are appropriate for the size that the image should be displayed at. For example, a 600x600 retina image should be displayed at 300x300. Set in false to discard the high-resolution image data.
- image_names: format used to name images. random or step_title. random can be useful if you need to ensure that you never end up with duplicate image names when importing into a 3rd party system.
max_image_dimensions: The maximum image dimensions to use for width and height. Entries are a comma delimited list of integers. You can provide just the width, width and height, or just height. Examples:
- text_format: xhtml or runs. xhtml is appropriate for creating HTML content and you won't need to do anything to the text that Clarify puts into the PHP objects. runs formats text in an array that separates the actual text from the formatting applied to the text. This allows you to more easily massage the text into other formats (e.g. markdown).
- web_safe: true or false.
- word_separator: character used to separate words in names.
The default config.xml file contains the following XML:
<?xml version="1.0" encoding="utf-8" ?> <properties version="1"> <web_safe>true</web_safe> <text_format>xhtml</text_format> <word_separator>-</word_separator> <article_structure>hierarchal</article_structure> <hi_res_images>true</hi_res_images> </properties>
Here is an example using image_names and max_image_dimensions.
<?xml version="1.0" encoding="utf-8" ?> <properties version="1"> <web_safe>true</web_safe> <text_format>runs</text_format> <word_separator>-</word_separator> <article_structure>hierarchal</article_structure> <hi_res_images>true</hi_res_images> <image_names>random</image_names> <max_image_dimensions>600,</max_image_dimensions> </properties>
The article folder is where you put all of the files that will be exported when exporting an article. There are two files that are required:
- @article: This is the template file that ScreenSteps will process with PHP. The filename must start with @article. The extension you add is up to you.
- @images: This is a placeholder file. ScreenSteps will store all article images in the same location as this file. Notice that in this example the file is in an @article folder. The HTML exporter will replace @article with the name of the article when exporting.
Any other files and folders in the article folder will be copied into the folder the article is being exported to.