@edmdesigner/plugin-core v1.0.14

EDMdesigner Plugin Core

1. basics

1.1. what is the EDMdesigner Plugin Core library and what are the Plugin Connectors?

EDMdesigner Plugin Core is a library, made for handling commonly the embedded EDMdesigner services. It provides common core functionalities, in order to implement a Plugin Connector for each of our plugins. These connectors are presenting an easy way to our partners to integrate our plugins into their own websites and use them as included plugins, without unneccessary code repetition.

1.2. independent iframe DOM node as window for plugin instance

Each plugin is displayed in an iframe DOM node placed in the integrator's website (added as a child node of the specified parent element). This way it enables running plugins in an independent environment and with independent style.

Multiple instances can be included into a single website simultaneously by providing each plugin a unique serviceId. Such as iframes are running in different DOM windows and different JavaScript scopes, they can run independently from each other and from the integrator's website.

Styling can be configured when creating a new plugin instance by passing a theme object with appropriate color properties. Custom coloured embedded plugins can be created this way, according to the whole website's design.

1.3. postMessage communication, message restrictions

Every communication between a Plugin Connector and the plugin belonging to it are sent via postMessages. These messages have common restrictions.

Every message data is a JSON encoded object. This object is called 'message'.

1.3.1. fields of message object

A 'message' must contain these properties with appropriate values:

• id: unique message id, to distinguish plugin instances and previous messages which the current message replies to
• type: message type, depending on plugin
• service: plugin name
• serviceId: plugin instance id

There are several cases when certain fields aren't neccessary:

• if the message sent from a plugin to the Plugin Connector, a unique id is only required when the sent message is a reply to a specific received message
• if the message is a first message with DOMReady type, sent from a plugin to the Plugin Connector, the serviceId is unknown for that instance yet, as it is given by the Plugin Connector in the response.

1.3.2. Describing message groups, and clarifying the behavoiur of their callback functions

Callbacks are delegating neccessary information related to postMessages towards the integrator. Sometimes the information consists of data parameters, sometimes the existence of a callback calling is the only but useful information without any parameter. This fact divides the message types into three main groups.

1.3.2.1. Messages sent to the plugin

Messages in this group don't have a callback function, because a postMessage is sent immediately after the integrator calls its triggering operation. Also there is no need to have an ack (verification) from plugin about receiving the message, thanks to the reliable postMessage sending within the local memory between windows.

The integrator can simply assume, that they're sent immediately after calling their triggering operation.

1.3.2.2. Messages sent to the plugin and needed to be replied with corresponding messages - request-reply paired messages

These messages have a mandatory, unique callback for each call of their triggering operation (and thus, for the sending of them). This means that the callback isn't set in the plugin instance creator function's callbacks object (see section 3.1.). It has to be set at the time of calling the triggering operation as a parameter (see section 3.2.4.). The answer belongs to its request uniquely, so different requests of the same type on the same instance have to be handled independently, with unique a callback function (or rather the Plugin Connector has to ensure the possibility of independent handling).

1.3.2.3. Messages sent from the plugin independently on requests - event-related messages

1. The type of event when the Plugin Connector has to notice integrator

These messages have mandatory callbacks given in the instance creator function's callbacks object (see section 3.1.).

2. event messages related to inner functioning

These messages have optional callbacks, the integrator doesn't have to be noticed, but information should be useful (see section 5.2.).

Typically, the DOMReady messages are related to the inner functioning, but sometimes finishing the building of the DOM tree of the plugin is an important thing to know (e.g. in order to show a loading screen to the visitor and hiding it when the plugin finished loading/building).

However, in case of DOMReady, giving a callback function as second parameter of plugin instance's creator function (see section 3.1.2.) is an equivalent way to set the DOMReady callback (that function will be called also when DOMReady received to the Plugin Connector).

1.4. common message types

There are several common message types. Each plugin implements and handles them and their behaviour described below.

1.4.1. DOMReady message sent by the plugin

An instance isn't able to receive postMessages while the browser is building the DOM tree of its iframe window, because the postMessages are catched by an eventListener function of the window. EventListeners work correctly on pages that finished loading. The instance notifies the Plugin Connector about the fact, that it's DOM is finished loading, about it's capability of receiving postMessages by sending DOMReady type postMessage.

These messages don't have other required fields.

The Plugin Connector answers a DOMReady message by an init message containing serviceId (see section 1.4.3). This means also that the still unknown serviceId isn't part of DOMReady message.

1.4.2. getDocumentHeight message received and answer sent by plugin

This type of message is a request-answer message pair in fact. First, getDocumentHeight request is sent to the plugin with a unique message id.

When the plugin receives the request, it determines its own DOM height and sends it as an answer to the getDocumentHeight message of the Plugin Connector.

This feature can be used to align the height of the plugin instance's iframe element to the height of instance's content in the website of the integrator.

1.4.3. init message received by the plugin

This is the answer for a DOMReady message (see section 1.4.1). Contains initialization data for the servie, including theme object and serviceId, which can be determined by the integrator by passing it with the config object of the instance's creator function, and it has "default" as default value.

Multiple plugin instances can be used on a single site. Thus, instances have to know their unique serviceId and include it in every further sent postMessages.

This message has a 'serviceId' required field indicating the unique plugin name (serviceId) of the instance. The 'theme' object (see below) and the 'JWT' are also required fields of these messages. Additional required fields may be depending on the initialized plugin.

The Plugin Connector distinguishes the sender of the DOMReady message by checking the postMessage's event.source.window against the iframe.contentWindow of every stored instance of the specified plugin. Further messages between the instance and the Plugin Connector will be routed by their serviceId property.

The plugin instances can be coloured by the integrator, by providing a theme object to the plugin during the initiation, with a 'theme' typed postMessage. The structure and other details of this object is described in section 2.2.2.

These messages have the 'theme' required field, containing the theme object. The plugin instance sets its colors according to the passed theme.

1.5. structure

The Plugin Core library is a common handler for plugins in order to implement their connectors with proper interface and functioning. This library is published to the npm registry.

1.5.1. plugin connector

Each EDMdesigner plugin implements a connector. Connectors use the Plugin Core library and pass a plugin wrapper to it. The purpose of the plugin wrapper is to provide an integrator-side, plugin specific collection of handler functions based on the required functionalities and used postMessages of the specific plugin.

Plugin connectors are published to the npm registry. The built variant of them are also available in our CDN.

1.5.2. plugin core

Each EDMdesigner plugin core (the plugin code running inside the iframe) implements a postMessage interface for communicating with the integrator-side connector. This is the inner functioning of the plugin. As an integrator, you don't have to deal with it.

1.5.3. basic usage and versioning

You can include the appropriate plugin connector from the npm registry or from our CDN (using the HTML script tag) into your integrator-side code.

Previously released plugin versions are also published, so you can include any specific available version.

2. initialization of a Plugin Connector

First of all, a Plugin Connector has to be initialized by including its source code and calling its creator function.

2.1. include the proper plugin connector

2.1.1. include the connector from CDN or from the integrator's storage

The source code of each connector is hosted on CDN. The built js file can be loaded with a simple 'script' html tag by passing the url of our or the integrator's host as 'src' attribute.

Url of hosted source code: ???

Example:

<script src="???"></script>

Note: it is important to include the plugin connector before executing codes using it.

2.1.2. include the Plugin Connector from the npm registry

First, you have to install the proper connector package:

npm install @edmdesigner/superpreview-connector --save-dev

After that, you should require it in your JavaScript code:

var createPluginConnector = require("@edmdesigner/superpreview-connector");

2.2. calling the creator function of a plugin connector

The creator function has a config object parameter with JWT and theme properties.

2.2.1. JWT property

Integrators need a JWT obtained from EDMdesigner to access our plugins. This key has to be set as the JWT property of config the object.

2.2.2. theme property

As mentioned above, the theme object describes the style (colouring) of the plugin instances. It is mandatory to give a common basic theme, but it can be altered in every single instance (see section 3.1.1).

Details of the theme object:

It has to have a 'theme' property with a given theme name. This enables using default style sets, including non-coloring styling elements too. An other theme uses another color for a specified style attribute in many cases. Thus, the theme also means association between given color denominations and the style attributes of the components in plugin HTML content. Theme can be:

• 'chamaileon'
• 'background'
• 'border'
• 'border-fill'

It has to have a 'colors' property which contains an object, describing colors with these common denominations:

• primary
• secondary
• info
• success
• warning
• error
• white
• black
• lightGray
• mediumGray
• darkGray
• border

2.2.3. example

var theme = {
	theme: "chamaileon",
	colors: {
		primary: "#44c0fc",
		secondary: "#9b9b9b",

		info: "#25aaf2",
		success: "#54c059",
		warning: "#f5a500",
		error: "#ee483b",

		white: "#fff",
		black: "#000",

		lightGray: "#f5f7f8",
		mediumGray: "#c0c1c3",
		darkGray: "#e5e9ec",

		border: "#d2cdc6"
	}
};

// initializing the plugin connector
var createPluginConnector = require("@edmdesigner/superpreview-connector");
var pluginConnector = createPluginConnector({
	theme: theme,
	JWT: "some Json Web Token"
});

3. default plugin operations

Each plugin type has common operations, such as creating the plugin, getting a plugin instance and destroying one.

These operations are available through the created Plugin Connector object. This object has all the available operations of the plugin, containing each operation as a separate callable property.

3.1. create a plugin instance

Plugin can be instantiated by calling the pluginConnector.create() function.

This operation has two parameters: a config object and an optional callback function.

It returns with the instance object representing the generated instance.

3.1.1. config object

If an existing id is given as id property (or creator function is called with the id's default value again without destroying first instance), the original plugin instance will be altered by the new one. The previous iframe node and any other data related to the original instance will be deleted. This way the library avoids memory leaking, failed delivery of messages and non-working trashes in the DOM tree.

3.1.2. optional callback function

A plugin instance's creator function has an optional callback parameter. If its a function, it will be called when the plugin instance is loaded and its DOM content has been built within its iframe. That's the state when the plugin is ready to use and capable of receiving postMessages. It is signaled to the Plugin Connector by sending a DOMReady postMessage (see section 1.4.1.).

This function is useful when some operations have to be executed after the plugin is loaded.

3.1.3. create plugin instance object

The create function also adds a new plugin instance object to the generated and stored instances. It can be accessed by getInstance function (see section 3.2.). Details of instance object are described in section 3.2.1.

3.1.4. example

This example assumes that a proper Plugin Connector is loaded and initialized conveniently (see section 2.). The example also assumes that the created PluginConnector object is stored in the variable "pluginConnector".

// instantiate superpreview plugin
var previewConfig = {
	id: "superpreviewExample",
	parentElement: document.body,
	callbacks: {
		changeSize: function(width, height) {
			console.log("Superpreview example's changeSize callback called with width '" + width + "' and height '" + height + "'.");
		}
	},
	autoSize: true,
	height: "100px"
};

pluginConnector.create(previewConfig, function() {
	//DOMReady callback function
	console.log("Superpreview example's instance is successfully loaded and DOM tree is built.");
});

3.2. getting a plugin instance

The Plugin Connector stores an object containing the plugin instance. This object can be reached by calling the getInstance function of the PluginConnector object.

This function has a 'serviceId' optional parameter. If a unique plugin id string is given, the corresponding plugin instance will be returned, otherwise the plugin will be requested with the serviceId: "default".

If the 'serviceId' cannot be found among the plugin instances, it will return with false.

3.2.1. returning instance object

3.2.2. getDocumentHeight operation

Every plugin provides a getDocumentHeight operation. This operation can be accessed by calling getDocumentHeight function on the plugin instance object.

This function has a mandatory callback parameter.

It sends a request-answer paired type message (see section 1.4.2.), so the answer is passed towards the integrator by calling its callback function.

Example:

pluginConnector.getInstance("superpreviewExample").getDocumentHeight(function(domHeight) {
	console.log("Received domHeight: " + domHeight);
});

3.2.3. additional properties as functions of specific plugin operations on the returning instance object

Specific plugin operations are also added to the instance's object. This is the common way of reaching every operation triggering postMessage transfer towards the plugin instance.

These functions and their parameters are discussed in section 4. depending on plugin.

3.2.4. Operations sending request-answer paired type messages, requiring callback function

Several messages are paired as requests towards the plugin and replies from the Plugin Connector that are passed to the integrator. These messages are paired through a unique message id (see section 1.3.).

Messages with this type have mandatory callback functions, because the answer belongs to the request uniquely, so it has to be handled by a different callback for every request.

In these cases, no common callback given in the create functions config.callbacks object (see section 3.1.1.) will be called when the Plugin Connector receives a reply. Always a given specific callback function will be called instead.

3.2.5. example

This example assumes that the superpreview Plugin Connector is loaded and initialized conveniently (see section 2.). This example also assumes that an instance of the superpreview plugin is created properly (see section 3.1.4.).

var instance = pluginConnector.getInstance("superpreviewExample");
console.log("Instance object: " + instance);

3.3. destroying a plugin instance

A stored instance object and the appended iframe node can be deleted by calling the plugin's destroy function.

It has an optional 'serviceId' parameter, working similar to getInstance function's parameter (see section 3.2). If the instance for a plugin cannot be found with a given serviceId, it throws an error. Otherwise it destroys the stored object and the iframe DOM node of the instance.

Example:

pluginConnector.destroy("superpreviewExample");

3.4. Reload plugin instance

Plugin instances can be reconstructed with their original config object by calling the reload plugin operation.

It has an optional 'serviceId' parameter, working similar to getInstance function's parameter (see section 3.2). If the instance for a plugin cannot be found with a given serviceId, it throws an error. Otherwise it destroys the stored object and the iframe DOM node of the instance, then creates a new instance with its original config.

pluginConnector.reload("superpreviewExample");

4. plugins

The provided plugins are discussed in this section in detail. Specific plugin operations can be reached via the plugin instance object (see section 3.2.3.).

4.1. contentEditor

4.1.1. creating contentEditor instance

There are additional mandatory properties of contentEditor's create instance function's config object:

Also an object in 'callbacks' property has additional mandatory properties:

Optional callbacks can be given for 'DOMReady' and 'editBlock' messages (sent by plugin).

4.1.2. getJSON operation

It's an operation for getting edited template object in JSON encoded format for saving and storing it. This sends request-answer paired type messages.

The answer contains the requested 'contentJSON', the JSON encoded template object from the contentEditor. Thus, given callback should have a 'contentJSON' parameter and should process this data (properly it means storing it for later recalling).

4.1.3. insertImage operation

When an image is selected from the integrator's gallery in order to change an image in the contentEditor, it can be sent to the plugin by calling the insertImage operation.

It has two required parameters, the dynamic id ('dynId') received from the editor plugin and the source ('url' or 'src') of the hosted image which has to be used in the contentEditor, in the template's specified field.

Despite its behaviour, this is not a request-answer paired type message, because the contentEditor determines which image has to be replaced by the given dynId and it's not the role of EDMdesigner Plugin Core to couple these messages by the messageId.

4.1.4. insertBlock operation

Sends insertBlock message with given blockJSON parameter. Last edited block in contentEditor plugin's narrowListing will be replaced by the new block described by blockJSON.

Works like insertImage operation: clicking on an edit button below the contentEditor's blocks triggers a block edit request. These messages can be catched by the optional editBlock callback function. In the optional callback function, the integrator can call the layoutEditor plugin and after the block is successfully edited, the new block's JSON content can be sent by this insertBlock operation, in order to replace the original block in the contentEditor instance.

Despite its behaviour, this is not a request-answer paired type message, because the contentEditor stores the last block (based on last block's edit button click) and that block will be changed automatically when the insertBlock message is received in the plugin.

4.1.4. example

This example assumes that the contentEditor Plugin Connector is loaded and initialized conveniently (see section 2.), and that the blocks and template variables are containing valid blocks and template JSON data.

//setting config parameters
var theme = {
	theme: "chamaileon",
	colors: {
		primary: "#44c0fc",
		secondary: "#9b9b9b",

		info: "#25aaf2",
		success: "#54c059",
		warning: "#f5a500",
		error: "#ee483b",

		white: "#fff",
		black: "#000",

		lightGray: "#f5f7f8",
		mediumGray: "#c0c1c3",
		darkGray: "#e5e9ec",

		border: "#d2cdc6" //only for the chamaileon style
	},
	icons: {
		search: "#icon-search",
		imageToolbox: {
			edit: "#icon-wand"
		}
	},
	labels: {
		linkToolbox: {
			"protocol": "Protocol",
			"url": "Url",
			"other": "other",
			"email-address": "Address",
			"email-subject": "Subject",
			"email-message": "Message"
		},
		imageToolbox: {
			"image-preview": "Image Preview",
			"on-switch": "On",
			"off-switch": "Off",
			"change-button": "Change",
			"edit-button": "Edit",
			"alternate-text": "Alternate text",
			"link": "Link"
		}
	}
};

var l10n = {
	"ALL": "All",
	"TAGS": "Tags: ",
	"NOTSET": "Not set",
	"YES": "Yes",
	"NO": "No",
	"RESET": "Clear filter"
};

var editorCallbacks = {
	getJSON: function(contentJSON) {
		console.log("Received template JSON: " + contentJSON);
	},
	changeBackgroundImage: function() {},
	changeContentImage: function() {},
	editImage: function() {}
};

var editorConfig = {
	id: "contentEditorExample",
	parentElement: document.body,
	blocks: blocks,
	l10n: l10n,
	template: template,
	callbacks: editorCallbacks
};

//creating contentEditor instance
pluginConnector.create(editorConfig, function() {
	console.log("contentEditorExample DOM is ready. Plugin create's callback function is called properly.");
});

//getJSON operation
pluginConnector.getInstance("contentEditorExample").getJSON();

//insertImage operation
pluginConnector.getInstance("contentEditorExample").insertImage("someDynId", http://example.com/example.png");

4.2. supergallery

4.2.1. creating supergallery instance

There aren't any additional mandatory properties of the supergallery's create instance function's config object.

However, the config object's callbacks property has to contain these callback functions:

Supergallery iframe is suggested to display within a knob-modal component. See knob-js documentation for further details about this HTML GUI component.

4.2.2. edit operation

In order to use the supergallery's image editor via the Plugin Connector, the edit operation has to be called for sending the edit image request. Thus, this function has a dynamic id ('dynId') parameter received from the editor plugin. This parameter need to be stored and insertImage message has to contain it. This function also has a source ('src' or 'url') parameter, containing reference to the image needed to be edited.

This request doesn't have a reply, because supergallery handles modification and storage of edited image file.

4.2.3. setCrop operation

Supergallery plugin has a crop feature. It can be enabled and configured by the setCrop operation via the Plugin Connector.

The setCrop function has two parameters: cropWidth and cropHeight. The gallery will crop and convert images to the given size, until it receives a clearCrop message (see section 4.2.4.). This request doesn't have a reply.

4.2.4. clearCrop operation

Supergallery crop feature can be disabled and its configuration parameters (crop size) can be deleted by a clearCrop operation via the Plugin Connector. Images won't be cropped after the plugin receives the clearCrop message.

This operation doesn't have any parameters or replies.

4.2.5. example

This example assumes that the supergallery Plugin Connector is loaded and initialized conveniently (see section 2.).

//setting config parameters
var galleryCallbacks = {
	cancel: function() {
		console.log("supergallery instance cancelled");
	},
	insert: function(src) {
		console.log("insert message received from supergallery instance: " + src);
	}
};

var galleryConfig = {
	id: "supergalleryExample",
	parentElement: document.body,
	callbacks: galleryCallbacks
};

//creating supergallery instance
pluginConnector.create(galleryConfig);

//edit operation
pluginConnector.getInstance("supergalleryExample").edit("http://example.com/example.png");

//setCrop operation
pluginConnector.getInstance("supergalleryExample").setCrop(640, 480);

//clearCrop operation
pluginConnector.getInstance("supergalleryExample").clearCrop();

4.3. superpreview

4.3.1. creating superpreview instance

There aren't additional mandatory properties of superpreview's create instance function's config object.

Neither the config object's callbacks property has to contain callback functions. There is an optional callback called 'changeSize' for autoSize option (see section 5.1.).

4.3.2. the url operation

The superpreview plugin opens a given url and shows its preview. In order to send this url to the plugin, the url operation should be used. This operation has an 'url' parameter containing the url of the website which has to be previewed by the plugin.

4.3.3. selectTab operation

The superpreview plugin has 3 tabs for different previews. Tabs can be selected by the selectTab operation. It has a parameter 'selectedIdx', which is the index of tab that should be selected (indexing starts from 0).

4.3.4. example

This example assumes that the superpreview Plugin Connector is loaded and initialized conveniently (see section 2.).

//setting config parameters
var previewConfig = {
	id: "superpreviewExample",
	parentElement: document.body,
	callbacks: {
		changeSize: function(width, height) {
			console.log("Superpreview example's changeSize callback called with width '" + width + "' and height '" + height + "'.");
		}
	},
	autoSize: true
};

//creating superpreview instance with autoSize option and optional changeSize callback
pluginConnector.create(previewConfig);

//url operation
pluginConnector.getInstance("superpreviewExample").url("http://edmdesigner.com");

//selectTab operation
pluginConnector.getInstance("superpreviewExample").selectTab(2);

4.4. layoutEditor

The layoutEditor plugin is an alias of contentEditor, except that its create config object does not have a required blocks parameter. Related 'blocks' type messages in this plugin are also unnesseccary.

4.4.1. example

This example assumes that the layoutEditor Plugin Connector is loaded and initialized conveniently (see section 2.), and that the template and theme variables are containing valid template JSON and theme data.

//setting config parameters
var l10n = {
	"drag-title": "Drag Icons",
	"drag-type-fullwidth-container": "FULLWIDTH",
	"drag-type-box": "BOX",
	"drag-type-multicol": "MULTICOL",
	"drag-type-text": "TEXT",
	"drag-type-image": "IMAGE",
	"drag-type-button": "BUTTON"
};

var editorCallbacks = {
	getJSON: function(contentJSON) {
		console.log("Received template JSON: " + contentJSON);
	},
	changeBackgroundImage: function() {},
	changeContentImage: function() {},
	editImage: function() {}
};

var editorConfig = {
	id: "layoutEditorExample",
	parentElement: document.body,
	l10n: l10n,
	template: template,
	callbacks: editorCallbacks
};

//creating layoutEditor instance
pluginConnector.create(editorConfig, function() {
	console.log("layoutEditorExample DOM is ready. Plugin create's callback function is called properly.");
});

4.5. templateLayer

The templateLayer plugin is very similar to the supergallery plugin. There are three major differences in their postMessages:

• templateLayer doesn't receive edit, setCrop or clearCrop messages
• init message and configuration is completed with a mandatory "package" property refering to the used template package in the plugin instance
• it sends insert message also when user selects a template in the plugin, but in this plugin the selected template will be sent to the integrator instead of supergallery's src parameter. The "template" mandatory field of insert message will contain the valid EDM document JSON of the template selected by the user.

As a succession of this similarity with the supergallery plugin, in order to see any further details of the behaviour of the templateLayer plugin, see section 4.2. (the documentation of supergallery plugin).

5. additional features

5.1. autoSize option

This feature is implemented for the automatic sizing of the plugins. The instance sends its required DOM size by a changeSize message and its iframe is automatically set to the received width and height values in the Plugin Connector.

This is useful to avoid scrollable/hidden content within the plugin's iframe. When resizing the iframe, it is called again with new values, so the plugin can modify the style or arrangement of its content, according to new sizes, then sends the new sizes with a changeSize message.

Only superpreview plugin supports this feature yet.

5.1.1. usage with optional callback (catching changeSize messages)

The autoSize option should be used with the given changeSize callback function. It has 'width' and 'height' parameters, and they contain the received automatic size values from the plugin. See section 4.3.4. for usage example.

5.2. optional callbacks for messages sent by plugin

Messages sent by the plugin without a request from the Plugin Connector or a mandatory callback are event related messages triggered inside the plugin. Optional callbacks can be given to these type of messages by adding it to the callbacks object of the creator function's config parameter, as a property called the same as the message type.

Typically, these optional callbacks are belonging to DOMReady or changeSize messages (see section 5.1.1.).

See section 4.3.4. for usage example.

Note: changeSize callback is specific, because it has a domWidth and a domHeight parameter. Usually these optional callbacks don't have any parameters to pass towards integrator, only receiving the message holds information about the event that happened inside the plugin.