This repository has been archived by the owner on Apr 11, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 31
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(middleware): Add 'symbolMiddleware' and 'symbolInstanceMiddlewar…
…e' (#52)
- Loading branch information
1 parent
fe80e6a
commit 5818868
Showing
14 changed files
with
3,425 additions
and
104 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -120,6 +120,48 @@ $ html-sketchapp --viewports.HigherDensity [email protected] --viewports.Retina 1024x | |
|
|
||
| If no scaling factor is provided, a default of `1` will be used. | ||
|
|
||
| ### Config file | ||
|
|
||
| All options can be provided via an `html-sketchapp.config.js` file. | ||
|
|
||
| ```js | ||
| module.exports = { | ||
| file: 'sketch.html', | ||
| outDir: 'dist/sketch', | ||
| viewports: { | ||
| Desktop: '1024x768', | ||
| Mobile: '320x568' | ||
| }, | ||
| puppeteerArgs: '--no-sandbox --disable-setuid-sandbox', | ||
| puppeteerExecutablePath: 'google-chrome-unstable' | ||
| }; | ||
| ``` | ||
|
|
||
| You can provide an alternate config file path with the `--config` option. | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --config example.config.js | ||
| ``` | ||
|
|
||
| ### Importing into Sketch | ||
|
|
||
| Once this command has successfully run, the following files will be generated in the output directory. | ||
|
|
||
| - `document.asketch.json` | ||
| - `page.asketch.json` | ||
|
|
||
| These need to be imported into Sketch via html-sketchapp's corresponding Sketch plugin. To ease the install process, you can run the following command. | ||
|
|
||
| ```bash | ||
| $ html-sketchapp install | ||
| ``` | ||
|
|
||
| Then, open a new Sketch document and, from the menu, select `Plugins > From *Almost* Sketch to Sketch`. In the file picker, select both `document.asketch.json` and `page.asketch.json`, and click `Choose`. | ||
|
|
||
| Congratulations! You should now have your symbols, text styles and document colors available within Sketch! 💎🎉 | ||
|
|
||
| ## Advanced Usage | ||
|
|
||
| ### Debug mode | ||
|
|
||
| If you need to see what Puppeteer is doing, you can provide the `--debug` flag which will do the following things: | ||
|
|
@@ -134,59 +176,75 @@ For example: | |
| $ html-sketchapp --url http://localhost:3000 --out-dir dist --debug | ||
| ``` | ||
|
|
||
| ### Symbol Layer Middleware | ||
| ### Puppeteer args | ||
|
|
||
| Symbol Layer Middleware allows you to call out to any APIs that may be exposed on the underlying html-sketchapp layer. | ||
| If you need to provide command line arguments to the browser instance via [Puppeteer](https://github.com/GoogleChrome/puppeteer), you can provide the `puppeteer-args` option. | ||
|
|
||
| The current usecase for this is the new `layer.setResizingConstraint` API which allows you to configure how a layer should behave when a symbol is resized. | ||
| Since Puppeteer uses [Chromium](https://www.chromium.org/Home) internally, you can refer to the [List of Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches) for available options. | ||
|
|
||
| #### Requiring a file | ||
| For example, if you'd like to disable the browser sandbox: | ||
|
|
||
| The below uses the string argument to `require` in a file that defines what resizing a layer should have applied to it. In the below case, fixing the layer to the top and left. | ||
| ```bash | ||
| $ html-sketchapp --puppeteer-args="--no-sandbox --disable-setuid-sandbox" --file sketch.html --out-dir dist | ||
| ``` | ||
|
|
||
| *Note: Because Puppeteer args are prefixed with hyphens, you **must** use an equals sign and quotes when providing this option via the command line (as seen above).* | ||
|
|
||
| ### Chromium executable | ||
|
|
||
| If you'd like to override the Chromium used by Puppeteer, you can provide a path to the executable with the `puppeteer-executable-path` option. | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --symbol-layer-middleware symbol.layer.middleware.js | ||
| $ html-sketchapp --puppeteer-executable-path google-chrome-unstable --file sketch.html --out-dir dist | ||
| ``` | ||
|
|
||
| ```js | ||
| module.exports = (args) => { | ||
| const { layer, RESIZING_CONSTRAINTS } = args; | ||
| ### Middleware | ||
|
|
||
| layer.setResizingConstraint(RESIZING_CONSTRAINTS.LEFT, RESIZING_CONSTRAINTS.TOP); | ||
| If you need to call out to lower-level html-sketchapp APIs, you can provide middleware functions that allow you to modify the underlying Sketch classes as they're generated. | ||
|
|
||
| It's recommended that you provide middleware via a [config file](#config-file) as inline functions, for example: | ||
|
|
||
| ```js | ||
| module.exports = { | ||
| symbolLayerMiddleware: (args) => { ... } | ||
| }; | ||
| ``` | ||
|
|
||
| #### Inline function | ||
|
|
||
| If you use the config file you can provide an inline function and avoid creating a separate file: | ||
| Alternatively, you can also provide middleware as standalone JavaScript files, configured via the command line: | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --config config.js | ||
| $ html-sketchapp --symbol-layer-middleware symbol.layer.middleware.js | ||
| ``` | ||
|
|
||
| ```js | ||
| module.exports = { | ||
| symbolLayerMiddleware: (args) => { | ||
| const { layer, RESIZING_CONSTRAINTS } = args; | ||
| This assumes that your middleware is a JavaScript module that exports the function: | ||
|
|
||
| layer.setResizingConstraint(RESIZING_CONSTRAINTS.LEFT, RESIZING_CONSTRAINTS.TOP); | ||
| } | ||
| }; | ||
| ```js | ||
| module.exports = (args) => { ... }; | ||
| ``` | ||
|
|
||
| #### Symbol layer middleware arguments | ||
| However, in order to keep the documentation streamlined, all examples will use the config file notation. | ||
|
|
||
| #### Symbol Layer Middleware | ||
|
|
||
| This middleware is executed for every layer within a symbol. | ||
|
|
||
| The function that is called has several arguments passed into it so you can provide different resizing options for different types of layers. | ||
| The typical use case for this is html-sketchapp's `layer.setResizingConstraint` API which allows you to configure how a layer should behave when a symbol is resized. | ||
|
|
||
| The following things are passed into symbol | ||
| ```js | ||
| module.exports = { | ||
| symbolLayerMiddleware: args => { ... } | ||
| }; | ||
| ``` | ||
|
|
||
| The following arguments are passed into your middleware function: | ||
| - layer: the html-sketchapp layer instance | ||
| - SVG: The SVG class for type checking of layer | ||
| - Text: The Text class for type checking of layer | ||
| - Rectangle: The Rectangle class for type checking of layer | ||
| - ShapeGroup: The ShapeGroup class for type checking of layer | ||
| - RESIZING_CONSTRAINTS: contains friendly names for `setResizingConstraint` API. | ||
| - RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API | ||
|
|
||
| Handling SVGs differently from other layers: | ||
| For example, when handling SVGs differently from other layers: | ||
|
|
||
| ```js | ||
| module.exports = { | ||
|
|
@@ -203,67 +261,38 @@ module.exports = { | |
|
|
||
| ``` | ||
|
|
||
| ### Puppeteer args | ||
|
|
||
| If you need to provide command line arguments to the browser instance via [Puppeteer](https://github.com/GoogleChrome/puppeteer), you can provide the `puppeteer-args` option. | ||
|
|
||
| Since Puppeteer uses [Chromium](https://www.chromium.org/Home) internally, you can refer to the [List of Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches) for available options. | ||
|
|
||
| For example, if you'd like to disable the browser sandbox: | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --puppeteer-args="--no-sandbox --disable-setuid-sandbox" --file sketch.html --out-dir dist | ||
| ``` | ||
|
|
||
| *Note: Because Puppeteer args are prefixed with hyphens, you **must** use an equals sign and quotes when providing this option via the command line (as seen above).* | ||
|
|
||
| ### Chromium executable | ||
| #### Symbol Middleware | ||
|
|
||
| If you'd like to override the Chromium used by Puppeteer, you can provide a path to the executable with the `puppeteer-executable-path` option. | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --puppeteer-executable-path google-chrome-unstable --file sketch.html --out-dir dist | ||
| ``` | ||
|
|
||
| ### Config file | ||
|
|
||
| All options can be provided via an `html-sketchapp.config.js` file. | ||
| This middleware is executed for every symbol within a document. | ||
|
|
||
| ```js | ||
| module.exports = { | ||
| file: 'sketch.html', | ||
| outDir: 'dist/sketch', | ||
| viewports: { | ||
| Desktop: '1024x768', | ||
| Mobile: '320x568' | ||
| }, | ||
| puppeteerArgs: '--no-sandbox --disable-setuid-sandbox', | ||
| puppeteerExecutablePath: 'google-chrome-unstable' | ||
| symbolMiddleware: args => { ... } | ||
| }; | ||
| ``` | ||
|
|
||
| You can provide an alternate config file path with the `--config` option. | ||
| The following arguments are passed into your middleware function: | ||
| - symbol: The current symbol master | ||
| - node: The source HTML node | ||
| - suffix: The symbol name suffix (e.g. `/Desktop`) | ||
| - RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API | ||
|
|
||
| ```bash | ||
| $ html-sketchapp --config example.config.js | ||
| ``` | ||
|
|
||
| ## Importing into Sketch | ||
|
|
||
| Once this command has successfully run, the following files will be generated in the output directory. | ||
|
|
||
| - `document.asketch.json` | ||
| - `page.asketch.json` | ||
| #### Symbol Instance Middleware | ||
|
|
||
| These need to be imported into Sketch via html-sketchapp's corresponding Sketch plugin. To ease the install process, you can run the following command. | ||
| This middleware is executed for every symbol instance within a document. | ||
|
|
||
| ```bash | ||
| $ html-sketchapp install | ||
| ```js | ||
| module.exports = { | ||
| symbolInstanceMiddleware: args => { ... } | ||
| }; | ||
| ``` | ||
|
|
||
| Then, open a new Sketch document and, from the menu, select `Plugins > From *Almost* Sketch to Sketch`. In the file picker, select both `document.asketch.json` and `page.asketch.json`, and click `Choose`. | ||
|
|
||
| Congratulations! You should now have your symbols, text styles and document colors available within Sketch! 💎🎉 | ||
| The following arguments are passed into your middleware function: | ||
| - symbolInstance: The current symbol instance | ||
| - symbolMaster: The symbol master that the symbol instance is referencing | ||
| - node: The source HTML node | ||
| - RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API | ||
|
|
||
| ## Contributing | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.