From 75eff4f5e48ddc17fdd04b788b84cd60730a14b5 Mon Sep 17 00:00:00 2001 From: joostdecock Date: Mon, 30 Oct 2023 18:58:31 +0100 Subject: [PATCH] chore(markdown): Show how to create a snippet. Closes #3824 --- .../dev/howtos/code/create-new-design/en.md | 2 +- markdown/dev/howtos/code/create-snippet/en.md | 127 ++++++++++++++++++ .../dev/howtos/code/create-snippet/smiley.png | Bin 0 -> 3418 bytes 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 markdown/dev/howtos/code/create-snippet/en.md create mode 100644 markdown/dev/howtos/code/create-snippet/smiley.png diff --git a/markdown/dev/howtos/code/create-new-design/en.md b/markdown/dev/howtos/code/create-new-design/en.md index 95264b0be8c..e3d4053c73f 100644 --- a/markdown/dev/howtos/code/create-new-design/en.md +++ b/markdown/dev/howtos/code/create-new-design/en.md @@ -1,5 +1,5 @@ --- -title: Creating a new pattern design +title: Creating a new design --- When creating a new design, you have two options. You can create it in a diff --git a/markdown/dev/howtos/code/create-snippet/en.md b/markdown/dev/howtos/code/create-snippet/en.md new file mode 100644 index 00000000000..937359633cf --- /dev/null +++ b/markdown/dev/howtos/code/create-snippet/en.md @@ -0,0 +1,127 @@ +--- +title: Creating a new snippet to be used in your design +--- + +Snippets are typically added by plugins. If you have your own snippet you want +to use, you can add it to your design by loading it in an ad-hoc plugin. + +Here's how to do that: + +## Define the snippet + +First thing to do is define the snippet. A snippet will end up in the [SVG +defs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs) element +where it can be referenced via [the SVG use +tag](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use). + +So your snippet should be SVG content that can be referenced with a single ID. +That ID will also be the name of the snippet. Let's say we want to add `smiley` +then we would create it like this: + +```mjs +const smiley = ` + + + + + +` +``` + +If you're curious, it will end up looking like this: + +![Preview of our snippet](smiley.png) + + + + +##### Avoid self-closing tags + +Avoid using self-closing tags in your SVG defs definitions. +While this will work fine in actual SVG: +```svg + +``` + +Make sure to explicitly close the tag in your defs: +```svg + +``` + + + +## Load the plugin + +In your part config, we are going to add an ad-hoc plugin to our `plugins` key +and load the snippet into the defs section of our SVG document: + +```mjs + plugins: [{ + name: 'smiley-snippet-plugin', + version: '1.0.0', + hooks: { + preRender: [ + function(svg) { + svg.defs.setIfUnset( 'smiley', smiley) + } + ] + } + }], +``` + +## Styling snippets + +Styling snippets is something that can frustrating if you are not familiar with +how they are rendered under the hood. The SVG `use` tag creates a so-called +*showdow-dom* and styles will behave something different in that shadowy realm. + +For example, you can't just slap [one of our CSS classes](/reference/css) on it +and call it a day, that won't be enough. + +You can of course provide inline styles, but now your snippet can't be themed +which is a big nono for sites like FreeSewing.org that let users pick differnt +themes. + +As you can see in the example, we used CSS vars, as these do work well in the +shadow-dom and suppor themeing. You don't have to follow this approach, but we +do recommend it. + +## Supporting scale + +If you're looking to _do things right_ there is one more thing to take into account: +FreeSewing's [scale setting](/reference/settings/scale). + +Snippets won't auto-magically adapt to the different scale, so to make that happen we +have to make a few small changes. + +First, adapt the defs definition and make it a method that accepts the current scale as a parameter. +We then simply apply a transform and scale the snippet accordingly: + +```mjs +const smiley = (scale) => ` + + + + + +` +``` + +Then adapt the lifecycle hook method to load the def by calling the method and passing the current scale: + +```mjs + plugins: [{ + name: 'smiley-snippet-plugin', + version: '1.0.0', + hooks: { + preRender: [ + function(svg) { + svg.defs.setIfUnset( + 'smiley', smiley(svg.pattern.settings[0].scale) + ) + } + ] + } + }], +``` + diff --git a/markdown/dev/howtos/code/create-snippet/smiley.png b/markdown/dev/howtos/code/create-snippet/smiley.png new file mode 100644 index 0000000000000000000000000000000000000000..b820921081f3e34866b04f8b4267fb9805ef18e5 GIT binary patch literal 3418 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 literal 0 HcmV?d00001