Installing Web Sketchpad

Version 4.8.0

Character Encoding

Pages containing Web Sketches must use a utf-8 character encoding:

Configuration Object

WSP supports configuration using an optional javascript object called GSPConfig. If used at all, this object must be set before any Web Sketchpad scripts are loaded. For example, you might insert a SCRIPT tag in the HEAD of your html as follows:

<script> GSPConfig = { myConfigurationKey: myConfigurationValue } </script>

Including Scripts

In order to use WSP in HTML you must include the correct CSS and JavaScript libraries.

jQuery

We assume jQuery

wsp-min.js

The main Web Sketchpad library (or wsp.js - the debug version)

wsp-runner.js

The Web Sketchpad jQuery utility library

Automatic Loading (without Javascript)

WSP will automatically detect DOM elements with a "sketch_canvas" class, and attempt to load the Sketchpad documents they point to. The most common way to specify a document is to use the data-url attribute, as in the example below. There are also other data-attributes used to specify the source of a document.

        <div class="sketch_canvas" data-url="../examples/sketches/Triangle_export.json"> </div>
    

Loading with jQuery (uses javascript)

Web Sketchpad's WSPRunner script exposes a "WSP" jQuery plugin. The general form of a call to the library is

WSP("loadSketch", options)

Loads a Sketchpad document into to matched DOM elements:

Document Source

The source of the document can be specified variously, either in a data attribute of the DOM element, or in the options hash. Options specified in options override those specified in the DOM. If more than one way of loading a document is specified, the one attempted is unspecified.

data-sourceDocument

A Sketchpad document, either as a string or JSON object.

data-url

The URL of a JSON Sketchpad document.

data-var

A variable in the global namespace of a Sketchpad document. The value should be a Sketchpad document, either as a string or JSON object.

If the variable does not exist, the loader will create a filename by appending "-json.js" to the data-var value and attempt to load and run a script with that filename. Provided that the script is loaded and creates the global variable corresponding to its filename and containing a Sketchpad document, the document is loaded.The data-var value may have a prepended path, which is used in the script filename but not in the variable name. (For example, if the data-var value is "./sketches/my_sketch", the loader tries to load and run "my_sketch-json.js" from the "sketches" directory, and the script must create "my_sketch" as a global variable.)

data-clone

The DOM id of a DOM element containing a Sketchpad document. The document will start as a copy of the cloned document.

data-promise

A jQuery promise object which resolves to a Sketchpad document: a string or JSON object. The resolved document will be used as the document's source.

Optional Parameters

autoStart

A boolean specifying whether the sketch should start after load. Default: true

sketchOptions

Various options effecting the the behavior of the sketch.

sizeParentToContent

Apply CSS to size parental DOM node. This amounts to styling generic display: block DIV's to display:inline-block, so that it sizes to the sketch content size. Turn this off if you are doing explicit layout of the node yourself. Default: true when parent node has css class "wsp-responsiveSizing", false otherwise.

responsiveSizing

Apply media query logic to change the form factor of the sketch based on window size. We get smaller on tablets and mobile. Default: Default: true when parent node has css class "wsp-responsiveSizing", false otherwise.

locale

Localize certain aspects of dynamically created text. Value should be a BPC 47 language tag for use with the JavaScript Intl API. Note: Currently only the decimal point separator is supported. Default behavior is to sniff the browser's behavior to determine the decimal point separator.

onError(arg)

A callback called when an error occurs. Inside the callback, this is a jQuery collection containing the DOM element into which Web Sketchpad tried to load the Sketchpad document. The callback is called with one argument arg, whose value varies depending on the error.

The following error cases are defined:

Malformed JSON

Web Sketchpad was asked to load a Sketchpad document from an invalid JSON string. arg is the invalid JSON string.

Unrecognized Sketch Datatype

Web Sketchpad was asked to load a Sketchpad document from something other than a string or an object. arg is the invalid value.

AJAX Error

An AJAX call failed. arg is the AJAX url.

Promise rejected

A jQuery promise was rejected. arg is the value with which the promise was rejected.

onLoad(metadata)

A callback called after document loads. metadata is the Sketchpad document metadata field. The default implementation sets the size of the DOM element to match the Sketchpad document.

onReady(sketch, metadata)

A callback called when the sketch is loaded, and just before it's ready to start. sketch is a sketch that is about to start. metadata is the sketch metadata field.

Once the document is ready, it will be available in the DOM element's data-document attribute:

jQuery(selector).data("document")

Further interaction with the sketch can then be done using the Document and the sQuery APIs.

Running Multiple Versions of Web Sketchpad on a page

Web Sketchpad supports loading different sketches into a single web page, using different versions of the Web Sketchpad software. To use this feature, simply include two or more versions of wsp.js or wsp-min.js. The sketch runner will match the version number of each sketch with the version number of the most appropriate version of wsp.js. Note that versions released before the Q4 2014 Release (December 2014) are not supported in this mode.

If a suitable version of the library is not found, the sketch runner will attempt to load one based on the major version number encoded in the web sketch document JSON. If the major version is N, it will attempt to load "js/wsp-compat-N.js". This can be overridden by setting GSPConfig.compatibilityVersionPath to be a function(majorVersion) which takes the major version (as a string) and returns a URI for the desired library.