QWiPS Javascript Library, v2

Functions reference

qwips.suspend()


QWiPS Javascript Library will try to parse the page after it has finished loading.

Unless qwips.suspend() is called during initialization, the following will happen:

To prevent this behavior, call qwips.suspend() in the body of the QWiPS script tag:

<script type="text/javascript" src="http://qwips.com/api/js/2">
	qwips.suspend(); //don't scan the DOM for QWiP links and QWiPS widgets
</script>

qwips.options(object)


This function sets global default options for QWiPS Javascript Library. See the Options reference page for a list of available options.

qwips.options({
	defaultPlayersType:'inline',
	inlinePlayerTransformsInto:'full'
});

qwips.parseWidgets(elem='body')


Scans elem and:

  • converts text links to QWiPs (http://qwips.com/0a1b2c) into Spot Players
  • converts <a> elements with a href attribute pointing to QWiPs (http://qwips.com/0a1b2c) into Spot Players
  • converts <div> elements with a qwips:qwip="0a1b2c" attribute into Spot Players
  • converts <div> elements with qwips:widget="spot" and qwips:qwip="0a1b2c" attributes into Spot Players
  • converts <div> elements with qwips:widget="compact" and qwips:qwip="0a1b2c" attributes into Compact Players
  • converts <div> elements with qwips:widget="normal" and qwips:qwip="0a1b2c" attributes into Normal Players
  • converts <div> elements with qwips:widget="full" and qwips:qwip="0a1b2c" attributes into Full Players
  • converts <div> elements with qwips:widget="myqwips" and qwips:myqwipsusername="username" attributes into My QWiPs Widgets
  • converts <div> elements with qwips:widget="aggregator" and qwips:aggregatorusername="username" attributes into Aggregator Widgets
  • converts <div> elements with a qwips:widget="composer" attribute into Composer Widgets

Note, that elements with a qwips:skip="1" attribute will not be processed.

qwips.attachButtons(elem='body')


Scans elem and:

  • attaches a Companion ("Record QWiP" buttons) to every <textarea> that does not have a qwips:skip="1" attribute.

qwips.linkUrl([url])


This function allows you to change the URL that will be saved along with QWiPs recorded on the current page.

When a QWiP is recorded, it remembers the URL of the page it was recorded on. This URL is used for the Share button and for redirecting the user from http://qwips.com/0a1b2c to the original page (according to publisher settings).

When the user hits http://qwips.com/0a1b2c, the following happens:
  • if redirection is not enabled for the domain (according to publisher settings), the user is shown a default QWiP page
  • if redirection is enabled and QWiP's URL does not contain {QWIPTOKEN}, the browser is redirected to $ORIGINAL_URL/#from_qwip=0a1b2c
  • if redirection is enabled and QWiP's URL contains {QWIPTOKEN}, {QWIP_TOKEN} is replaced by the QWiP's token, and the browser is redirected to the resulting URL

For example, your page URL is http://example.com, but you want all QWiPS to rather use http://test.com:

//all QWiPs will now be saved as if they were recorded on http://test.com
//http://qwips.com/0a1b2c will redirect to http://test.com/#from_qwip=0a1b2c
qwips.linkUrl('http://test.com');
//all QWiPs will now be saved as if they were recorded on http://test.com
//http://qwips.com/0a1b2c will redirect to
//http://test.com/?referenced-qwip=0a1b2c
qwips.linkUrl('http://test.com/?referenced-qwip={QWIPTOKEN}');

You can use qwips.getUrl() to find out what the currently used URL is.

You can use qwips.fromQwip() to find out what QWiP the user was redirected from.

Call qwips.linkUrl(undefined) to revert to the default URL.

qwips.getUrl()


Returns the URL that will be saved along with all QWiPs recorded on the current page. See also: qwips.linkUrl()

qwips.fromQwip()


When the user hits http://qwips.com/0a1b2c and is redirected to the page where QWiP was recorded, our server will append QWiP's token to the url. This function returns the token.

//Window URL is http://example.com/#from_qwip=000aaa
console.log(qwips.fromQwip()); //will print 000aaa
If you called qwips.linkUrl() with an URL containing {QWIPTOKEN}, you must also specify a correct RegEx to qwips.options({referencedQwipTokenRegex:/.../}) option for this function to work correctly.

By default, qwips.fromQwip() uses this RegEx to parse the referenced QWiP token:
qwips.options({
referencedQwipTokenRegex : /(?:#from_qwip=)(\d[a-z0-9]{5,9})/i
});
If you want to use URLs like http://example.com/?referenced-qwip=0a1b2c instead, you need to set the referencedQwipTokenRegex option to the RegEx similar to the following example:
qwips.linkUrl('http://test.com/?referenced-qwip={QWIPTOKEN}');
qwips.options({
referencedQwipTokenRegex : /(?:[\?|&]referenced-qwip=)(\d[a-z0-9]{5,9})/i
});

qwips.reinit([interval])


If the contents of your page have changed (next page was loaded with AJAX), new elements will not be processed by QWiPS Javascript Library (no automatic Players and Companions). If you want QWiPS Javascript Library to periodically re-scan the page DOM for new supported elements — call this function, specifying the necessary interval (in milliseconds).

//Check DOM for new supported elements
qwips.reinit(); //Re-check DOM immediately (once)
qwips.reinit(0); //Re-check DOM periodically with default interval (1500ms)
qwips.reinit(3000); //Re-check DOM every 3000ms

This function has no effect if qwips.suspend() has been called previously.

Call qwips.stopReinit() to cancel the DOM checks.

qwips.stopReinit()


Prevents QWiPS Javascript Library from doing any further periodical DOM checking for supported elements. See also: qwips.reinit()

qwips.bind(eventType, callback)


Bind a callback to specified event(s). This function uses jQuery's .bind() syntax (in fact, it relies on jQuery's .bind() function).

See the Events Reference page for details.

qwips.unbind(eventType [, callback])


Unbind a callback from specified event(s). This function uses jQuery's .unbind() syntax (in fact, it relies on jQuery's .unbind() function).

See the Events Reference page for details.