12.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.

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 .

Which mode to chooze ?

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.

Edrawsvg is a pure ajax web application, it's need a javascript engine. It's cannot be run directly from files.

The war distribution can be deployed on an apache tomcat server, zip distribution with Node.js engine.

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="https://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 :

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 :

          // 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.

User profile

Only features of the basic user profile are enabled with Edrawsvg (see chapter user profile ).

With jsChannel online integration, the expert profile remains activated if it was validated on the last access to drawsvg online on the same browser.

This function is used to control the document menu.

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";
};

        

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

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 12.1. Save dialog with save service button

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

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) {}
});

        

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

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

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);

        

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

This function has only one parameter.

Example:

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

        

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

It has only one parameter.

The current SVG document is returned as object with properties.

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']);
	}
});

        

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

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) {}
});

        

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.

Example:

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

        

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 )

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) {}
});