Adding custom JavaScript

It is possible to add application-specific JavaScript to a WComponents application. Before doing so though one ought consider carefully whether:

1. the functionality one is trying to implement is already available in the theme; and
2. if not then should it be added to the theme?

• Adding a cacheable JavaScript file
  • Using WApplication
  • Using Headers
• Adding inline JavaScript
  • Using WText
  • Using WTemplate
• Related topics

Adding a cacheable JavaScript file

The most efficient way to add JavaScript is usually using a cacheable script file.

Using WApplication

WApplication has these methods which may be used to add a script element to the page head element:

• addJsUrl(String url); and
• addJsFile(String fileName).

Each of these methods has the same net effect: a HTML script element will be added to the head with the src set to the url or file resource. The script element is placed after the inclusion of WComponents scripts and requirejs configuration and inclusion therefore you should be able to rely on the presence of requirejs and if you build your script as an AMD module you will be able to use WComponents modules.

// Get the WApplication from the current object'
WApplication app = WebUtilities.getAncestorOfClass(WApplication.class, this);

// Then use this WApplication to add JS from a resource.
app.addJsFile("/path/to/resource/my_javascript_file.js");
// Adding from a URL is similar. Use '//'' to avoid defining the protocol.
app.addJsUrl("//example.com/path/to/static_js_file.js");

Using Headers

This technique is being phased out in favour of that outlined above but is available in WComponents 1.0.2 and before. The methods for setting and getting headlines shown in the example are all deprecated.

A JavaScript file can be added to an application using com.github.bordertech.wcomponents.Headers.addUniqueHeadLine(String type, String aLine) or com.github.bordertech.wcomponents.Headers.addUniqueHeadLine(String aLine).

One possible method of doing this could be by using WContent and an internal resource:

private final WContent js = new WContent();

// ...

// Add a cache key to js so that it can be cached. This cache key
// can then be changed if there is a need to update the JavaScript.
css.setCacheKey("my.custom.js" + version);

// The resource must be added to the output tree event though it is
// not included in the XML output.
add(js);

// ...

// At some point the js resource must be set up. This could be the
// first time the object to which js was 'added' is painted in
// preparePaintComponent
@Override
protected void preparePaintComponent(final Request request) {
    super.preparePaintComponent(request);

    // ...

    if (!isInitialised()) {

        // ...

       js.setContentAccess(new InternalResource(
            "/path/to/resource/my_custom_script.js",
            "my_custom_script.js"));
        setInitialised(true);
    }

    // ...

    // Finally use addUniqueHeadLine To attach the script
    UIContext uic = UIContextHolder.getCurrent();
    uic.getHeaders().addUniqueHeadLine(
        "<script type='text/javascript' " 
        + "src='" 
        + WebUtilities.encode(js.getUrl()) 
        + "'></script>");
}

Adding inline JavaScript

Using WText

WText may be used to output any HTML element(s) including a script element. You must turn off output escaping (doing this is considered harmful) and you are completely responsible for ensuring your HTML snippet is XML compliant. This includes knowing what to escape or enclosing your script in a CDATA block.

// Let us assume we have a JavaScript snippet we want to include and it is in
// a String MY_SCRIPT which should include the script element opening and
// closing tags and a CDATA wrapper if required.
WText jsText = new WText(MY_SCRIPT);
jsText.setEncodeText(false);
add(jsText);

The script element will be echoed to the output stream (HTML) in the position in which it is added to the component tree.

Using WTemplate

Custom JavaScript may be included in a view by adding it to a WTemplate. The same caveats apply as for using WText.

Related topics

• Adding custom CSS
• Creating a theme
• Lifecycle on client side