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.