PreviousNextContentsPDF

9.2. Integration by API

9.2.1. Introduction
9.2.2. Function setDocumentMenu
9.2.3. Function loadStringSVG
9.2.4. Function loadUrlSVG
9.2.5. Callback saveService
9.2.6. Function getSVG
9.2.7. Function getSVGObject
9.2.8. Function addLayer
9.2.9. Function setInputLayerId
9.2.10. Function setCustomShapeCatalog

9.2.1. Introduction

This is the most powerfull integration mode. It requires the use of an iframe. It uses mozilla jsChannel tool.

See the demo of this mode.

Choose your integration mode, Online or Embedded with Edrawsvg distribution

Drawsvg can be integrated in the same way both online mode and embedded mode with Edrawsvg. The online mode has the advantages of benefiting from the latest version without updating with more services. The integrated mode with Edrawsvg allows you to group drawsvg editor and your application within your WEB container.

Edrawsvg is a distribution of Draw SVG editor, intended to developpers to be embedded into their websites. Edrawsvg is a free software released under the GNU LGPL.

Request an API Key

To activate your drawsvg integration, and download Edrawsvg if you plan to use it, you should request a registered API Key.

How to

Insert drawsvg within an iframe with the 'jsChannel' entry and key parameter like this:

<iframe id="drawsvg" src="http://www.drawsvg.org/drawsvg.html#jsChannel:?key=yourKey"></iframe>

For the offline embedded release edrawsvg:

<iframe id="drawsvg" src="edrawsvg.html#jsChannel:?key=yourKey"></iframe>

The integration sequence is :

  1. Establish a communication channel with drawsvg iframe.

  2. Wait drawsvg ready notification

  3. Call drawsvg functions when ready

To establish a communication channel:

// create drawsvg channel
var chan = Channel.build({
    debugOutput: true,
    window: document.getElementById("drawsvg").contentWindow,
    origin: "*",
    scope: "drawsvg"
});

To wait the drawsvg ready notification :

  1. Define a function to receive notification

  2. bind it as "onDrawSVGReady" to be called by drawsvg

// drawsvg ready callback
function onDrawSVGReady(trans,params) {
	// now you can communicate with drawsvg
	log("got drawsvg ready notification");
	return "connected";
};
// bind drawsvg ready callback 
chan.bind("onDrawSVGReady", onDrawSVGReady);

There are functions to control the document menu, edit and save svg documents.

More functions will be added to customize drawsvg under user requests.

9.2.2. Function setDocumentMenu

This function is used to control the document menu.

ParameterTypeDescription
enableSamplesbooleanEnable (true) or disable (false) the samples sub-menu.
disableTasksstring

Disable a list of tasks from :

  • new, create a new document

  • open, open a existing document

  • save, save the document

  • print, print the document

  • exportpng, export the document as a png image

  • dimensions, set the document dimensions

  • resize, set the document viewBox with a rectangle

  • grid, set the grid tool parameters

  • importdef, import definitions from another svg document

  • gradient, open the gradient tool editor

  • pattern, open the pattern tool editor

  • filter, open the filter tool editor

  • marker, open the marker tool editor

This example disables the new and open tasks, the user can only edit the loaded document :

// drawsvg ready callback
function onDrawSVGReady(trans,params) {
	// now you can communicate with drawsvg
	log("got drawsvg ready notification");
	// enable buttons
	document.getElementById("svg1btn").disabled=false;
	document.getElementById("svg2btn").disabled=false;
	// setting document menu
	// call 'setDocumentMenu' method 
	// with params {enableSamples, disableTasks}
	chan.call({
		method: "setDocumentMenu",
		params: {
			// disable samples sub-menu
			'enableSamples' : false,
			// disable taks new and open 
			'disableTasks' : 'new open'
		},
		// jsChannel callbacks
		error: function(error, message) { 
			log( "ERROR: " + error + " (" + message + ")");
		},
		success: function(v) {
			log("setting document menu done");
		}
	});
	return "connected";
};

9.2.3. Function loadStringSVG

This function is used to edit a svg document when its contents is stored in a javascript string variable.

ParameterTypeDescription
stringSVGstringThe document contents
nameSVGstringThe svg name
saveServicestringThe name of the bind function to be called to save the document when the user click on the save button of drawsvg.
showSaveDialogbooleanfalse: the dialog will not be displayed on save (default is true).
fullWindowbooleanChange (true) the dimensions of the document to the full window (100%) or (false) view the document with it's size.
saveButtonLabelbooleanThe label of the save button.
onLoadstringThe function called by drawsvg when the document is loaded.
onErrorstringThe function called by drawsvg when the document cannot be loaded.

Note

This function is asynchronous

Example:

chan.call({
	method: "loadStringSVG",
	params: {
		// string svg contents
		'stringSVG' : stringSVG1,
		// svg name
		'nameSVG' : 'svg1',
		// The name of the service which to be called 
		// when user clicks on the save button of drawsvg
		'saveService' :  'onSaveSVG',
		// don't show save dialog
		'showSaveDialog' : false,
		// Change the dimensions to the full window (100%)
		'fullWindow' : true,
		// svg loading callbacks
		'onLoad' : function() {
			log("got svg1 onLoad notification");
		},
		'onError': function(err) {
			log("ERROR while loading svg1: "+err);
		}
	},
	// jsChannel callbacks
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {}
	}
);

When the user clicks on the "save" icon of the document menu, then DRAW-SVG shows a dialog with a button to call the "saveService" function.

Le label of the 'saveService' button is set with the parameter 'saveButtonLabel' value.

Figure 9.1. Save dialog with save service button

Save dialog with save service button

9.2.4. Function loadUrlSVG

This function is used to edit a svg document identified by its URL.

ParameterTypeDescription
urlSVGstringThe document URL
nameSVGstringThe svg name
useEmbedstring

Selection of the container type within drawsvg

  1. true (default) , the svg is edited with an embed element

  2. false, the svg is edited with an svg inline element.

saveServicestringThe name of the bind function to be called to save the document when the user click on the save button of drawsvg.
showSaveDialogbooleanfalse: the dialog will not be displayed on save (default is true).
fullWindowbooleanChange (true) the dimensions of the document to the full window (100%) or (false) view the document with it's size.
saveButtonLabelstringThe label of the save button.
onLoadstringThe function called by drawsvg when the document is loaded.
onErrorstringThe function called by drawsvg when the document cannot be loaded.

Note

This function is asynchronous

The embed mode has the advantages to delegate the loading to the element and to isolate the svg contents from the drawsvg page. If the URL is not in the same domain, drawsvg will use its proxy service.

In the other case (useEmbed:false) drawsvg will load the document contents with an HTTP Request.

Example:

chan.call({
	method: "loadUrlSVG",
	params: {
		// svg url
		'urlSVG' : urlSVG2,
		'nameSVG' : 'svg2',
		// use inline svg instead of embed
		'useEmbed' : true,
		// The name of the save service
		'saveService' :  'onSaveSVG',
		// save button label
		'saveButtonLabel' : 'save svg2',
		// svg loading callbacks
		'onLoad' : function() {
			log("got svg2 onLoad notification");
		},
		'onError': function(err) {
			log("ERROR while loading svg2: "+err);
		}
	},
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {}
});

9.2.5. Callback saveService

To save the document with a dedicated function when the user click on the "save" button of drawsvg :

  1. Declare the function with arguments (trans,params)

  2. Bind it with a dedicated name

  3. Set the 'saveService' parameter value with this name

The 'params' argument contains the name and the new contents of the document to save it

ParameterTypeDescription
urlSVGStringThe document URL
nameSVGStringThe svg name
modifiedboolean

Indicates whether the document has been modified.

Example:

// save svg service
function  onSaveSVG(trans,params) {
	log("onSaveSVG nameSVG="+params['nameSVG']);
	log("onSaveSVG modified="+params['modified']);
	log("onSaveSVG stringSVG="+params['stringSVG']);
	// save svg with stringSVG 
	// .... write your code
	return "save done";
}

// bind save callback
chan.bind("onSaveSVG", onSaveSVG);

9.2.6. Function getSVG

This function is used to get the current SVG document returned as String.

This function is asynchronous and does not have parameters.

Example:

	
chan.call({
	method: "getSVG",
	params: {},
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")");
	},
	success: function(v) {
		log(v);
	}
});

9.2.7. Function getSVGObject

This function is used to get the current SVG document returned as object with properties.

PropertyTypeDescription
modifiedboolean

Indicates whether the document has been modified.

stringSVGstringThe SVG document

This function is asynchronous and does not have parameters.

Example:

	
chan.call({
	method: "getSVG",
	params: {},
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {
		log("modified="+v['modified']);
		log("stringSVG="+v['stringSVG']);
	}
});

9.2.8. Function addLayer

This function creates a layer (a g element child of the document root).

ParameterTypeDescription
layerIdstringThe ID of the layer

The layer can be used after receiving the success method.

Example:

chan.call({
	method: "addLayer",
	params: {
		'layerId' : 'myLayer',
		}
	},
	// jsChannel callbacks
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {}
});

9.2.9. Function setInputLayerId

This function limits the operations of creating and modifying the elements of the documents to those included in the identified layer.

The layer must exist and be a 'g' element.

ParameterTypeDescription
layerIdstringThe ID of the layer

Example:

chan.call({
	method: "setInputLayerId",
	params: {
		'layerId' : 'myLayer',
		}
	},
	// jsChannel callbacks
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {}
});

9.2.10. Function setCustomShapeCatalog

This function can be used to define a custom shape catalog with the generated file by the tool custom shape catalog tool. (see chapter customization)

ParameterTypeDescription
indexintThe index of the catalog (from 1 to 4)
titleStringThe title of the catalog
stringSVGStringThe generated svg document of the catalog
storebooleanOption to save the catalog in the local storage space of the browser.

Example:

chan.call({
	method: "setCustomShapeCatalog",
	params: {
		'index' : 1,
		'title': 'brands',
		'stringSVG': doc,
		'store':true
		}
	},
	// jsChannel callbacks
	error: function(error, message) { 
		log( "ERROR: " + error + " (" + message + ")"); 
	},
	success: function(v) {}
});