9.2. Integration by API

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.

This use case is done with the 'jsChannel' entry without parameters (at this moment) :

<iframe id="drawsvg" src="http://www.draw-svg.appspot.com/drawsvg.html#jsChannel:"></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.1. 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.2. 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 of the document 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.3. 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.4. 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

ParameterDescription
urlSVGThe document URL
nameSVGThe svg name

Example:

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

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

9.2.5. Function getSVG

This function is used to get the current SVG document 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.6. 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.7. 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) {}
	});