1
0
Fork 0

chore(markdown): Move non-api docs to reference

This commit is contained in:
Joost De Cock 2022-09-30 15:34:59 +02:00
parent 8c3c0c9910
commit 8e9e5052ee
62 changed files with 68 additions and 49 deletions

View file

@ -0,0 +1,85 @@
---
title: Lifecycle hooks
---
FreeSewing has **lifecycle hooks** that allow you extend its functionality by
hooking into a lifecycle event.
You can register a method for a hook. When the hook is triggered, your method will be
called. It will receive two parameters:
- An object relevant to the hook (see the specific hook for details)
- Data passed when the hook was registered (optional)
## Pattern lifecycle
<Dot caption="A schematic overview of FreeSewing lifecycle hooks">
```dot
rankdir="TB"
compound=true
subgraph cluster_pattern {
fontsize=14
color="transparent"
preInit [shape="box" color="tc-orange"]
postInit [shape="box" color="tc-orange"]
subgraph cluster_draft {
label="Pattern.draft()"
color="tc-teal"
preDraft [shape="box" color="tc-teal"]
preSetDraft [shape="box" color="tc-teal"]
prePartDraft [shape="box" color="tc-teal"]
postPartDraft [shape="box" color="tc-teal"]
postSetDraft [shape="box" color="tc-teal"]
postDraft [shape="box" color="tc-teal"]
}
subgraph cluster_sample {
label="Pattern.sample()"
color="tc-sky"
preSample [shape="box" color="tc-sky"]
postSample [shape="box" color="tc-sky"]
}
subgraph cluster_getRenderProps {
label="Pattern.getRenderProps()"
color="tc-gray"
preRenderProps [label="preRender" shape="box" color="tc-teal"]
}
subgraph cluster_render {
label="Pattern.render()"
color="tc-gray"
preRender [shape="box" color="tc-teal"]
insertText [shape="box" color="tc-teal"]
postRender [shape="box" color="tc-teal"]
}
}
preInit -> postInit
postInit -> preDraft
preDraft -> preSetDraft -> preSetDraft
preSetDraft -> prePartDraft -> prePartDraft
prePartDraft -> postPartDraft -> postPartDraft
postPartDraft -> postSetDraft -> postSetDraft
postSetDraft -> postDraft
postDraft -> preRenderProps
postDraft -> preRender
preRender -> insertText -> insertText
insertText -> postRender
postInit -> preSample
preSample -> postSample
postSample -> preRenderProps
postSample -> preRender
```
</Dot>
## Lifecycle hooks
Below is a list of all available lifecycle hooks:
<ReadMore list />

View file

@ -0,0 +1,55 @@
---
title: insertText
---
The `insertText` lifecycle hook is called when text is about to be inserted
during rendering.
It is typically used for translation, as is the case
in [our i18n plugin](/reference/plugins/i18n/).
## Signature
```js
string hook(string locale='en', string text)
```
## Example
```js
// Let' get LOUD by turning everything into UPPERCASE
pattern.on(
'insertText',
(locale, text) => text.toUpperCase()
)
```
## Notes
When we say that _this hook is called when text is about to be inserted_, that is a simplified view.
In reality, this hook is called:
- For every string of text added to a given Point or Path
- For the combined result of these values, joined together with spaces
Let's use an example to clarify things:
```js
points.example
.addText("seamAllowance")
.addText(": 1cm")
```
For the example point above, the `insertText` hook will end up being called 3 times:
- First it will pass `seamAllowance` to the plugin
- Then it will pass `: 1cm` to the plugin
- Finally it will pass `seamAllowance : 1cm` to the plugin
Having the `insertText` hook only run once with `Seam allowance: 1cm` would be problematic because
the seam allowance may differ, or perhaps we're using imperial units, and so on.
Instead, you can (and should) divide your text into chunks that need translating, and chunks that do not.
This is also why we're not inserting **Seam allowance** but rather **seamAllowance**;
It is merely a key to indicate what translation we want to replace this text with.

View file

@ -0,0 +1,23 @@
---
title: postDraft
---
The `postDraft` lifecycle hook runs just after your pattern is drafted.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postDraft', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `postDraft` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,23 @@
---
title: postInit
---
The `postInit` lifecycle hook runs just after a pattern is initialized.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postInit', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `postInit` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,24 @@
---
title: postLayout
---
The `postLayout` lifecycle hook runs just after the pattern layout is
calculated.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postLayout', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `postLayout` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,27 @@
---
title: postPartDraft
---
The `postPartDraft` lifecycle hook runs just after a part is drafted.
It will fire once for each part in each set (of settings).
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postPartDraft', pattern => {
// Mutate the pattern object here
// You can use the pattern.activePart
// and pattern.activeSet properties to
// figure out for which part this hook was fired
}
```
## Notes
The `postPartDraft` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,19 @@
---
title: postRender
---
The `postRender` lifecycle hook is triggered after the SVG is rendered.
It will only fire when `Pattern.render()` is called.
## Signature
```js
null hook(Svg svg)
```
## Notes
The `postRender` hook is rarely used, but it's there if you need it.
Like the `preRender` hook, it receives [the SVG object](/api/svg) as its first
parameter.

View file

@ -0,0 +1,30 @@
---
title: postSample
---
The `postSample` hook runs just after your pattern is sampled.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postSample', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `postSample` hook is rarely used, but it's there if you need it.
It is triggered just before the end of either:
- the [Pattern.sampleOption()](/reference/api/pattern/sampleoption) method
- the [Pattern.sampleMeasurement()](/reference/api/pattern/samplemeasurement) method
- the [Pattern.sampleModels()](/reference/api/pattern/samplemodels) method

View file

@ -0,0 +1,24 @@
---
title: postSetDraft
---
The `postSetDraft` lifecycle hook runs just after a set (of settings) is
drafted. It will fire once for each set when calling `Pattern.draft()`.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('postSetDraft', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `postSetDraft` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,23 @@
---
title: preDraft
---
The `preDraft` lifecycle hook runs just before your pattern is drafted.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('preDraft', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `preDraft` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,23 @@
---
title: preInit
---
The `preInit` lifecycle hook runs just before a pattern will be initialized.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('preInit', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `preInit` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,27 @@
---
title: prePartDraft
---
The `prePartDraft` lifecycle hook runs just before a part is drafted.
It will fire once for each part in each set (of settings).
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('prePartDraft', pattern => {
// Mutate the pattern object here
// You can use the pattern.activePart
// and pattern.activeSet properties to
// figure out for which part this hook was fired
}
```
## Notes
The `prePartDraft` hook is rarely used, but it's there if you need it.

View file

@ -0,0 +1,20 @@
---
title: preRender
---
The `preRender` lifecycle hook is triggered just before your pattern is
rendered to SVG.
## Signature
```js
null hook(Svg svg)
```
## Notes
The `preRender` hook is typically used to change the result of the render, for
example by adding CSS to the SVG output.
Like the `postRender` hook, it receives [the SVG object](/api/svg) as its first
parameter.

View file

@ -0,0 +1,30 @@
---
title: preSample
---
The `preSample` hook runs just before your pattern is sampled.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('preSample', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `preSample` hook is rarely used, but it's there if you need it.
It is triggered just before the start of either:
- the [Pattern.sampleOption()](/reference/api/pattern/sampleoption) method
- the [Pattern.sampleMeasurement()](/reference/api/pattern/samplemeasurement) method
- the [Pattern.sampleModels()](/reference/api/pattern/samplemodels) method

View file

@ -0,0 +1,24 @@
---
title: preSetDraft
---
The `preSetDraft` lifecycle hook runs just before a set (of settings) is
drafted. It will fire once for each set when calling `Pattern.draft()`.
## Signature
```js
null hook(Pattern pattern)
```
## Example
```js
pattern.on('preSetDraft', pattern => {
// Mutate the pattern object here
}
```
## Notes
The `preSetDraft` hook is rarely used, but it's there if you need it.