User-defined JavaScript in the visitor-facing chat of yalst

External custom JavaScript can be injected into the chat application by use of yalst Themes ( .ytf files) and will execute in the same context as the application itself.

This document describes the programming interface for the chat application aka the Theme Api. The Theme Api is organized in JavaScript AMD modules which should be accessed by calling the require method of the RequireJS library. RequireJS is available in the global context since it is used for the chat application anyway.

The Custom Api Module

is the chat programming interface dedicated for custom JavaScript. It is provided as the module module:themeApi

The Server Ajax Module

is a JavaScript api in the web browser for the yalst web service for managing the chat. It has several uses e.g. to determine if the chat service is online, offline or busy (See module:api.hello).

This api is used by the web application itself. However, it can be accessed by third party JavaScript as documented here module:api.

Tips & Tricks

• define a global function named themeApiReady which will be invoked by the JavaScript loader as soon as the API becomes available for your yalst theme.

• external scripts can assume that jQuery is present in $.

• all symbols of the Ramda functional library are made global (Get a list by running R.keysIn(R))

• do not register handlers for the window's beforeunload or unload events, or you'll loose Back-Forward Caching and thus increase load times on page navigation. Instead use the pageshow and pagehide events as described there.

  for example:

$(window).on("pagehide.my_external_script", function(evt)
	{
		if (evt.originalEvent && (evt.originalEvent instanceof window.PageTransitionEvent))
		{
			if (evt.originalEvent.persisted === true)
			{
				console.log("App is suspended. DOM will be cached.");
			}
		}
	}
);

• always use namespaced events to avoid conflicts with the application.

for example:

$(window).on("orientationchange.my_external_script", function(evt)
	{
		console.log("The device is now" + evt.orientation + " aligned.");
	}
);
//...
$(window).off("orientationchange.my_external_script");

History

Version 1.1 (November 2015)

• added receivedMessage event

Version 1.0 (Januar 2015)

• initial version