drawsvg iconDRAWSVG user's manual
PreviousNextContentsPDFdrawsvg

12.2. Integration by API

12.2.1. Introduction
12.2.2. Function setDocumentMenu
12.2.3. Function loadStringSVG
12.2.4. Function loadUrlSVG
12.2.5. Callback saveService
12.2.6. Function getSVG
12.2.7. Function getSVGObject
12.2.8. Function addLayer
12.2.9. Function setInputLayerId
12.2.10. Function setCustomShapeCatalog

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

Which mode to chooze ?

  1. The Online mode has the advantages of benefiting from the latest version without updating with more services.

  2. The Embedded mode with Edrawsvg allows you to group drawsvg editor and your application within your WEB container and runs on a private network without internet connexion.

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 :

  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.

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.

12.2.2. Function setDocumentMenu

This function is used to control the document menu.

ParameterType / description
enableSamples

boolean

Enable (true) or disable (false) the samples sub-menu.

disableTasks

string

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

        

12.2.3. Function loadStringSVG

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

ParameterType / description

stringSVG

string

The document contents

backgroundImageURL

string

The background image URL, can be:

  • A valid global URL (https: or https:)

  • A relative image file path from your domain starting with a slash character (ex: /home/images/..).

    The loadStringSVG function will add your domain adress to build a valid URL.

  • A encoded 64 base URI.

The image dimensions should have the same ratio width/height than the svg viewBox.

This will create an image element with the URL and geometry (x,y,width,height) to cover the svg viewBox.

nameSVG

string

The svg name

saveService

string

The name of the bind function to be called to save the document when the user click on the save button of drawsvg.

showSaveDialog

boolean

false: the dialog will not be displayed on save (default is true).

fullWindow

boolean

Change (true) the dimensions of the document to the full window (100%) or (false) view the document with it's size.

saveButtonLabel

boolean

The label of the save button.

onLoad

string

The function called by drawsvg when the document is loaded.

onError

string

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

Save dialog with save service button

12.2.4. Function loadUrlSVG

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

ParameterType / Description
urlSVG

string

The document URL
nameSVG

string

The svg name
useEmbed

string

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.

saveService

string

The name of the bind function to be called to save the document when the user click on the save button of drawsvg.
showSaveDialog

boolean

false: the dialog will not be displayed on save (default is true).
fullWindow

boolean

Change (true) the dimensions of the document to the full window (100%) or (false) view the document with it's size.
saveButtonLabel

string

The label of the save button.
onLoad

string

The function called by drawsvg when the document is loaded.
onError

string

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

        

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

string

The document content
nameSVG

string

The svg name
modified

boolean

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

        

12.2.6. Function getSVG

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

This function has only one parameter.

ParameterType / Description
unloadBackgroundImage

boolean

If true, the background image is removed from the output.

Example:

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

        

12.2.7. Function getSVGObject

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

It has only one parameter.

ParameterType / Description
unloadBackgroundImage

boolean

If true, the background image is removed from the output.

The current SVG document is returned as object with properties.

PropertyType / Description
modified

boolean

Indicates whether the document has been modified.

stringSVG

string

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

        

12.2.8. Function addLayer

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

ParameterType / Description
layerId

string

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

        

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

ParameterType / Description
layerId

string

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

        

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

ParameterType / Description
index

int

The index of the catalog (from 1 to 4)
title

string

The title of the catalog
stringSVG

string

The generated svg document of the catalog
store

boolean

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