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 - Docs (ReleaseInstructions): Clarify need for npm permissions to publish
# 3.1.1 # 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) ##### Design choices for applying modules (Technical)
The jQuery files have not been added in ES6 Modules format, however, because 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 they do not have such a distribution and adding an import in source which
require compilation whereas we'd like the modular file to work without converts them to ES6 Modules through plugin would require compilation
compilation for faster debugging (note that rather than importing our whereas we'd prefer that at least the modular editor file be able to work
external npm dependencies directly from `node_modules`, we have a `copy-deps` without compilation for faster debugging (note, however, that rather than
script for copying these files into our repository, so experimenting on importing our external npm dependencies directly from `node_modules`, we
these files should probably be done within the `editor/external` directory, have a `copy-deps` script for copying these files into our repository, so
though such changes should not be committed unless the source packages experimenting on these files should probably be done within the
are also updated and the `copy-deps` routine brings them in). `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 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 `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 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 The file `redirect-on-no-module-support.js`, which redirects when module
support is not available, is not bundled for the same essential reason. support is not available, is not bundled for the same type of reason.
#### JavaScript config file breaking changes #### 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 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 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 an advantage for our use of Github-based project hosts like
raw.githack.com), but these config files have been moved out of the 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). if using the editor within our repository).
These files also now have different names (`svgedit-config-es.js` 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 This move is intended to allow config to be stored semi-independently
of editor files. 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 #### Stylesheet breaking changes
In version 2.8.1, one could place a `custom.css` file in the same directory 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 You may change the stylesheets which are loaded by changing the default
JavaScript stylesheet config (see the JavaScript stylesheet config (see the
"JavaScript config file breaking changes" section for the location of "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 ```js
svgEditor.setConfig({ 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. 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" 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 `extPath` and `langPath` now have different defaults, depending
on whether a module environment is detected or not. on whether a module environment is detected or not.
The non-modular versions will now default to "../dist/extensions/" and The non-modular versions will now default to `../dist/extensions/` and
"../dist/locale/", respectively, whereas the modular version will use the `../dist/locale/`, respectively, whereas the modular version will use the
old default paths ("extensions/" and "locale/"). old default paths (`extensions/` and `locale/`).
Also, since we have not copying extension icons over to `dist` and the path 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 resolution of extension icons would otherwise break, we have now added new
config `extIconsPath`, distinct from `extPath`, which points by default to a config property, `extIconsPath`, distinct from `extPath`, which points
"extensions/" for both modular and non-modular environments. 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 And because our dependencies canvg and jspdf are now building from module
a result of this move as well, we have added the config `canvgPath` and and would break as a result of this move as well, we have added the config
`jspdfPath` which default respectively to "canvg/" and "jspdf/" for modular `canvgPath` and `jspdfPath` which default respectively to `canvg/` and
loads and to "../dist/" for both path types with non-modular loads. `jspdf/` in modular loads and to `../dist/` for both path types within
non-modular loads.
(`imgPath` and `jGraduatePath` remain unchanged since they, as with (`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 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 order for their value to be discovered when compiled and loaded
in a non-modular context, in such contexts they will be auto-defined 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). locale file name with any hyphens replaced as underscores).
In the spirit of modularization and only loading what is needed, 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`. `editor/extensons/ext-locale/<extension name>/<language code>.js`.
A new method, `importLocale`, is passed to extensions A new method, `importLocale`, is passed to extensions (see
(see "Summary of enhancements -> APIs") which can load locale files "Summary of enhancements -> APIs") which can load locale files within
within this hierarchy, requiring no arguments if relying on the detected this hierarchy, requiring no arguments if relying on the detected locale.
locale.
The `npm run rollup` routine (also a part of `npm test`) will build The `npm run rollup` routine (also a part of `npm run test-prep` or
any properly named and formatted ES6 Modules locale file into a non-modular the full test routines) will build any properly named and formatted ES6
file within `dist/locale`. Modules locale file into a non-modular file within `dist/locale`.
#### Extension breaking changes #### Extension breaking changes
Extension files are now formatted as ES6 Module exports rather than as Extension files are now formatted as ES6 Module exports (rather than as
calls to `svgEditor.addExtension`. The latter may still be used, but calls to `svgEditor.addExtension`). The latter may still be used, but
support for passing an object (with a `callback` method as an init function) 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` is not (`callback` may be present on the *return* object of extension `init`
method, however). method, however).
@ -178,15 +197,15 @@ only used as a unique identifier).
Any init function previously supplied as second argument to `addExtension` Any init function previously supplied as second argument to `addExtension`
should be expressed as an `init` method on the object exported by the 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. Its `this` value will be set to the editor object.
For the object returned by `init`, invocation of any `callback` method For the object returned by `init`, invocation of any `callback` method
will also be invoked with the `this` value set to the editor object. 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 The `npm run rollup` routine (also a part of `npm run test-prep` or
any properly named and formatted ES6 Modules extension file into a non-modular the full test routines) will build any properly named and formatted ES6
file within `dist/extensions`. Modules extension file into a non-modular file within `dist/extensions`.
See also "Locale breaking changes". See also "Locale breaking changes".