Last edit 1st June 2018 by Jon

Requires Sailwave version 2.19.5 or later.

Firstly you need to create a folder to contain your effects and tell Sailwave about it.  Read this Publishing FAQ for details.  I recommend you read the whole of this FAQ, not just the effects section, as templates and styles are highly relevant.

When creating a list of effects, Sailwave will scan your folder and then extend the list with the default Sailwave effects unless a default effect has the same name as one of yours.  i.e. your effects are overrides in the case of a file name clash.

While an effect is just a Javascript script, we’ve used the word effect to emphasise that they are related to publishing, since we may well one day add generic scripting to Sailwave.

Check that Sailwave is looking at your effect folder by copying one of the default effects (<Sailwave install folder>\javascript) to your folder and changing its name.  Start Sailwave and make sure the new file is included in the effects list when publishing.

Edit the new effect with a text editor and change the header lines (// *) appropriately.  The layout here is arbitrary but “name=” and “dependencies=” are mentioned on the effect library page, so make sure your header has at least something containing those strings.  Nothing parses this header info, it’s purely informational and just needs be valid Javascript comment syntax.

If you look at the source of the published page when using an effect you’ll see that it has been inlined into the page.  In this way, any user can use an effect without having to upload it to a server.

You can of course just create a custom publishing template and reference any Javascript files you like – use effects if you would like to share your code with the Sailwave community.

Placement

Sailwave publishing templates specify where the scripts will be inlined.  See this header.txt in the/your template folder for an example.  Look for the line:-

`html.javascript()`

This tells Sailwave to replace that line with libraries.txt followed by the selected scripts.

This explains the ungainly content of libraries.txt in terms of <script> and </script> but it has to be like that to keeping old templates and effects working.

Callbacks

Scripts can use the backquote callback syntax to include the same Sailwave data that can be included in templates; for example:-

var venueName = '`venue.name`';

jQuery and other libraries

When you look at the source you’ll also see that jQuery is loaded by default.  What’s actually happening is that Sailwave is inlining the content of javascript\libraries.txt which contains the reference to jQuery.

If you need to include other libraries, copy libraries.txt to your effects folder and edit as required.  Your entry in the effects library should note the changes needed to so that other users can do likewise.  Alternatively (and better from a casual users’ perspective) your effect could dynamically load the libraries required if not already present.

Helper functions

libraries.txt also includes some helper functions listed below and of course you can extend them for your own use.

Helper function: swGetURLArgs()

This returns an object containing all the url parameters.  For example if a URL contains &x=1.5 somewhere in the URL, it can be extracted using:-

var args = swGetURLArgs();
var x    = args.x;          // or args['x']

args.x will be undefined if not present.  Note that args.x will be a string and you’ll need to use parseInt() and parseFloat() to convert into numbers if required.  For example:-

var args = swGetURLArgs();
var x    = parseFloat(args.x);

See Colin J’s scroller effect for another simple example.

Effect library entry

When you have tested your effect, write the text of an effect library entry and send it to jon@sailwave.com.  You can include the code in the text or link to a file on the web.  We can upload it to the Sailwave server if you like and you can link to it from there, but again email jon@sailwave.com to arrange.

Send us updates as required.  If you write many effects we can give you an account on the website to maintain your own entries.

You can announce your effect on the Sailwave facebook page and Sailwave User Group or we can do it for you.

Please note the text on the effect library page that says if an author has included their contact details in the entry or the code they are happy for users to contact them.

Once you have your effect entry it may be useful to add a link to it from the effect itself – example.

Last Edited 29st April 2020 by Jon

This post only applies to Sailwave versions 2.6.2 and later.

Sailwave results contain four tables: summary, race, code and prize.  By default, Sailwave does not add “class=classname” attributes to the th and td elements of these tables.  It does use colgroup and col but CSS is limited in that you can only perform these changes to columns as a whole using CSS:-

• Set the background color
• Set the width
• Set a border
• Control visibility

You can add classes to td and th elements yourself by creating your own result template and specifying class names using the Sailwave class.set callback function.  For example:-

`class.set("prize.col.competitor.td", "prize-comp")`

All the td elements in the competitor column of the prize table will then have the prize-comp class applied.  For example, an actual td element may look like this:-

<td class="prize-comp">Colin Jenkins</td>

These class.set calls must be placed before the call to html.resultswiz.

The first parameter to class.set identifies the table and its column with a suffix of .td representing the table cells and .th representing the header cells.  The second parameter is your class name or names separated by spaces – the definition(s) of which you need to add to any of your modified or custom styles.  For example:-

.prize-comp {font-weight: bold;}

The set of valid columns for the first parameter can be found by looking in the factory version of Results.htm and identifying the string.set calls containing:-

*.col.*

As of 22/11/2012 these are (note this help may lag the content of Results.htm) :-

prize.col.rank
prize.col.category
prize.col.competitor

codes.col.description
codes.col.code
codes.col.points

race.col.start
race.col.finish
race.col.elapsed
race.col.laps
race.col.corrected
race.col.bce
race.col.bcr
race.col.speed
race.col.place
race.col.points

You can target columns in the summary and race tables representing competitor field names using:-

summary.col.fieldname
race.col.fieldname

You can target the race columns of the summary table with:-

summary.col.race

Examples:-

`class.set("race.col.points.th","myclass1")`
`class.set("summary.col.sailno.td","myclass2 myclass3")`
`class.set("summary.col.race.th","myclass4")`

By convention, the first parameter to class.set is specified in lower case but it is not essential.  The second parameter must not contain a speech quote ” or backquote ` character.

 

Last edit 1st June 2018 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

The recommended location for the modified templates is:- Users\Public\Documents\Sailwave\Templates this is configured in the Setup – Global options – Folders

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:\Users\Public\Documents\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.  In later versions, this is pre-configured for you.  You can either type it in or use the little wave icon to select it.  Close Sailwave.

On Italian PC’s the Italian versions of the Templates are pre-installed in C:\Users\Public\Documents\Sailwave\Templates\ITA

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.* callbacks 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.