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.
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.
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:-
This tells Sailwave to replace that line with libraries.txt followed by the selected scripts.
This explains the ungainly content of libraries.txt in tems of <script> and </script> but it has to be like that to keeping old templates and effects working.
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
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.
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 firstname.lastname@example.org. 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 email@example.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.
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.