github/svgedit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- Security fix: 'extPath', 'imgPath', 'extIconsPath', 'canvgPath', 'langPath', 'jGraduatePath', and 'jspdfPath' were not being prevented

Browse Source 
- Breaking change: Rename "svgutils.js" to "utilities.js" (make in conformity with JSDoc module naming convention)
- Breaking change: Rename "svgedit.js" to "namespaces.js" (to make clear purpose and avoid confusing with editor)
- Breaking change: Rename "jquery-svg.js" to "jQuery.attr.js"
- Breaking change: Rename "jquery.contextMenu.js" to "jQuery.contextMenu.js"
- Breaking change: Rename "jquery.jpicker.js" to "jQuery.jPicker.js"
- Breaking change: Rename "JQuerySpinBtn.css" to "jQuery.SpinButton.css"
- Breaking change: Rename "JQuerySpinBtn.js" to "jQuery.SpinButton.js" (to have file name more closely reflect name)
- Breaking change: Rename "jquery.svgicons.js" to "jQuery.svgIcons.js"
- Breaking change: Rename "jquery.jgraduate.js" to "jQuery.jGraduate.js"
- Breaking change: Rename "pathseg.js" to "svgpathseg.js" (as it is a poyfill of SVGPathSeg)
- Breaking change: Rename `addSvgElementFromJson()` to `addSVGElementFromJson` for consistency
- Breaking change: Rename `changeSvgContent()` to `changeSVGContent()` for consistency
- Breaking change: Have `exportPDF` resolve with `output` and `outputType` rather than `dataurlstring` (as type may vary)
- Breaking change: Rename `extensions/mathjax/MathJax.js` to `extensions/mathjax/MathJax.min.js`
- Breaking change: Avoid recent change to have editor ready callbacks return Promises (we're not using and advantageous to keep sequential)
- Breaking change: Avoid recent addition of locale-side function in ext-imagelib for l10n
- Breaking change: Change name of ext-arrows.js from `Arrows` to `arrows` for sake of file path (not localized anyways).
- Breaking change: Change `addlangData` extension event to `addLangData` for consistency with method name
- Breaking change: Have `readLang`  return lang and data but do not call `setLang`
- Fix: Have general locales load first so extensions may use
- Fix: Provide `importLocale` to extensions `init` so it may delay adding of the extension until locale data loaded
- Fix: Ensure call to `rasterExport` without `imgType` properly sets MIME type to PNG
- Fix: Wrong name for moinsave
- Update: Update WebAppFind per new API changes
- Enhancement: Make `setStrings` public on editor for late setting (used
  by `ext-shapes.js`)
- Enhancement: Add `extensions_added` event
- Enhancement: Add `message` event (Relay messages including those which
  have been been received prior to extension load)
- Enhancement: Allow SVGEdit to work out of the box--avoid need for copying sample config file. Should also help with Github-based file servers
- Enhancement: Allow avoiding "name" in extension export (just extract out of file name)
- Enhancement: Add stack blur to canvg by default (and refactoring it)
- Enhancement: Return `Promise` for `embedImage` (as with some other loading methods)
- Enhancement: Supply `importLocale` to `langReady` to facilitate extension locale loading
- Enhancement: Recover if an extension fails to load (just log and otherwise ignore)
- Enhancement: More i18n of extensions (also fixed issue with some console warnings about missing locale strings); i18nize Hello World too
- Enhancement: Allowing importing of locales within `addLangData`
- npm: Update devDeps
- Docs: Migrate copies of all old wiki pages to docs/from-old-wiki folder; intended for a possible move to Markdown, so raw HTML (with formatting) was not preserved, though named links had their absolute URL links preserved
- Docs: Begin deleting `SvgCanvas.md` as ensuring jsdoc has replacements
- Docs: Add Edtior doc file for help to general users
- Docs: Clarify/simplify install instructions
- npm/Docs (JSDoc): Add script to check for overly generic types
- Docs (JSDoc): For config/prefs and extension creating, link to tutorials (moved tutorials to own directory to avoid recursion problems by jsdoc)
- Docs (JSDoc): Add modules (upper case for usual main entrance files or regular names)
- Docs (JSDoc): Fill out missing areas; indicate return of `undefined`; consistency with `@returns`
- Docs (JSDoc): Add our own layout template to support overflow
- Docs (JSDoc): Use cleverLinks and disallow unknown tags
- Docs (JSDoc): Insist on "pedantic" flag; put output directory in config
- Docs (JSDoc): Use more precise Integer/Float over number, the specific type of array/function/object
- Docs (JSDoc): Use `@throws`, `@enum`, `@event`/`@fires`/`@listens`
- Docs: Generally update/improve docs (fixes #92)
- Docs: Update links to `latest` path (Avoid needing to update such references upon each release)
- Docs: 80 chars max
- Refactoring: Drop code for extension as function (already requiring export to be an object)
- Refactoring: Object destructuring, `Object.entries`, Object shorthand, array extras, more camelCase variable names
- Refactoring: Add a `Command` base class
- Refactoring: Simplify svgicons `callback` ready detection
- Refactoring: Put `let` or `const` closer to scope
- Refactoring: Remove unneeded `delimiter` from regex escaping utility
- Refactoring: Clearer variable names
- Refactoring: Use (non-deprecated) Event constructors
- Testing: Use new Sinon
This commit is contained in:
Brett Zamir
2018-06-06 15:26:20 +08:00
parent 057f5a5dc2
commit a3f0b8e501
334 changed files with 60808 additions and 16650 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/tutorials/CanvasAPI.md Normal file
View File

@@ -0,0 +1,20 @@
# Canvas
While the Canvas works with the [Editor]{@tutorial EditorAPI}, it can also
work on its own.
Its methods can be summarized here.
See also the [JSDocs entry for Canvas]{@link module:svgcanvas}.
## Exposed `svgCanvas` private methods and properties
These are supplied in an object supplied as the first parameter to each
extension function (see [ExtensionDocs]{@tutorial ExtensionDocs} for
an example and information).
See their [JSDocs API]{@link module:svgcanvas.PrivateMethods}.
## Canvas events
See [Events]{@tutorial Events} (under "Canvas events").

170
docs/tutorials/ConfigOptions.md Normal file
View File

@@ -0,0 +1,170 @@
# 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
'?source=' + encodeURIComponent('data:image/svg+xml;utf8,' + /*...*/);
// 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.
<!-- 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.)

21
docs/tutorials/Editor.md Normal file
View File

@@ -0,0 +1,21 @@
# Editor
This document is for detailing usage of the Editor by regular users (as
opposed to the [API of the Editor for programmers]{@tutorial EditorAPI}).
Until we may flesh this document out further, we may begin with tips on the
features which are more non-obvious as to usage (including for novices to
graphic design). Feel free to file an issue to request documentation on a
particular feature.
See also some possibly out-of-date documentation at
[FrequentlyAskedQuestions]{@tutorial FrequentlyAskedQuestions}.
## Paths
When working with a path (as created by the Path tool left ("mode")
toolbar item or "Convert to Path" in the "context" toolbar at the
top), chosen by the "Select" left-toolbar item, clicking the item once
will allow the normal resizing/rotation, and clicking the item again
will allow for independent manipulation of the path and display a
different context-dependent toolbar at the top of the screen.

11
docs/tutorials/EditorAPI.md Normal file
View File

@@ -0,0 +1,11 @@
# Editor API
This is an entry point that summarizes the documentation on the Editor.
For user-facing information about the Editor, see [Editor]{@tutorial Editor}.
The main API entrance point is with the [Editor JSDocs]{@link module:Editor}.
## Canvas-specific methods
See [Canvas]{@tutorial Canvas}.

128
docs/tutorials/Events.md Normal file
View File

@@ -0,0 +1,128 @@
# Introduction
## `save`, `open`, `exportImage` (`setCustomHandlers`)
You can hook to the save event (e.g. in an extension), to handle saving
the SVG file differently:
### Example
```js
svgEditor.setCustomHandlers({
save (win, data) {
// Save svg
}
});
```
Other methods corresponding to UI events that may be supplied are `open`
and `exportImage`.
See [`CustomHandler`]{@link module:SVGEditor.CustomHandler} for the required
format of the object to be passed to
[`setCustomHandlers`]{@link module:SVGEditor.setCustomHandlers}.
## Parent/Opening window events
### `svgEditorReady`
The `svgEditorReady` event is triggered on a containing `document` (of
`window.opener` or `window.parent`) when the editor is loaded.
See [svgEditorReadyEvent]{@link module:SVGEditor#event:svgEditorReadyEvent}
for the JSDocs.
### Example
```js
$(document).bind('svgEditorReady', function () {
const svg = `
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="50">
<ellipse cx="50" cy="25" rx="50" ry="25" style="fill:blue;"/>
</svg>`;
$('iframe.svgedit')[0].contentWindow.svgCanvas.setSvgString(svg);
});
```
If you are acting within the frame, you may use `svgEditor.ready`
(see [Within-frame events](#Editor-within-frame-events-svgEditor) below).
## Editor (within-frame) events (`svgEditor`)
### `svgEditor.canvas`
- Canvas object. See [Canvas events](#Canvas-events).
### `svgEditor.canvas.bind(eventName, function () {})`
- Method for listening to canvas events. See [Canvas events](#Canvas-events).
### `svgEditor.ready(function () {})`
Method for listening to editor callbacks. Used internally as well.
No arguments passed to callback.
See [`SVGEditor.ready`]{@link module:SVGEditor.ready}.
## Extension events
Most extensions will want to run functions when certain events are
triggered. This is a list of the current events that can be hooked
onto. All events are optional.
See the `vars` param of
[`runExtensions`]{@link module:svgcanvas.SvgCanvas#runExtensions}
for some of the available extension events and their descriptions and types.
See [`ExtensionStatus`]{@link module:svgcanvas.ExtensionStatus} for the
values to be returned by the corresponding extension methods listening
for these extension event types.
## Canvas events
Canvas events are listened to with the bind method
([JSDocs API]{@link module:svgcanvas.SvgCanvas#bind}):
```js
canvas.bind(eventName, callback);
```
Canvas events are passed between the editor and canvas and should mostly
only of be of interest to those working with the [Canvas]{@tutorial CanvasAPI}
alone or those developing SVGEdit).
`callback` (see [`EventHandler`]{@link module:svgcanvas.EventHandler}) will be passed the
`window` object and a single argument specific to the event
(see [`GenericCanvasEvent`]{@link module:svgcanvas.SvgCanvas#event:GenericCanvasEvent}).
The `bind` method will return any previous callback attached to the given
event name.
The method used to trigger these bound events is `call()`
([JSDocs]{@link module:svgcanvas.SvgCanvas#call}).
All events below are currently called from within `svgcanvas.js` except where
noted. All events are also defined internally within `svg-editor.js` except
where noted.
|Event|Where bound/defined (besides editor)|Where called/triggered (besides canvas)|
|-----|------------------------------------|-----------------------------|
|`changed` | | (Also called from `draw.js`, `ext-arrows.js`, `ext-foreignObject.js`, `ext-markers.js`, `ext-polygon.js`, `ext-star.js`, and `path.js`) |
|`cleared` | Not bound/defined in SVGEdit. | |
|`contextset` | | Only called from `draw.js`|
|`exported` | | |
|`exportedPDF` | | |
|`extension_added` | | |
|`extensions_added` | | Only called from `svg-editor.js` |
|`message` | Only bound/defined in `ext-webappfind.js` | Only called from `svg-editor.js` |
|`pointsAdded` | Not bound/defined in SVGEdit. | |
|`saved` | | |
|`selected` | | Also called from `path.js` |
|`setnonce` | Only bound/defined in `ext-arrows.js` | |
|`transition` | | |
|`updateCanvas` | | |
|`unsetnonce` | Only bound/defined in `ext-arrows.js` | |
|`zoomed` | | |
|`zoomDone` | | |

223
docs/tutorials/ExtensionDocs.md Normal file
View File

@@ -0,0 +1,223 @@
# Introduction
SVG-Edit has support for extensions (as of v2.5). This is a guide for
creating SVG-Edit extensions.
## Means to have extensions loaded
SVG-Edit extensions are standalone JavaScript files that can be either
included in the HTML file, loaded using `setConfig`, or indicated through
the URL (see [ConfigOptions]{@tutorial ConfigOptions} for usage).
Note that, as of v3.0, if you create a `svgedit-config-iife.js` file in
the project root directory (`config.js` in the `editor` directory for
v2.8), this will be used to execute commands before extensions are loaded,
e.g., if you wish to make configuration changes which affect extension
loading behavior. Normally, however, it should be preferable for modularity
to use the extension mechanism, as this can allow you or users to customize
which extensions are loaded (whereas `svgedit-config-iife.js` will always
run if present).
## Basic format
This is the general format for an extension:
```js
export default {
name: 'extensionname',
init (methods) {
return extensionData;
}
};
```
Extensions must export an object. (For the API docs of this object, see
[ExtensionObject]{@link module:SVGEditor.ExtensionObject}.)
The first property on the object exported above, `name`, is the unique
ID for this extension. It can actually be omitted, in which case the
ID (not shown visually) will instead be determined from the file name
(omitting the initial "ext-" and ending ".js"). These are not displayed
visually, so the only purpose is to avoid name conflicts with other
extensions.
The other property above (`init`) is a function (see
[`ExtensionInitCallback`]{@link module:svgcanvas.ExtensionInitCallback}
for its API) that is supplied methods and variables from svgCanvas (see
[`ExtensionArgumentObject`]{@link module:svgcanvas.ExtensionArgumentObject})
and can return an object that includes properties and functions that may
be required for further processing by
the extension, depending on the type of methods desired by the extension
being added. See [`ExtensionInitResponse`]{@link module:svgcanvas.ExtensionInitResponse}
for API documentation on the response type(s) available for `init`.
Its `this` value is bound to the editor, so
[those methods]{@link module:SVGEditor} are also available.
In order to await execution of set-up such as calls to `langReady` and
`svgIcons`, the callback `callback` can be added to the object returned with
the call to `init`. The callback is invoked upon addition of the extension,
or, if svgicons are set, then after the icons are ready. See
[`ExtensionInitResponse#callback`]{@link module:svgcanvas.ExtensionInitResponse#callback}
in the API for more on this.
## Example
The basic Hello world extension (in `/editor/extensions/ext-helloworld.js`)
can be seen as an example on how to create a basic extension. This extension
adds a "mode" button to the bottom of the left panel that changes the mode,
then shows a "Hello world" message whenever the canvas is clicked on. See
[extension in action](https://svg-edit.github.io/svgedit/releases/latest/editor/svg-editor.html?extensions=ext-helloworld.js).
The basic structure of this extension looks like this:
```js
export default {
name: 'helloworld',
init () {
return {
svgicons: 'extensions/helloworld-icon.xml',
buttons: [{...}],
mouseDown () {
...
},
mouseUp (opts) {
...
}
};
}
};
```
Note how the returned properties may include information on the buttons,
as well as the functions that should be run when certain events take place.
The "Hello World" extension also demonstrates internationalization (see
the next section).
## Internationalization of extensions
The locale files for extensions (which need translation as with the main
locales) are hosted in `editor/extensions/ext-locale/<ext name>/`.
Both `addLangData`
([JSDocs]{@link module:svgcanvas.ExtensionInitResponse#addLangData})
(invoked early)
and `langReady`
([JSDocs]{@link module:svgcanvas.ExtensionInitResponse#langReady})
are passed objects with an `importLocale` function
([JSDocs]{@link module:SVGEditor~ImportLocale}) that you can use to
import your own extension locales hosted in the above-mentioned directory.
The `importLocale` function will use the detected locale and detected
extension name by default (no need for arguments), and returns a
`Promise` that will resolve to the locale strings found within a
file you place at:
`${svgEditor.curConfig.extPath}ext-locale/<extNameWithoutExtPrefix>/<lang>.js`
(`<lang>` is the detected `lang` returned on
[`langReady`]{@link module:SVGEditor.ExtensionVars_langReady} and
`<extNameWithoutExtPrefix>` is your extension name without the initial
required "ext-" prefix and without the trailing ".js").
The resolved `Promise` value is expected to adhere to
[`LocaleStrings`]{@link module:locale.LocaleStrings} (as with SVGEdit's
global locale files).
You could also use your own means to store and retrieve locale data for
your extension (and
[`importSetGlobalDefault`]{@link module:importModule.importSetGlobalDefault}
is available should this be of assistance) in which case the `global`
property should follow the format
`svgEditorExtensionLocale_<extNameWithoutExtPrefix>_<lang>` to avoid global
naming conflicts in the non-modular version of SVGEdit.
```js
import {importSetGlobalDefault} from '../external/dynamic-import-polyfill/importModule.js';
// ...
(async () => {
const url = `${svgEditor.curConfig.extPath}ext-locale/<extNameWithoutExtPrefix>/<lang>.js`;
const localeStrings = await importSetGlobalDefault(url, {
global: 'svgEditorExtensionLocale_imagelib_' + lang
});
// Use `localeStrings`
})();
```
In addition to your own extension's locale strings,
[`langReady`]{@link module:svgcanvas.ExtensionInitResponse#langReady}
also has access to the global internationalization strings through the
`uiStrings` property on the object passed to it (see
[event:ext-langReady]{@link module:svgcanvas.SvgCanvas#event:ext-langReady}).
See also [LocaleDocs]{@tutorial LocaleDocs}, including for information on
formatting of locale strings (the current lack of any standard beyond a
convention of using brackets for variables).
## Creating buttons
Buttons can appear either in the "mode" panel (left panel) or the "context"
panel (top panel, changes depending on selection). Their icons can
either consist of SVG icons (recommended) or just raster images.
Each button is an object (added to the
array "buttons" on the object returned by the extension's `init` method).
Its properties are outlined at
[`SVGEditor.Button`]{@link module:SVGEditor.Button}.
## Creating SVG icons
The SVG-Edit project uses icons created using basic SVG (generally
using SVG-Edit as design tool), and extensions are encouraged to do so
too. This allows the interface toolbars to be resized and icons to be
reused at various sizes. If your extension uses multiple icons, they can
all be stored in the same file. To specify icon file used, set the path
under the extension's returned `svgicons` property.
An SVG icon file is an XML document that consists of a root SVG element
with child group elements (`<g></g>`). Each of these has an ID that
should match the ID specified in the associated button object.
Its content should be the SVG source of the icon. See the "Hello World"
icon as an example.
For further information, see the SVG Icon Loader project.
## Creating context tools
Context tools appear in the top toolbar whenever a certain type of
element is selected.
These are added by the extension returning an object with the
property "context_tools". See [this object's API]{@link module:SVGEditor.ContextTool}
for details.
## SVG-Edit extension events
See [Events]{@tutorial Events} for the events that lead to the triggering
of extension callbacks. (Mostly of relevance for developers of SVGEdit itself.)
## Helpers
A variety of properties and methods can be accessed within extensions.
### `svgCanvas` properties and methods
These are supplied in an object through the first parameter of the
extension function (see "methods" variable in above example).
See
[`ExtensionArgumentObject`]{@link module:svgcanvas.ExtensionArgumentObject}.
Note that this object also has these
[surfaced private methods and properties from Canvas]{@link module:svgcanvas.PrivateMethods}.
### `svgEditor` public properties and methods
The `this` value of the `init`
([JSDocs]{@link module:svgcanvas.ExtensionInitCallback}) method
is the [Editor object]{@link module:SVGEditor}. Its methods may be invoked
from on `this` within that method.

89
docs/tutorials/FrequentlyAskedQuestions.md Normal file
View File

@@ -0,0 +1,89 @@
**NOTE: The following may contain outdated content.**
**Q: Why doesn't SVG-edit work in Internet Explorer 6-7-8?**
A: SVG-edit only works in IE6-7-8 if you have installed the Google Chrome
Frame plugin. Internet Explorer 8 and under do not natively support Scalable
Vector Graphics (SVG), however IE9+ does, and thus is supported starting
in SVG-edit 2.6
In theory there are several other possibilities that could allow SVG-edit
to work in IE:
* someone gets it to work with the SVG Web shim
* someone gets it to work with IE and the Adobe SVG Viewer
* someone gets it to work with another SVG plugin
**Q: How can I make SVG-edit save files on my server?**
A: As of SVG-edit 2.5.1, an extension is available that overrides the
default open/save behavior and instead uses PHP files to allow proper
open/save dialog boxes. You can include the extension by adding
`ext-server_opensave.js` to the `curConfig.extension` array in
`svg-editor.js` or through other methods mentioned on our ConfigOptions page.
For other server-saving behavior you'll want to modify
`ext-server_opensave.js` or the `filesave.php` file, both available
under `editor/extensions/`.
**Q: How can I set the stroke to 'none'?**
A: Shift-clicking palette squares sets the Stroke paint value. Thus,
you can `shift-click` on the None box (red x on white background) to
clear the Stroke paint.
**Q: How can I help?**
A: See How to participate
**Q: How can I select an element when it's hidden or behind another one?**
A: Select an object. `Shift+O` will select the previous object `Shift+P`
will select the next object. Using the wireframe mode may also help in
seeing hidden objects.
**Q: How can I edit shapes that have been grouped?**
A: Double-click the group and you will shift the editing context to the
group. The rest of the image will not be editable while you are in the
group context. Once you are done editing inside the group, press Escape.
**Q: Can I trace over a raster (PNG, JPEG...) image?**
A: Yes, there are two methods you can use as of SVG-edit 2.4.
1. Go to the Document Properties, and enter the URL of the image under
"Editor Background". This image will then fill the background without
being saved as part of the image.
1. Add a layer from the layer panel. Then draw a raster image (image icon)
and enter your URL. Use the layer above this one to trace over the image
without moving. Note that you can also hide/show layers to help your work.
**Q: How do I use the Wave Gadget?**
A: (Note that this information refers to the SVG-edit 2.3 Wave Gadget,
the Wave Gadget has not been worked on for years though) Go to this wave
wavesandbox.com!w+W7VzCLZk%A and there will be a button on the bottom
that says "Install" and when you are editing things, you will see a
SVG-edit icon in your toolbar that you can click to include the gadget
into any blip.
**Q: How do I copy the style of an object to other(s)?**
A:
- Select the object you want to copy the style from. You'll see its Fill and
Stroke style attributes displayed in the bottom toolbar.
- Holding Shift to keep the first object selected, select one or several
other objects.
- Open the colorpicker by clicking on the color blocks in the bottom
toolbar. If you want to copy the fill, select the Fill block. If you
want to copy the stroke, select the Stroke block.
- Hit "Ok" in the colorpicker
The other objects will get the Fill or the Stroke of the first object.
**Q: How can I serve SVG graphic editor from my own server?**
A: You need to download the latest version to your server and unzip.
The exact commands/instructions are here: <http://howik.com/Improve_your_user%27s_experience_by_adding_svg_graphic_editor_to_your_website_in_less_than_2_minutes>

43
docs/tutorials/LocaleDocs.md Normal file
View File

@@ -0,0 +1,43 @@
# Introduction
As of v3.0, locale files are defined as an object exported as
an ES6 Module default. See `editor/locale` for some example files.
(In previous versions, the locale files were required to call
`svgEditor.readLang`.)
## Expected format
You may also see the [LocaleStrings API]{@link module:locale.LocaleStrings}
for the programmatic definition of the expected object (i.e., an object of
strings and a potential recursion of other such subobjects or an array of
strings and such objects). This is true for extenions as well.
However, we are not currently processing any formatting of such strings
(besides using the convention of using brackets to surround variables
`{variableToSubstitute}`). In the absence of such, you may wish to use
your own formatting such as with
[Fluent.js](https://github.com/projectfluent/fluent.js).
While it is possible we may move to accept JSON in future versions
(to avoid maintainers needing to worry about JavaScript execution),
the ES6 Modules export allows for cleaner objects; there is no need for
quoted keys when alphanumeric keys are used, and there is the opportunity
to use less-distracting single quotes if not
[ES6 Template Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)).
## Special properties
While not currently in use, the `dir` property should be used to indicate
the default directionality of the language of the locale, while the `lang`
should define its HTML `lang` value (which should probably always be the
same as "<lang>" within the "lang.<lang>.js" file name).
## Location of locale files (including for extensions)
While `editor/locale` hosts the main locale files, internationalizable
extensions define their own locale files (better supporting modularity). In
our project, these can be found within `editor/extensions/ext-locale/<ext name>/`.
See [ExtensionDocs]{@tutorial ExtensionDocs} if you are implementing an
internationalized extension.

17
docs/tutorials/tutorials.json Normal file
View File

@@ -0,0 +1,17 @@
{
"ExtensionDocs": {
"title": "Extension Docs"
},
"ConfigOptions": {
"title": "Config Options"
},
"Editor": {
"children": ["ConfigOptions", "ExtensionDocs", "LocaleDocs"]
},
"FrequentlyAskedQuestions": {
"title": "Frequently Asked Questions (FAQ)"
},
"LocaleDocs": {
"title": "Locale Docs"
}
}