NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Skins and JavaScript

Skin authors should load twiki.js from pub/TWikiJavascripts/twiki.js to benefit from a number of utility functions: retrieving class elements, WikiWord checking and creation, cookie management (reading and writing values), and so on.

JavaScript onload handler

<script type="text/javascript">
//<![CDATA[
   addLoadEvent(myFunc);
   function myFunc () {
      // initializing code
   }
//]]>
</script>

-- Contributors: ArthurClemens

Comments & Questions about this Supplemental Document Topic

Are the contents/API of twiki.js documented or even guaranteed? TWikiJavascripts would be a preferred location for docs, but is pretty uninformative right now .

-- HaraldJoerg - 19 Jul 2006

Most of the code itself is documented with javadoc comments. But the API may change in next TWiki releases, for instance with a consistent namespace for all functions.

-- ArthurClemens - 19 Jul 2006

Put together: I should load it in my skin, but the API may change? Fat chance. Skins are supposed to survive TWiki upgrades, so I need API stability to really rely on a library.

-- HaraldJoerg - 19 Jul 2006

When we change twiki.js plugin authors will be consulted.

-- ArthurClemens - 20 Jul 2006

Harald is right here.

If we start recommending that skin authors uses certain calls in twiki.js then we need to have as strict an API as we have in the perl code.

• This means API is documented
• This means that no API functions are deprecated as the general rule. Exceptions must be rare and with years of warning before expiry.

If we cannot offer this kind of API stability then I recommend skin authors to write their own code and not rely on anything because the history of consulting plugin authors in the TWiki project is not a success story.

Some developers have the idea that when the API is changed it is the plugin and skin authors that are affected. It is not. It is our users that loose because half the skins and plugins are abandonned and the users have no chance to know that what they installed is no longer maintained or badly maintained. They upgrade TWiki and discover that half their plugin and their tailored skin no longer works.

If twiki.js is to be recommended for skin authors, you need to write an API doc and document which functions are regarded stable API. And then make sure not to change it.

-- KennethLavrsen - 04 Aug 2006

Very good remark Kenneth.

-- PeterThoeny - 05 Aug 2006

In that case I recommend we first consolidate twiki.js and document the API, and then freeze it. Bugs:Item2643

-- ArthurClemens - 05 Aug 2006

We're trying to src javascript libs (e.g. the line <script src="http://zx3vp9agry5d65mr.roads-uae.org/timeline/api/timeline-api.js" type="text/javascript"> </script>), and get the error: "Error Failed to derive URL prefix for Timeline API code files"

The reason we want to use this js lib is because we can't get the Timeline Plug-in to work, because, we think, the XML formatter isn't working properly (* Set SKIN = xml)...then again, I have no idea if an XML skin is available by default, or if this is something that needs to be added or developed separately...mainly because the plug-in isn't documented. Help would be appreciated...

-- AndyMauro - 07 Aug 2006

Hilariously enough, I just got this "Failed to derive..." error on twiki.org while submitting this comment. Actually, not all that funny...not being able to write js in the twiki is a huge drawback

-- AndyMauro - 07 Aug 2006

This section here is for feedback on the documentation. Please ask support questions in the Support web, or in the relevant Plugin Dev topic.

-- PeterThoeny - 07 Aug 2006

What about having the same onunload using an addOnUnloadEvent function?

-- StephaneLenclud - 25 Sep 2006

Initiative for refactoring of twiki.js in TWikiJavaScriptRefactoring.

-- ArthurClemens - 27 Oct 2006