store Method

Description

Creates SVG data for the current diagram and passes this SVG data into the onSuccess function. Optionally, the method will return a Base64 encoded export of the diagram in png or jpeg format.

Remarks

Creates valid SVG data for the current diagram and passes this SVG data into the onSuccess function which may be displayed in the browser or any other container that supports the SVG format. The diagram may also be loaded back into the drawing editor by passing it to the load method.

Syntax

.store(/* Object */ options, /* Function */ onSuccess, /* Function */ onError)

Parameters

options: Object

A hash of values that control the store operation. The valid values are:

ignoreMapError — When true, errors that occur while updating the map in the diagram will be ignored. When a map update error occurs and this option is enabled, the stored diagram will not include the map.
The default value is false.

image — When true, a Base64 encoded image of the current diagram will be generated along with the diagram SVG string. This image will be returned via the onSuccess callback along with the SVG string.
The default is false.

If image is true, these properties apply:

format — Specifies the image format. 'image/jpeg' and 'image/png' are supported.
The default is 'image/png'.

imageQuality — This value sets the quality level for a JPG export. Acceptable values are between 0.0 and 1.0. For best quality specify 1.0. A quality setting of 0.75 provides good image quality and compression. Lower quality settings provide greater image compression. This option is ignored for PNG images.
The default is 0.75

trim — This option, when set to true, trims the white space so the resulting image has the same aspect ratio as the diagrams viewbox.
The default is false.

resolutionPixels - The number of pixels per output resolution unit. This value and the value of resolutionUnit define the output resolution. Output resolution is always 1 resolutionUnit / resolutionPixels. For example, if resolutionUnit is 'inch' and resolutionPixels is 300, the output resolution will be 300px/inch.
The default is 72px.

Note: Output resolution is important for two reasons. First, it used to convert output sizes (width, height, margin) expressed as linear measurements to pixels. Second, some diagram features are sized based on output resolution. Items on the measurment layer and structure dimension lines are examples of this behavior. The sizes of these items are defined in points (1/72") and the output resolution is used to calculate thier output size in pixels.

resolutionUnit — A standard linear unit of measure like 'inch' or 'cm' that is combined with resolutionPixels to define output resolution.
The default is 'inch'.

width — The image width in pixels or expresssed as a linear measurement like '7.5"' or '20cm'. When width is expresssed as s linear measurement it will be converted to pixels based on the output resolution. For example if width is '7.5"' and output resolution is 300px/inch, the resulting width will be 2250px.
The default is 600px.

height — The image height in pixels or expresssed as a linear measurement like '10"' or '5cm'. When height is expresssed as a linear measurement it will be converted to pixels based on the output resolution. For example if height is '10"' and output resolution is 300px/inch, the resulting height will be 3000px.
The default is 600px.

margin — The image margin width in pixels or expresssed as a linear measurement like '0.25"' or '0.5cm'. When margin is expresssed as a linear measurement it will be converted to pixels based on the output resolution. For example if margin is '0.5"' and output resolution is 300px/inch, the resulting margin will be 75px.
The default is 0px.

includePrefix — When set to true adds a data: URL prefix to the exported string. This image can then be used directly in the browser.
The default is true.

Note: Although the exported image may be used directly in this manner, keep in mind that the SVG passed into the onSuccess function can be easily displayed in your page. Using the SVG is more efficient than exporting the image and provides greater fidelity.

includeStructureDimensions — When set to true, wall length dimension lines will be included in the stored SVG and the generated image, if the diagram contains one or more structure shapes.
The default is false.

includeFieldMeasurements — When set to true, shapes from the measurement layer will be included in the stored SVG and the generated image -- a JSON formatted string that contains the data values from the measurement layer will also be returned in the "diagram info" hash which is the second argument passed to the onSuccess callback.
The default is false.

includeAttachments — When set to true, attachments will be visible in the stored diagram.
The default is true.

onSuccess: Function

This function will be called when diagram store completes successfully. It will be passed two parameters:

The stored diagram SVG string.

A hash of information related to the diagram and image as specified in the options parameter. The items in this hash may include:

image: a string containing a Base64 encoded image of the stored diagram (with format as specified in options).

fieldMeasurements: a object containing the measurement layer data.

Here is an example of the measurement layer data:

{
  units: "feetAndInches",
  stationLines: [
	{
	  stationLineIncrement: 0,
	  formattedStationLineIncrement: "0'",
	  markers: [
		{
		  id: "1",
		  description: "Station Line One",
		  station: 10,
		  formattedStation: "10'",
		  distance: 10,
		  formattedDistance: "10'",
		  direction: "R"
		}
	  ]
	}
  ],
  triangulationMeasurements: {
	markerPoints: [
	  {
		id: "1",
		description: "Measurement Point One",
		refPt1: "A",
		refPt2: "B",
		distance1: 20,
		formattedDistance1: "20'",
		distance2: 20,
		formattedDistance2: "20'",
		direction: "L"
	  }
	]
  }
}

Note: the measurement layer data includes formatted and numeric versions of length and distance values.

onError: Function

A function that accepts one parameter, a JavaScript Error object. This function will be called if the export fails. An Error object indicating the nature of the failure will be passed to it. If this function does not return true, indicating that the error has been handled, the error will be passed on to the built-in error handler.

SVG Diagram and Image Consistency

When an image is requested as part of the store, the resulting SVG diagram and the image will be visually consistent. This implies that options that directly effect the exported image like width, height, and margin will impact the stored diagram as well. For example if an image is requested with width set to 800px, height set to 600px, and margin set to 40px, the stored diagram will have an aspect ratio of 4:3 with margin that is 5% of its width.

Example

editor = new ESDWeb(null, 'editorNode');

/* set editor properties here */

editor.startup();

In code that runs after the editor is closed:

var diagramData = editor.store(
	{
		image: true,
		width: 300,
		height: 300,
		includeFieldMesurements: true,
		format: 'image/jpeg'
	},
	function (diagram, diagramInfo) {
		// The store was successful...
		// The parameter "diagram" is a string containing a copy of the
		// current diagram. The parameter "diagramInfo" contains
		// auxiliary information related the stored diagram. In
		// this case, diagramInfo.image will be a Base64 encoded
		// 300x300 JPEG image of the diagram as well as a json string
        // containing information about the field measurements in the
        // diagram.

        // Any operations that depend on the diagram copy or
        // the image must be done within the body of this callback
        // function.
	},
	function (error) {
		alert('Diagram store failed: ' + error.message);
	}
);