wip: More improvements on dev docs
This commit is contained in:
joostdecock
parent
e0a261731f
commit
12652ed646
14 changed files with 222 additions and 218 deletions
|
|
@ -1,19 +0,0 @@
|
|||
---
|
||||
title: copy()
|
||||
---
|
||||
|
||||
```js
|
||||
Part part.copy(Part original)
|
||||
```
|
||||
|
||||
This will copy the points, paths, and snippets from a part you pass into it.
|
||||
|
||||
<Note>
|
||||
|
||||
This method is used internally, you are unlikely to need this.
|
||||
|
||||
If you want one part to build on another, you should set
|
||||
up [part inheritance](/advanced/inject) in your pattern's [configuration](../config) file.
|
||||
|
||||
</Note>
|
||||
|
||||
|
|
@ -3,15 +3,19 @@ title: Part
|
|||
order: 20
|
||||
---
|
||||
|
||||
Part objects hold the actual information, and together they make up your pattern.
|
||||
The `Part` object in FreeSewing's core library holds all data and logic of a pattern part.
|
||||
A pattern part is what holds the actual information about points and paths,
|
||||
and multiple parts together typically make up a pattern.
|
||||
|
||||
Each Part object comes with the following properties:
|
||||
## Part properties
|
||||
|
||||
- `paths` : A plain object to store your paths in
|
||||
- `points` : A plain object to store your points in
|
||||
- `render` : A flag that controls whether to include the part in the render output
|
||||
- `snippets` : A plain object to store your snippets in
|
||||
| Property | Description |
|
||||
| --------:| ----------- |
|
||||
| `paths` | A plain object to store your paths in |
|
||||
| `points` | A plain object to store your points in |
|
||||
| `render` | A flag that controls whether to include the part in the render output |
|
||||
| `snippets` | A plain object to store your snippets in |
|
||||
|
||||
In addition, a Part object exposes the following methods:
|
||||
## Part methods
|
||||
|
||||
<ReadMore list />
|
||||
|
|
|
|||
|
|
@ -1,13 +1,34 @@
|
|||
---
|
||||
title: getId()
|
||||
title: Part.getId()
|
||||
---
|
||||
|
||||
A part's `getId()` method will return an integer the can be used as an
|
||||
ID Points/Paths/Snippets. This method will ensure the ID is unique be
|
||||
keeping an internal record of the ID that have been used.
|
||||
It is typically used when programatically adding points, paths, or snippets.
|
||||
|
||||
## Part.getId() signature
|
||||
|
||||
```js
|
||||
int part.getId(prefix='')
|
||||
```
|
||||
Returns a integer as an available ID that you can use as for Points/Paths/Snippets.
|
||||
|
||||
Takes an options `prefix` to prefix the ID with.
|
||||
This methiod takes an optional parameter that will be used as a prefix for the ID.
|
||||
|
||||
## Part.getId() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { Point, points } = part.shorthand()
|
||||
|
||||
for (let i=0;i<10;i++) {
|
||||
const id= part.getId()
|
||||
points[id] = new Point(i*10, i*10)
|
||||
}
|
||||
|
||||
// You would do more useful stuff before returning
|
||||
return part
|
||||
}
|
||||
```
|
||||
|
||||
This is typically used when adding points programmatically.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,10 @@
|
|||
---
|
||||
title: raise.debug()
|
||||
title: Part.raise.debug()
|
||||
---
|
||||
|
||||
```js
|
||||
raise.debug(data)
|
||||
```
|
||||
|
||||
The `raise.debug()` method adds an event of type `debug` to the pattern.
|
||||
A part's `raise.debug()` method will log a debug-level event.
|
||||
Debug events are typically used to pass information to pattern developers
|
||||
so that can troubleshoot issues with the pattern.
|
||||
|
||||
What happens with this data is entirely up to the frontend developer.
|
||||
As such, data can by anything you like. A string is common, but you
|
||||
|
|
@ -18,3 +16,23 @@ use in your frontend.
|
|||
All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
|
||||
|
||||
</Tip>
|
||||
|
||||
## Part.raise.debug() signature
|
||||
|
||||
```js
|
||||
raise.debug(data)
|
||||
```
|
||||
|
||||
## Part.raise.debug() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { raise } = part.shorthand()
|
||||
|
||||
raise.debug('Entered the draft method of partmyPart')
|
||||
|
||||
// You would do more useful stuff before returning
|
||||
return part
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,19 @@
|
|||
---
|
||||
title: raise methods
|
||||
title: Part raise methods
|
||||
---
|
||||
|
||||
The various `raise` methods are used to bring information to the attention
|
||||
of the user, or developer.
|
||||
A part's different `raise` methods are used to bring information to the attention
|
||||
of the user, or developer. You can think of them as logging methods the register
|
||||
data.
|
||||
|
||||
<Warning>
|
||||
|
||||
##### FreeSewing v3 breaking changes
|
||||
|
||||
This behavior is likely to change in FreeSewing v3. Refer to [the
|
||||
roadmap](https://github.com/freesewing/freesewing/discussions/1278) for details.
|
||||
|
||||
</Warning>
|
||||
|
||||
There are four different types of information with their own method:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,27 +1,35 @@
|
|||
---
|
||||
title: raise.error()
|
||||
title: Part.raise.error()
|
||||
---
|
||||
|
||||
```js
|
||||
raise.error(data)
|
||||
```
|
||||
|
||||
The `raise.error()` method adds an event of type `error` to the pattern.
|
||||
|
||||
<Note>
|
||||
|
||||
##### Raising an error will prevent the pattern from being completed
|
||||
|
||||
Unlike other events, which have no side-effects, if there is one or more
|
||||
A part's `raise.error()` method will log a error-level event.
|
||||
Unlike other raised events which have no side-effects, if there is one or more
|
||||
events of type `error`, the pattern will not be completed.
|
||||
|
||||
In other words, you should only use this when the situation is unrecoverable.
|
||||
If not, [raise a warning](/reference/api/part/raise/warning).
|
||||
|
||||
</Note>
|
||||
In other words, you should only use this when end up in a situation
|
||||
you cannot recover from. If not, [raise a warning](/reference/api/part/raise/warning).
|
||||
|
||||
<Tip>
|
||||
|
||||
All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
|
||||
|
||||
</Tip>
|
||||
|
||||
## Part.raise.error() signature
|
||||
|
||||
```js
|
||||
raise.error(data)
|
||||
```
|
||||
|
||||
## Part.raise.error() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { raise, measurements } = part.shorthand()
|
||||
|
||||
if (measurements.hips > measurements.chest) {
|
||||
raise.warning('Chest circumference smaller than hip circumference is currently unsupported. Aborting.')
|
||||
return part
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,10 @@
|
|||
---
|
||||
title: raise.info()
|
||||
title: Part.raise.info()
|
||||
---
|
||||
|
||||
```js
|
||||
raise.info(data)
|
||||
```
|
||||
|
||||
The `raise.info()` method adds an event of type `info` to the pattern.
|
||||
A part's `raise.info()` method will log a ingo-level event.
|
||||
Info events are typically used to pass information to users
|
||||
that is informative to them.
|
||||
|
||||
What happens with this data is entirely up to the frontend developer.
|
||||
As such, data can by anything you like. A string is common, but you
|
||||
|
|
@ -18,3 +16,22 @@ use in your frontend.
|
|||
All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
|
||||
|
||||
</Tip>
|
||||
|
||||
## Part.raise.info() signature
|
||||
|
||||
```js
|
||||
raise.info(data)
|
||||
```
|
||||
|
||||
## Part.raise.info() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { raise, options } = part.shorthand()
|
||||
|
||||
if (options.shortSleeves) {
|
||||
raise.info('Not drafting french cuffs because you opted for short sleeves')
|
||||
return part
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,12 +1,11 @@
|
|||
---
|
||||
title: raise.warning()
|
||||
title: Part.raise.warning()
|
||||
---
|
||||
|
||||
```js
|
||||
raise.warning(data)
|
||||
```
|
||||
|
||||
The `raise.warning()` method adds an event of type `warning` to the pattern.
|
||||
A part's `raise.warning()` method will log a warning-level event.
|
||||
Warning events are typically used to pass information to pattern developers
|
||||
so that can troubleshoot issues with the pattern, or users to warn them
|
||||
that something is sub-optimal.
|
||||
|
||||
What happens with this data is entirely up to the frontend developer.
|
||||
As such, data can by anything you like. A string is common, but you
|
||||
|
|
@ -18,3 +17,28 @@ use in your frontend.
|
|||
All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
|
||||
|
||||
</Tip>
|
||||
|
||||
## Part.raise.warning() signature
|
||||
|
||||
```js
|
||||
raise.warning(data)
|
||||
```
|
||||
|
||||
## Part.raise.warning() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { raise, measurements } = part.shorthand()
|
||||
|
||||
if (measurements.hips > measurements.chest) {
|
||||
raise.warning(`
|
||||
Chest circumference is smaller than hip circumference.
|
||||
This might lead to unexpected results
|
||||
`)
|
||||
}
|
||||
|
||||
// You would do more useful stuff before returning
|
||||
return part
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,63 +1,80 @@
|
|||
---
|
||||
title: shorthand()
|
||||
title: Part.shorthand()
|
||||
---
|
||||
|
||||
A part's `shorthand()` method provides easy access to a number of
|
||||
internal objects and properties. It does so be returning an object
|
||||
that contains all you need to draft your pattern parts. It is
|
||||
typically combined with object destructuring to pull out those
|
||||
properties you need.
|
||||
|
||||
As the name implies, this method can save you a bunch of typing, and keep your
|
||||
code concise. We highly recommend you use it.
|
||||
|
||||
## Part.shorthand() signature
|
||||
|
||||
```js
|
||||
object Part.shorthand();
|
||||
```
|
||||
|
||||
This method returns a plain object with the following properties:
|
||||
The `Part.shorthand()` method returns a plain object with the following properties:
|
||||
|
||||
- `complete` = `pattern.settings.complete`
|
||||
- `events` : An object holding the raised events (see `raise`)
|
||||
- `final` : `true` is this is a full draft, or `false` if this is a sample.
|
||||
- `macro` : The macro runner
|
||||
- `measurements` = `pattern.settings.measurements`
|
||||
- `paperless` = `pattern.settings.paperless`
|
||||
- `Path` : the [Path](/reference/api/path) constructor
|
||||
- `paths` = `part.paths`
|
||||
- `Point` : the [Point](/reference/api/point) constructor
|
||||
- `points` = `part.points`
|
||||
- `Snippet` : the [Snippet](/reference/api/snippet) constructor
|
||||
- `snippets` = `part.snippets`
|
||||
- `options` = `pattern.settings.options`
|
||||
- `raise` : An object holding the various methods that allow you to [raise events](/reference/api/part/raise/)
|
||||
- `sa` = `pattern.settings.sa`
|
||||
- `store` = `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts
|
||||
- `utils` : A [Utils](/reference/api/utils) instance with utility methods
|
||||
- `units` : A context-aware version of `utils.units`
|
||||
| Property | Description |
|
||||
| --------:| ----------- |
|
||||
| `config` | The pattern configuration |
|
||||
| `complete` | Holds `pattern.settings.complete` |
|
||||
| `events` | An object holding the raised events (see [Part.raise](/reference/api/part/raise/)) |
|
||||
| `final` | `true` is this is a full draft, or `false` if this is a sample. |
|
||||
| `macro` | The macro runner. See [the macros documentation](/reference/macros/) |
|
||||
| `measurements` | Holds `pattern.settings.measurements` |
|
||||
| `paperless` | Holds `pattern.settings.paperless` |
|
||||
| `Path` | The [Path constructor](/reference/api/path) |
|
||||
| `paths` | Holds `part.paths` |
|
||||
| `Point` | The [Point constructor](/reference/api/point) |
|
||||
| `points` | Holds `part.points` |
|
||||
| `Snippet` | The [Snippet constructor](/reference/api/snippet) |
|
||||
| `snippets` | Holds `part.snippets` |
|
||||
| `options` | Holds `pattern.settings.options` |
|
||||
| `raise` | Holds [Part.raise](/reference/api/part/raise/) thus giving you access to the various raise methods |
|
||||
| `sa` | Holds `pattern.settings.sa` |
|
||||
| `store` | Holds `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts |
|
||||
| `utils` | A [Utils](/reference/api/utils) instance with utility methods |
|
||||
| `units` | A context-aware version of `utils.units` |
|
||||
|
||||
As the name implies, this method can save you a bunch of typing, and keep your
|
||||
code concise. We highly recommend it. Below are some examples:
|
||||
## Part.shorthand() example
|
||||
|
||||
```js{16}
|
||||
// You could write this:
|
||||
part.points.from = new part.Point(
|
||||
pattern.measurements.chestCircumference / 2,
|
||||
pattern.options.armholeDepth);
|
||||
pattern.measurements.chest / 2,
|
||||
pattern.options.armholeDepth
|
||||
)
|
||||
|
||||
part.points.to = new part.Point(
|
||||
part.points.from.x + pattern.settings.sa,
|
||||
part.points.from.y);
|
||||
part.points.from.y
|
||||
)
|
||||
|
||||
part.paths.example = new part.Path()
|
||||
.move(parts.points.from)
|
||||
.line(parts.points.to);
|
||||
.line(parts.points.to)
|
||||
|
||||
// Or use shorthand:
|
||||
let { Point, points, measurements, options, sa } = part.shorthand();
|
||||
const { Point, points, measurements, options, sa } = part.shorthand()
|
||||
|
||||
points.from = new Point(
|
||||
measurements.chestCircumference / 2,
|
||||
options.armholeDepth);
|
||||
measurements.chest / 2,
|
||||
options.armholeDepth
|
||||
)
|
||||
|
||||
points.to = new part.Point(
|
||||
points.from.x + sa,
|
||||
points.from.y);
|
||||
points.from.y
|
||||
)
|
||||
|
||||
paths.example = new Path()
|
||||
.move(points.from)
|
||||
.line(points.to);
|
||||
.line(points.to)
|
||||
```
|
||||
|
||||
<Tip>
|
||||
|
|
|
|||
|
|
@ -1,12 +1,11 @@
|
|||
---
|
||||
title: units()
|
||||
title: Part.units()
|
||||
---
|
||||
|
||||
```js
|
||||
string part.units(float number)
|
||||
```
|
||||
|
||||
Formats input (in mm) as the units requested by the user.
|
||||
A part's `units()` method will formats a float you pass it, which should
|
||||
represent a value in mm, into the units requested by the user.
|
||||
The returned value is to be used in presentation only, as it will be
|
||||
a string that includes the user's units.
|
||||
|
||||
<Tip>
|
||||
|
||||
|
|
@ -20,3 +19,19 @@ let { units } = part.shorthand();
|
|||
|
||||
</Tip>
|
||||
|
||||
## Part.units() signature
|
||||
|
||||
```js
|
||||
string part.units(float number)
|
||||
```
|
||||
|
||||
## Part.units() example
|
||||
|
||||
```js
|
||||
export default function (part) {
|
||||
const { raise, units, measurements } = part.shorthand()
|
||||
|
||||
raise.info(`Pattern drafted for a ${units(measurements.chest)} chest`)
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +0,0 @@
|
|||
---
|
||||
title: Pattern.apply()
|
||||
---
|
||||
|
||||
A pattern's `apply()` method merges the settings passed to it with
|
||||
the current pattern settings. It is used internally to merge the
|
||||
settings that are passed to the pattern constructor with the default settings.
|
||||
|
||||
<Note>This method is chainable as it returns the Pattern object</Note>
|
||||
|
||||
## Pattern.apply() signature
|
||||
|
||||
```js
|
||||
Pattern pattern.apply(object settings)
|
||||
```
|
||||
|
||||
<Note>
|
||||
You are unlikely to ever user this method directly.
|
||||
</Note>
|
||||
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
---
|
||||
title: Pattern.needs()
|
||||
---
|
||||
|
||||
A pattern's `needs()` method will return `true` or `false`
|
||||
depending on whether a pattern part is a requirement for the
|
||||
pattern to be drafted in its current configuration. In other
|
||||
words, it will return `true` of the part is *needed*.
|
||||
|
||||
A part is needed if:
|
||||
|
||||
- it is requested by the user in [the `only` pattern setting](/reference/settings/only/)
|
||||
- it is a dependency of a part requested by the user in [the `only` pattern setting](/reference/settings/only/)
|
||||
- [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden
|
||||
|
||||
<Note>
|
||||
|
||||
You don't typically use this method. Instead, you configure part
|
||||
dependencies in your [configuration file](/reference/config/).
|
||||
|
||||
</Note>
|
||||
|
||||
## Pattern.needs() signature
|
||||
|
||||
```js
|
||||
bool pattern.needs(string partName)
|
||||
```
|
||||
|
||||
## Pattern.needs() example
|
||||
|
||||
```js
|
||||
import Aaron from "@freesewing/aaron"
|
||||
import models from "@freesewing/models"
|
||||
|
||||
const pattern = new Aaron({
|
||||
settings: {
|
||||
embed: true,
|
||||
},
|
||||
measurements: models.manSize38
|
||||
})
|
||||
|
||||
if (pattern.needs('front')) console.log('Front is needed')
|
||||
else console.log('Front is not needed')
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
title: wants()
|
||||
---
|
||||
|
||||
A pattern's `wants()` method will return `true` or `false`
|
||||
depending on whether a pattern part is requested in the
|
||||
current pattern configuration. In other words, it will
|
||||
return `true` of the part is *wanted* by the user.
|
||||
|
||||
A part is wanted if:
|
||||
|
||||
- it is requested by the user in [the `only` pattern setting](/reference/settings/only/)
|
||||
- [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden
|
||||
|
||||
<Note>
|
||||
|
||||
You don't typically use this method. Instead, you configure part
|
||||
dependencies in your [configuration file](/reference/config/).
|
||||
|
||||
</Note>
|
||||
|
||||
## Pattern.wants() signature
|
||||
|
||||
```js
|
||||
bool pattern.wants(string partName)
|
||||
```
|
||||
|
||||
## Pattern.wants() example
|
||||
|
||||
```js
|
||||
import Aaron from "@freesewing/aaron"
|
||||
import models from "@freesewing/models"
|
||||
|
||||
const pattern = new Aaron({
|
||||
settings: {
|
||||
embed: true,
|
||||
},
|
||||
measurements: models.manSize38
|
||||
})
|
||||
|
||||
if (pattern.wants('front')) console.log('Front is wanted')
|
||||
else console.log('Front is not wanted')
|
||||
```
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ While the methods exposed by this object are only used internally,
|
|||
its attributes are useful for situations where you
|
||||
want to develop a plugin, or use a custom layout:
|
||||
|
||||
## Properties
|
||||
## Svg properties
|
||||
|
||||
<ReadMore list />
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue