How do I add my own publishing templates, styles and effects?

Last edit 28th February 2016 by Jon

This post only applies to setting up your new template or style.  Other publishing FAQs detail how the content can be customised.

Sailwave templates

If you have not done so already, create a folder for your modified templates.  For example you could create a folder called Sailwave in My Documents and then add another folder called Templates within that.

Copy the template you wish to modify from the installation templates folder to your new folder.  The Sailwave templates all reference header.txt and footer.txt, so you’ll need to also copy these (and subsequently edit as needed) – or – paste the content of them into your new template where they are referenced.

Depending on your operating system, your installation templates folder will be one of:-

C:\Program Files\Sailwave\templates
C:\Program Files (x86)\Sailwave\templates
C:\ProgramData\Sailwave\templates

Open Sailwave.  Open the global options (setup+global options menu).  Click the Folders tab and point the My template files field to your new folder.  You can either type it in or use the little wave icon to select it.  Close Sailwave.

When there is a template of the same file name in the default folder and your own folder, Sailwave uses your version.  So this template will now be used.  If your template has a different file name to any of the factory templates, it is added to the publishing list instead of replacing an existing item in the publishing list.

Templates contain HTML and callbacks to Sailwave using backquotes `.  For example:-

<h1>`venue.name`</h1>

You can control how the template looks in the Sailwave publishing menu using these callbacks:-

template.setmenurank
template.setmenutext
template.setmenumsg
template.setdisabled
template.end

For example:-

`template.setmenurank(100)`
`template.setmenutext('&Results...')`
`template.setmenumsg('Publish results')`
`template.setdisabled(0)`
`template.end()`

setmenurank controls where the template is displayed in the publishing menu.  Have a look at the factory templates to see what values they use and choose your values appropriately.  The factory templates use large gaps and  start at 100, so you can easily intersperse your own templates.  The lower the value the more towards the top of the menu.

setmenutext specifies the menu text.  Use “&” before the desired keyboard hotkey for access the menu with the keyboard.

setmenumsg is the help text shown in the Sailwave status bar when hovering over the menu item.

setdisabled  should have value a value of 0 to display the template in the menu and 1 to hide it.  You can use this technique to hide factory menus.  Create a custom menu with the same file name as a factory template, then disable it using this option.

end just tells Sailwave that no more template.* callsbacks are in the template.  This is used when constructing the publishing menu – i.e. Sailwave does not need to read the whole file – just up to template.end.

The following callbacks to global variables can be used.

Current view font characteristics.  In this way you can control the published font based on what you are looking at:-

view.fontface
view.fontsize
view.fontcolour

Fields from Setup+SeriesProperties:-

venue.burgee
venue.web
venue.email
venue.name
event.burgee
event.web
event.email
event.name
event.id

The current year:-

date.year

For example:-

<h2>`event.name` at `venue.name` `date.year`</h2>

The current source file name:-

filename

For example:-

<meta name="filename" content="`filename`">

You can reference an external file using the html.include template.  For example:-

`html.include('header.txt')`

The factory templates use this technique to load common template fragments.

The following user interface callbacks can be used.  See the factory templates for examples of their use:-

html.resultswiz
html.natstandingswiz
html.natplacingswiz
html.natresultswiz
html.natleaderboardwiz
html.flightwiz
html.competitorwiz
html.populatedonoffwiz
html.onoffwiz
html.retirementwiz
html.altpenaltywiz
html.paperwiz
html.teamwiz

If you want to allow the user to select a CSS style when publishing use html.style.  To allow the user to select a javascript ‘effect’ use html.javascript.  If these are not present the corresponding options will not be available to the user when publishing.  For example all the standard factory templates include a file called header.txt which has this snippet of HTML to allow the user to select both a CSS style and a javascript effect:-

<style type="text/css">
`html.style()`
</style>
<script type="text/javascript">
`html.javascript()`
</script>

Sailwave styles

Proceed as for templates above but using the appropriate folder and fields.  Your style either replaces the factory one in the drop down list when publishing or is added to the list if it has a file name different to any of the factory styles.

Styles can include the callbacks described above but only view.* make any real sense in this context.

To find out what classes Sailwave applies to elements, publish a series with everything included (summary tables race tables with all columns, prizes, codes, notes etc) and look at the source.

Sailwave effects

Sailwave effects are javascript files that and in-lined into the resulting HTML files, like styles.  As executable code they offer endless customisation opportunities.  We recommend you study the existing effects before writing one.

Proceed as for templates above but using the appropriate folder and fields.  Your effect either replaces the factory one in the drop down list when publishing or is added to the list if it has a file name different to any of the factory effects.

Effects can include the callbacks described above.

 

Leave a Reply