171 lines
6.0 KiB
Markdown
171 lines
6.0 KiB
Markdown
# Introduction
|
|
|
|
SVG-edit has several options that can be overridden either by adding URL
|
|
parameters or by setting the options in JavaScript (since v2.5).
|
|
|
|
Options may be divided into "config" (which is not meant to be customized
|
|
via UI by the user) and "preferences" (which are meant to be customized
|
|
by UI).
|
|
|
|
See the API definition of
|
|
[Config]{@link module:SVGEditor.Config}
|
|
for the allowable values, defaults, and uses of config.
|
|
|
|
See the API definition of [Preferences]{@link module:SVGEditor.Prefs}
|
|
for their information.
|
|
|
|
A few among these options related to paths are disallowed via URL though
|
|
they can still be set by `svgEditor.setConfig()` (since v2.7).
|
|
|
|
These are covered in the sections below.
|
|
|
|
One may preload a file. See "Preloading a file" below.
|
|
|
|
One may also configure stylesheets expected by the default HTML
|
|
(`svgedit-custom.css` (v3.0+) or `custom.css` (v2.8))).
|
|
|
|
One may also add stylesheets programmatically (since v3.0).
|
|
See "Customizing stylesheets" below.
|
|
|
|
## How to set the options
|
|
|
|
### Setting options programmatically
|
|
|
|
Options of either type 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 as of v3.0 (or for v2.8, within `editor/config.js`) and
|
|
add such configuration directives to it without needing to modify the
|
|
repository editor code
|
|
|
|
```js
|
|
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.
|
|
|
|
#### Overwrite configuration
|
|
|
|
For programmatic config setting, 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`, this will allow
|
|
subsequent configuration overwriting via URL (e.g., if you want the
|
|
user to have the option to override certain of your (`svgedit-config-iife.js`)
|
|
`.setConfig()` directives via URL while still providing them with
|
|
your own default value, you should add this property).
|
|
|
|
### Setting options via URL
|
|
|
|
The same options from the "Setting options programmatically" section can be
|
|
set in the URL as follows:
|
|
|
|
```
|
|
.../svg-editor.html?dimensions=300,240&canvas_expansion=5&initFill[color]=0000FF
|
|
```
|
|
|
|
## Priority of programmatically-set config vs. URL config
|
|
|
|
If options are set both using `.setConfig()` as well as in the URL, the
|
|
`.setConfig()` value will be used (as of v2.7). (The reverse was true in
|
|
previous versions but was changed for security reasons.)
|
|
|
|
See section "Overwrite configuration" above on changing this behavior.
|
|
|
|
## Note to developers of SVGEdit on preferences vs. configuration
|
|
|
|
Those items marked as preferences are intended to be configuration items
|
|
which can also be set via the UI (and specifically via Editor Options
|
|
except where mentioned). Config and preferences should therefore not
|
|
share the same name.
|
|
|
|
There are, however, some items set in the UI which are currently
|
|
stored as config, whereas a few "preferences" are not meant to be set
|
|
by the user. A future version may adjust these types.
|
|
|
|
## Preloading a file
|
|
|
|
It is possible to start the editor with preloaded SVG file, using either
|
|
of the following approahces.
|
|
|
|
### Preload a file (Programmatically)
|
|
|
|
One should bear in mind that if one wishes to immediately set a
|
|
particular string regardless of previous saves by the user, especially when
|
|
from the config file (`svgedit-config-iife.js` in v3.0 or `editor/config.js`
|
|
in v2.8) which runs early, one should first set the config option
|
|
`noStorageOnLoad` to `true` or otherwise any
|
|
previous local storage that is found will overwrite your own string.
|
|
Bear in mind that if this option is set, the user will be prevented thereby
|
|
from saving their own text locally.
|
|
|
|
If you wish to store a one-time default and let the user subsequently save
|
|
locally, you do not need to set `noStorageOnLoad` as storage will only be
|
|
set if storage is found.
|
|
|
|
```js
|
|
// Serialized string:
|
|
svgEditor.loadFromString('<svg xmlns="...">...</svg>');
|
|
|
|
// Data URI:
|
|
svgEditor.loadFromDataURI('data:image/svg+xml;base64,...');
|
|
|
|
// Local URL:
|
|
svgEditor.loadFromURL('images/logo.svg');
|
|
```
|
|
|
|
### Preload a file (by URL)
|
|
|
|
As a URL parameter, one can pre-load an SVG file in the following manner:
|
|
|
|
```js
|
|
// Data URI
|
|
location.href += '?source=' + encodeURIComponent('data:image/svg+xml;utf8,' + svgText);
|
|
|
|
// Data URI (base 64):
|
|
location.href += '?source=' + encodeURIComponent('data:image/svg+xml;base64,' + svgTextAsBase64); // data%3Aimage%2Fsvg%2Bxml%3Bbase64%2C ...
|
|
|
|
// Local URL:
|
|
location.href += '?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.
|
|
<!-- Todo: Is this still occurring? -->
|
|
|
|
## Customizing stylesheets
|
|
|
|
As of version 3.0, stylesheets can be indicated dynamically (and
|
|
asynchronously loaded though applied serially) via
|
|
`svgEditor.setConfig({stylesheets: [...]})`.
|
|
|
|
To add your own stylesheets along with the default stylesheets, ensure
|
|
`"@default"` is present in the array along with your own. For example:
|
|
|
|
```js
|
|
svgEditor.setConfig({ stylesheets: [ '@default', 'myStylesheet.css' ] });
|
|
```
|
|
|
|
(In version 2.8, the CSS file `editor/custom.css` was included by default,
|
|
whether the file existed or not. With version 3.0, the move was made to
|
|
be fully modular and let plugins add their default stylesheets to
|
|
`$.loadingStylesheets` which SVGEdit would load dynamically, so that HTML
|
|
would not need to indicate such style-information in a non-modular fashion.)
|