zcy
/
svgedit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
svgedit/docs/ConfigOptions.md

11 KiB
Raw Blame History

Introduction

As of version 2.5, SVG-edit has several configuration settings that can be overridden either by adding URL parameters or by setting the options in JavaScript. As of version 2.7, a few among these options related to paths are disallowed via URL though they can still be set by svgEditor.setConfig.

How to set the options

Options can be set using svgEditor.setConfig(options), where options is an object literal of keys and values. This must be run before the actual page or DOM is loaded, otherwise it will have no effect. Note that one may create a svgedit-config-iife.js file within the project root directory and add such configuration directives to it without needing to modify the repository editor code (and note version 2.8 adds support for a custom.css file for the same purpose).

Example:

svgEditor.setConfig({
  dimensions: [320, 240],
  canvas_expansion: 5,
  initFill: {
    color: '0000FF'
  }
});

This will set the default width/height of the image, the size of the outside canvas, and the default "fill" color.

The same options can be set in the URL like this:

.../svg-editor.html?dimensions=300,240&canvas_expansion=5&initFill[color]=0000FF

As of version 2.7, if options are set both using .setConfig() as well as in the URL, the .setConfig() value will be used. The reverse was true in previous versions but was changed for security reasons.

One may optionally pass another object to .setConfig() as the second argument to further adjust configuration behavior.

If an overwrite boolean is set to false on this additional object, it will, as occurs with all URL type configurations, prevent the current configuration from overwriting any explicitly set previous configurations. The default is true except for URLs which always are false.

If an allowInitialUserOverride boolean is set to true, it will allow subsequent configuration overwriting via URL (e.g., if you do want the user to have the option to override certain or your (svgedit-config-iife.js) .setConfig() directives via URL while still wishing to provide them with your own default value, you should add this property).

Configurable options

Note that those items marked as preferences are configuration items which can also be set via the UI (and specifically via Editor Options except where mentioned). Those items which appear in the UI but are not treated internally as preferences are marked with "Maybe" as their status may change.

| Property | Description | Default | Preference | |:---------|:------------|:--------|:-----------| | lang | Two-letter language code. The language must exist in the Editor Preferences language list | Default to "en" if locale.js detection does not detect another language | Yes | | bkgd_url | Background raster image URL. This image will fill the background of the document, useful for tracing purposes | (none) | Yes | | img_save | Defines whether included raster images should be saved as Data URIs when possible, or as URL references. Must be either 'embed' or 'ref'. Settable in the Document Properties dialog. | embed | Yes | | dimensions | The default width/height of a new document. Use an array in setConfig (e.g., [800, 600]) and comma separated numbers in the URL | [640, 480] | Maybe | | initFill[color] | The initial fill color. Must be a hex code string. | FF0000 (solid red) | No | | initFill[opacity] | The initial fill opacity. Must be a number between 0 and 1 | 1 | No | | initStroke[color] | The initial stroke color. Must be a hex code. | 000000 (solid black) | No | | initStroke[width] | The initial stroke width. Must be a positive number. | 5 | No | | initStroke[opacity] | The initial stroke opacity. Must be a number between 0 and 1 | 1 | No | | initTool | The initially selected tool. Must be either the ID of the button for the tool, or the ID without "tool_" prefix_| select | No | | exportWindowType | New as of 2.8. Can be "new" or "same" to indicate whether new windows will be generated for each export; the window.name of the export window is namespaced based on the canvasName (and incremented if "new" is selected as the type) | new | No | | imgPath | The path where the SVG icons are located, with trailing slash. Note that as of version 2.7, this is not configurable by URL for security reasons. | images/ | No | | jGraduatePath | The path where jGraduate images are located. Note that as of version 2.7, this is not configurable by URL for security reasons. | jgraduate/images/ | No | | langPath | The path where the language files are located, with trailing slash. Note that as of version 2.7, this is not configurable by URL for security reasons. | locale/ | No | | extPath | The path used for extension files, with trailing slash. Note that as of version 2.7, this is not configurable by URL for security reasons. | extensions/ | No | | extensions | Extensions to load on startup. Use an array in setConfig and comma separated file names in the URL. Note that as of version 2.7, paths containing "/", "", or ":", are disallowed for security reasons. Although previous versions of this list would entirely override the default list, as of version 2.7, the defaults will always be added to this explicit list unless the configuration noDefaultExtensions is included. | ['ext-overview_window.js','ext-markers.js','ext-connector.js','ext-eyedropper.js','ext-shapes.js','ext-imagelib.js','ext-grid.js','ext-polygon.js','ext-star.js','ext-panning.js','ext-storage.js'] | No | | showlayers | Open the layers side-panel by default | false | No | | wireframe | Start in wireframe mode | false | No | | gridSnapping | Enable snap to grid by default. Set in Editor Options. | false | Maybe | | gridColor | Set in Editor Options. | #000 (black) | Maybe | | baseUnit | Set in Editor Options. | px | Maybe | | snappingStep | Set the default grid snapping value. Set in Editor Options. | 10 | Maybe | | showRulers | Initial state of ruler display (v2.6). Set in Editor Options. | true | Maybe | | no_save_warning | A boolean that when true prevents the warning dialog box from appearing when closing/reloading the page. Mostly useful for testing. | false | No | | canvas_expansion | The minimum area visible outside the canvas, as a multiple of the image dimensions. The larger the number, the more one can scroll outside the canvas. | 3 | No | | show_outside_canvas | A boolean that defines whether or not elements outside the canvas should be visible; set by svgcanvas.js | true | No | | iconsize | Size of the toolbar icons. Must be one of the following: 's', 'm', 'l', 'xl' | Will default to 's' if the window height is smaller than the minimum height and 'm' otherwise | Yes | | bkgd_color | Canvas background color | #FFF (white) | Yes | | selectNew | Initial state of option to automatically select objects after they are created (v2.6) | true | No | | save_notice_done | Used to track alert status | false | Yes | | export_notice_done | Used to track alert status | false | Yes | | allowedOrigins | Used by ext-xdomain-messaging.js to indicate which origins are permitted for cross-domain messaging (e.g., between the embedded editor and main editor code). Besides explicit domains, one might add '' to allow all domains (not recommended for privacy/data integrity of your user's content!), window.location.origin for allowing the same origin (should be safe if you trust all apps on your domain), 'null' to allow file:// URL usage| [] | Maybe | | canvasName | Used to namespace storage provided via ext-storage.js; you can use this if you wish to have multiple independent instances of SVG Edit on the same domain | default | No | | initOpacity | Initial opacity (multiplied by 100) | 1 | No | | colorPickerCSS | Object of CSS properties mapped to values (for jQuery) to apply to the color picker. A null value (the default) will cause the CSS to default to left with a position equal to that of the fill_color or stroke_color element minus 140, and a bottom equal to 40 | null (see description) | No | | preventAllURLConfig | Set to true (in svgedit-config-iife.js; extension loading is too late!) to override the ability for URLs to set non-content configuration (including extension config) | false | No | | preventURLContentLoading | Set to true (in svgedit-config-iife.js; extension loading is too late!) to override the ability for URLs to set URL-based SVG content | false | No | | lockExtensions | Set to true (in svgedit-config-iife.js; extension loading is too late!) to override the ability for URLs to set their own extensions; disallowed in URL setting. There is no need for this when preventAllURLConfig is used. | false | No | | noDefaultExtensions | If set to true, prohibits automatic inclusion of default extensions (though "extensions" can still be used to add back any desired default extensions along with any other extensions); can only be meaningfully used in svgedit-config-iife.js or in the URL | false | No | | showGrid | Set by ext-grid.js; determines whether or not to show the grid by default | false | No | | noStorageOnLoad | Some interaction with ext-storage.js; prevents even the loading of previously saved local storage | false | No | | forceStorage | Some interaction with ext-storage.js; strongly discouraged from modification as it bypasses user privacy by preventing them from choosing whether to keep local storage or not | false | No | | emptyStorageOnDecline | Used by ext-storage.js; empty any prior storage if the user declines to store | false | No | | paramurl | This is available via URL only. Deprecated and removed in trunk. Allowed an un-encoded URL within the query string (use "url" or "source" with a data: URI instead) | (None) | No | | selectNew | Set by svgcanvas.js; used by mouseUp; it true, will replace the selection with the current element and show grips | true | No | | stylesheets | An array of required stylesheets to load in parallel; include the value '@default' within this array to ensure all default stylesheets are loaded | ['@default'] | No |

Preload a file

It is also possible to start the editor with preloaded SVG file, using the following methods.

However, one should bear in mind that if one wishes to immediately set a particular string, especially if in svgedit-config-iife.js (and prevent the user from saving their own text), one should first set the config option "noStorageOnLoad" to false or otherwise any previous local storage may overwrite your own string.

// Serialized string:
svgEditor.loadFromString('...');

// Data URI:
svgEditor.loadFromDataURI('data:image/svg+xml;base64,...');

// Local URL:
svgEditor.loadFromURL('images/logo.svg');

Or as URL parameter:

// Data URI
'?source=' + encodeURIComponent('data:image/svg+xml;utf8,') + encodeURIComponent(/*...*/)

// Data URI (base 64):
'?source=' + encodeURIComponent('data:image/svg+xml;base64,' + /* ... */); // data%3Aimage%2Fsvg%2Bxml%3Bbase64%2C ...

// Local URL:
'?url=' + encodeURIComponent('images/logo.svg'); // images%2Flogo.svg

Note: There is currently a bug that prevents data URIs ending with equals (=) characters from being parsed. Removing these characters seem to allow the import to work as expected.