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

- Docs (3.0.0): Clarify

master
Brett Zamir 2018-10-26 08:08:26 +08:00
parent 5c96501507
commit 126b2cb840
2 changed files with 62 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES.md
View File

@ -1,5 +1,6 @@
# ?
- Docs (3.0.0): Clarify
- Docs (ReleaseInstructions): Clarify need for npm permissions to publish
# 3.1.1

103
docs/versions/3.0.0.md
View File

@ -50,29 +50,29 @@ For ES6 Modules being available as a distribution option, see "Enhancements".
##### Design choices for applying modules (Technical)
The jQuery files have not been added in ES6 Modules format, however, because
they do not have such a distribution and adding an import in source would
require compilation whereas we'd like the modular file to work without
compilation for faster debugging (note that rather than importing our
external npm dependencies directly from `node_modules`, we have a `copy-deps`
script for copying these files into our repository, so experimenting on
these files should probably be done within the `editor/external` directory,
though such changes should not be committed unless the source packages
are also updated and the `copy-deps` routine brings them in).
they do not have such a distribution and adding an import in source which
converts them to ES6 Modules through plugin would require compilation
whereas we'd prefer that at least the modular editor file be able to work
without compilation for faster debugging (note, however, that rather than
importing our external npm dependencies directly from `node_modules`, we
have a `copy-deps` script for copying these files into our repository, so
experimenting on these files should probably be done within the
`editor/external` directory and such changes must not be committed unless
the source packages are also updated and the `copy-deps` routine brings them
in).
The file `redirect-on-lacking-support.js` has not been bundled with the main
`svgedit-config-es.js` script so that browsers not supporting SVG are
redirected faster (and, in the same vein as polyfills, it may be more
logically consistent to add this externally anyways).
logically consistent to add this external to the main code anyways).
The `redirect-on-no-module-support.js`, which redirects when module
support is not available, is not bundled for the same essential reason.
The file `redirect-on-no-module-support.js`, which redirects when module
support is not available, is not bundled for the same type of reason.
#### JavaScript config file breaking changes
In place of looking for `config.js` in the `editor` directory,
Unlike version 2.8.1 which had a `config-sample.js` file which needed
to be copied to `config.js` in the same directory, in version 3.0.0,
to be copied to `config.js` in the same `editor` directory, in version 3.0.0,
things work out of the box by pointing to the pre-built config files (also
an advantage for our use of Github-based project hosts like
raw.githack.com), but these config files have been moved out of the
@ -80,11 +80,29 @@ raw.githack.com), but these config files have been moved out of the
if using the editor within our repository).
These files also now have different names (`svgedit-config-es.js`
for `svg-editor-es.html` and `svgedit-config-iife.js` for `svg-editor.html`).
for `svg-editor-es.html` and `svgedit-config-iife.js` for `svg-editor.html`)
for a measure of namespacing.
This move is intended to allow config to be stored semi-independently
of editor files.
Also note that while the config file was optional in 2.8.1, the config
file in 3.* includes (or for, the ES version, imports) all of the main
SVG-Edit code, so the file (or one like it) cannot be omitted. This has
the advantage of avoiding an extra script tag and for the non-ES version,
an extra HTTP request. But if you are working with the non-modular HTML
and are not running the build routines to compile ES to non-modular
JavaScript, you will be required to directly modify your config within
the large non-modular, bundled JavaScript config file that includes most
of the SVG codebase.
The build routines include `npm run build-config` to convert the
JavaScript config to non-modular form, `npm run rollup` to convert the other
source files to non-modular form, and `npm run build-html` to build the
non-modular HTML out of the modular HTML (all of these are run during
`npm run test-prep`, or if you want to run the tests, also as a part of
`npm test` and `npm run browser-test`).
#### Stylesheet breaking changes
In version 2.8.1, one could place a `custom.css` file in the same directory
@ -96,7 +114,7 @@ and is expected as `svgedit-custom.css`.
You may change the stylesheets which are loaded by changing the default
JavaScript stylesheet config (see the
"JavaScript config file breaking changes" section for the location of
these files). The default is:
these files). The default behavior is equivalent to this:
```js
svgEditor.setConfig({
@ -104,7 +122,7 @@ svgEditor.setConfig({
});
```
...which indicates it will load all default stylesheets and then
...which indicates that all default stylesheets will be loaded and then
one's custom file. You may omit either of these and/or add your own.
See "Other breaking changes -> HTML" for removal of the "scoped"
@ -119,26 +137,28 @@ and in order to avoid path resolution problems, the config properties
`extPath` and `langPath` now have different defaults, depending
on whether a module environment is detected or not.
The non-modular versions will now default to "../dist/extensions/" and
"../dist/locale/", respectively, whereas the modular version will use the
old default paths ("extensions/" and "locale/").
The non-modular versions will now default to `../dist/extensions/` and
`../dist/locale/`, respectively, whereas the modular version will use the
old default paths (`extensions/` and `locale/`).
Also, since we have not copying extension icons over to `dist` and the path
resolution of extension icons would otherwise break, we have now added new
config `extIconsPath`, distinct from `extPath`, which points by default to
"extensions/" for both modular and non-modular environments.
a config property, `extIconsPath`, distinct from `extPath`, which points
by default to `extensions/` for both modular and non-modular environments.
And because canvg and jspdf are now building from module and would break as
a result of this move as well, we have added the config `canvgPath` and
`jspdfPath` which default respectively to "canvg/" and "jspdf/" for modular
loads and to "../dist/" for both path types with non-modular loads.
And because our dependencies canvg and jspdf are now building from module
and would break as a result of this move as well, we have added the config
`canvgPath` and `jspdfPath` which default respectively to `canvg/` and
`jspdf/` in modular loads and to `../dist/` for both path types within
non-modular loads.
(`imgPath` and `jGraduatePath` remain unchanged since they, as with
`extIconsPath`, are not looking for module-only files.)
`extIconsPath`, are not looking for module-expressed files.)
#### Locale breaking changes
Locale files are now formatted as ES6 Module exports.
Locale files are now formatted as ES6 Module exports (rather than as
calls to `svgEditor.readLang`).
In order for their value to be discovered when compiled and loaded
in a non-modular context, in such contexts they will be auto-defined
@ -146,22 +166,21 @@ as global variables (as "svgEditorLang_" followed by the
locale file name with any hyphens replaced as underscores).
In the spirit of modularization and only loading what is needed,
locale strings pertaining solely to extensions were moved to
locale strings pertaining solely to extensions were moved to
`editor/extensons/ext-locale/<extension name>/<language code>.js`.
A new method, `importLocale`, is passed to extensions
(see "Summary of enhancements -> APIs") which can load locale files
within this hierarchy, requiring no arguments if relying on the detected
locale.
A new method, `importLocale`, is passed to extensions (see
"Summary of enhancements -> APIs") which can load locale files within
this hierarchy, requiring no arguments if relying on the detected locale.
The `npm run rollup` routine (also a part of `npm test`) will build
any properly named and formatted ES6 Modules locale file into a non-modular
file within `dist/locale`.
The `npm run rollup` routine (also a part of `npm run test-prep` or
the full test routines) will build any properly named and formatted ES6
Modules locale file into a non-modular file within `dist/locale`.
#### Extension breaking changes
Extension files are now formatted as ES6 Module exports rather than as
calls to `svgEditor.addExtension`. The latter may still be used, but
Extension files are now formatted as ES6 Module exports (rather than as
calls to `svgEditor.addExtension`). The latter may still be used, but
support for passing an object (with a `callback` method as an init function)
is not (`callback` may be present on the *return* object of extension `init`
method, however).
@ -178,15 +197,15 @@ only used as a unique identifier).
Any init function previously supplied as second argument to `addExtension`
should be expressed as an `init` method on the object exported by the
extension and it should return what the init function had been returning.
extension, and it should return what the init function had been returning.
Its `this` value will be set to the editor object.
For the object returned by `init`, invocation of any `callback` method
will also be invoked with the `this` value set to the editor object.
The `npm run rollup` routine (also a part of `npm test`) will build
any properly named and formatted ES6 Modules extension file into a non-modular
file within `dist/extensions`.
The `npm run rollup` routine (also a part of `npm run test-prep` or
the full test routines) will build any properly named and formatted ES6
Modules extension file into a non-modular file within `dist/extensions`.
See also "Locale breaking changes".