VSinerva/freesewing
1
0
Fork 0
Code Activity

wip(markdown): Work on updating tutorial

Browse source
This commit is contained in:
Joost De Cock 2022-10-09 23:47:32 +02:00
parent b9a46e9763
commit 8e7595fcb4
8 changed files with 318 additions and 221 deletions
Download patch file Download diff file Expand all files Collapse all files

58
markdown/dev/tutorials/pattern-design/adding-measurements/en.md
View file

@ -8,28 +8,36 @@ we are going to draft our pattern according to the measurements provided to us.
Which begs the question, which measurements? Which begs the question, which measurements?
It is you, as the pattern designer, who decides which measurements are required to draft your pattern. It is you, as the pattern designer, who decides which measurements are used
For our bib, the only measurement we need is the baby's _head circumference_. to draft your pattern. For our bib, the only measurement we need is the
_head circumference_.
So let's add it as a required measurement. So let's add it as a required measurement.
## Add required measurements ## Adding required measurements
Open the config file at `design/config.js` and update the `measurements` array with the name of our required measurement: In our `bib.mjs` file, on the `bib` object, we'll add a new key called
`measurements` that will hold a list (an array) of all required measurements
for this part.
```js We are going to use *the official name* of the measurement. For head
measurements: ["head"], circumference, that name is `head`.
```design/src/bib.mjs
function draftBib({ part }) {
return part
}
export const bib = {
name: 'tutorial.bib',
draft: draftBib,
// Add this line:
measurements: ['head'],
}
``` ```
<Tip> Now everybody knows this part requires the `head` measurement.
Make sure to re-use the names of existing measurements, rather than invent your own.
See our [best practices](/guides/best-practices/reuse-measurements) on this topic for details.
</Tip>
Now everybody knows your pattern requires the `head` measurement.
This change will also get picked up by the development environment, and you'll now see this screen: This change will also get picked up by the development environment, and you'll now see this screen:
@ -41,4 +49,22 @@ For example `38` as 38cm is a realistic head circumference measurement for a bab
Enter `38` in the box, and click on **Draft Design** in the sidebar under the **View** heading. Enter `38` in the box, and click on **Draft Design** in the sidebar under the **View** heading.
This brings you back to our work in progress: This brings you back to our work in progress:
<Example pattern="tutorial" part="step1">Nothing has changed, yet</Example>
## Notes
### Why using standard measurements names matters
In principle, you can use any name you want for your measurements.
Our core library really doesn't care.
However, if everybody uses their own (names for) measurements, then people
aren't able to re-use their measurements across designs.
So if you have any intention at all to play nice with the FreeSewing ecosystem,
please make sure to re-use the names of existing measurements, rather than
invent your own.
See our [best practices](/guides/best-practices/reuse-measurements) on this
topic for details.

60
markdown/dev/tutorials/pattern-design/adding-options/en.md
View file

@ -13,21 +13,29 @@ to work with. But there's still a number of choices you have to make:
You can make all of these choices for the user and set them in stone, so to speak. You can make all of these choices for the user and set them in stone, so to speak.
But since you're designing a pattern in code, it's trivial to make your pattern But since you're designing a pattern in code, it's trivial to make your pattern
flexible and let the user decide. All you have to do is add options to your pattern. flexible and let the user decide. All you have to do is add options to your part.
## Add the neckRatio option ## Add the neckRatio option
The first option we're going to add controls the ratio between the neck opening The first option we're going to add controls the ratio between the neck opening
and the head circumference. Let's call it `neckRatio`. and the head circumference. Let's call it `neckRatio`.
Open the config file at `design/config.js` and add this to the options: We'll add a new `options` key to our part object for this:
```js ```design/src/bib.mjs
function draftBib({ part }) {
return part
}
export const bib = {
name: 'tutorial.bib',
draft: draftBib,
measurements: ['head'],
// Add these 3 lines:
options: { options: {
// Remove this size option neckRatio: { pct: 80, min: 70, max: 90, menu: 'fit' },
//size: { pct: 50, min: 10, max: 100 } },
// And add the neckRatio options
neckRatio: { pct: 80, min: 70, max: 90 },
} }
``` ```
@ -37,49 +45,39 @@ Can you guess what it means?
- Its minimum value is 70% - Its minimum value is 70%
- Its maximum value is 90% - Its maximum value is 90%
- Its default value is 80% - Its default value is 80%
- We've added this option to the *fit* menu
<Note> <Note>
There are different types of options, but percentages are the most common ones. There are different types of options, but percentages are the most common ones.
They are all documented [in the API docs](/reference/api/config/options). They are all documented [in the part reference docs](/reference/api/part/config/options).
</Note> </Note>
## Add the widthRatio and lengthRatio options
Let's do something similar for the width and length of our bib: Let's do something similar for the width and length of our bib:
```js ```design/src/bib.mjs
options: { options: {
neckRatio: { pct: 80, min: 70, max: 90 }, neckRatio: { pct: 80, min: 70, max: 90, menu: 'fit' },
widthRatio: { pct: 45, min: 35, max: 55 }, widthRatio: { pct: 45, min: 35, max: 55, menu: 'style' },
lengthRatio: { pct: 75, min: 55, max: 85 }, lengthRatio: { pct: 75, min: 55, max: 85, menu: 'style' },
} }
``` ```
- You've added `widthRatio` and `lengthRatio` options - You've added `widthRatio` and `lengthRatio` options
- You've given all options sensible defaults - You've given all options sensible defaults
- You've given all options sensible maximum and minimum boundaries - You've given all options sensible maximum and minimum boundaries
- You've added these two new options to the *style* menu
<Note>
Later, you'll test-drive your pattern to see how it behaves when you adapt the options Later, you'll test-drive your pattern to see how it behaves when you adapt the options
between their minimum and maximum values. At that time, you can still tweak these values. between their minimum and maximum values. At that time, you can still tweak these values.
</Note> With that out of the way, let's start drawing our bib.
Before you close the `design/config.js` file, make sure to update the `optionGroups` entry as follows: ## Notes
```js The `menu` key on an option does not do anything for your pattern as such.
optionGroups: { Instead it signals to the frontend that this is how options should be grouped
fit: ["neckRatio", "widthRatio", "lengthRatio"] together and presented to the user.
},
```
<Note>
The `optionGroups` entry does not do anything for your pattern as such.
Instead it signals to the frontend that this is how options should be grouped together and presented to the user.
</Note>
Because you have removed the `box` option, the pattern no longer draws a box.
So let's start drawing your bib instead.

87
markdown/dev/tutorials/pattern-design/draft-structure/en.md Normal file
View file

@ -0,0 +1,87 @@
---
title: Structure of a draft method
order: 150
---
Time to turn our attention to the draft method of our part.
Inside our `design/src/bib.js` file, this is what it currently looks like:
```design/src/bib.mjs
function draftBib({ part }) {
return part
}
```
This is an empty skeleton for a draft method. A draft method should always
return the part object, and that's effectively the only thing it currently
does.
## Destructuring the function parameter
If you're not familiar with the `({ part })` syntax you see above, this is a
technique called *parameter destructuring* or more generally, [object
desctructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)
The draft method receives only 1 parameter: An object that holds everything you
need to draft your method. Destructuring is a way to *pull things out of the
object into their own variable*. It saves us a bunch of typing as these two are
equivalent:
```design/src/bib.mjs
function draftBib(props) {
return props.part
}
```
```design/src/bib.mjs
function draftBib({ part }) {
return part
}
```
As we'll make our way through this tutorial, we'll need more and more stuff, so
we'll be pulling it out of the object passed to the draft method via
*destructuring*.
<Note>
If you're new to JavaScript, and don't intuitively _get this_, stick with it. It will become second nature soon enough.
</Note>
## Destructuring what we need to start drawing our bib
Change the function to look like this:
```design/src/bib.mjs
function draftBib({
Path,
Point,
paths,
points,
part,
}) {
return part
}
```
That's bunch of new lines, but each of one gives us something we'll use in this
tutorial.
For a complete list of what you can access via destructuring like this, refer
to [the draft method reference documentation](/reference/api/part/draft).
Here's a brief summary of the things we've added above:
- `Path`: The Path constructor, allows you to create new Paths
- `Point`: The Point constructor, allows you to create new Points
- `points`: A container object to hold the part's points
- `paths`: A container object to hold the part's paths
Long story short: These will make it possible for you to draw points and paths easily.
So let's go ahead and do that.

2
markdown/dev/tutorials/pattern-design/en.md
View file

@ -11,7 +11,7 @@ translate your designs into code.
At the end of this tutorial, you will have created this pattern: At the end of this tutorial, you will have created this pattern:
<Examples part="tutorial.step11">Your end result</Examples> <Examples part="tutorial.step11" caption="Your end result" />
Before we can get started, let's make sure you have the required software Before we can get started, let's make sure you have the required software
installed on your computer: installed on your computer:

25
markdown/dev/tutorials/pattern-design/new-design/en.md
View file

@ -6,14 +6,15 @@ order: 100
Open a terminal and enter the following command: Open a terminal and enter the following command:
```sh ```sh
npx @freesewing/new-design npx @freesewing/new-design@next
``` ```
<Fixme compact>Remove `@next` suffix once v3 is in production</Fixme>
You'll be asked some questions, use these answers: You'll be asked some questions.
All the defaults will do, but here are the details:
- **What template would you like to use?**: Pick the default `From scratch` - *What template would you like to use?* — Pick the default: **Tutorial**
- **What name would you like the design to have**: Enter `bib` - *What package manager should we use?* — Pick the default: **npm**, unless you are certain you have **yarn** installed
- **What package manager do you use?**: Pick `npm` unless you are certain you have `yarn` installed
After you've answered these questions, files will be copied, dependencies installed, and components downloaded. After you've answered these questions, files will be copied, dependencies installed, and components downloaded.
@ -23,17 +24,17 @@ This will take a few minutes because we're loading some software for your develo
</Note> </Note>
When it's ready, enter the `bib` directory that was just created and run `npm run dev`: When it's ready, enter the `tutorial` directory that was just created and run `npm run dev`:
```sh ```sh
cd bib cd tutorial
npm run dev npm run dev
``` ```
Or if you chose to use Yarn as package manager: Or if you chose to use yarn as package manager:
```sh ```sh
cd bib cd tutorial
yarn dev yarn dev
``` ```
@ -43,11 +44,9 @@ If all goes well, you should see this landing page:
![The FreeSewing development environment](./nd.png) ![The FreeSewing development environment](./nd.png)
<Note> ## Notes
###### Need help? ### Need help?
If you run into any issues, [join our **#development-help** chat room on on If you run into any issues, [join our **#development-help** chat room on on
Discord](https://discord.freesewing.org/) and we'll figure it out together. Discord](https://discord.freesewing.org/) and we'll figure it out together.
</Note>

106
markdown/dev/tutorials/pattern-design/part-structure/en.md
View file

@ -1,106 +0,0 @@
---
title: Structure of a part
order: 150
---
Let's get rid of the example box first.
Open `design/src/bib.js` and make sure it looks like this:
```js
export default function(part) {
const { Point, points, Path, paths, complete, sa, paperless } = part.shorthand()
// Design pattern here
// Complete?
if (complete) {
if (sa) {
}
// Paperless?
if (paperless) {
}
}
return part
}
```
This is an empty skeleton for a pattern part. Anytime you want to create a new part,
this is a good starting point.
Let's quickly go over the different sections.
Even if there's not much going on yet, it's always good to understand what's going on.
## The draft method
```js
export default function(part) {
// ...
return part
}
```
This is the boilerplate of our `draftBib` method. It takes the part as an argument, and returns it.
<Note>
If you're new to JavaScript, and don't intuitively _get this_, stick with it. It will become second nature soon enough.
</Note>
## Using shorthand
```js
let {
Point,
points,
Path,
paths,
} = part.shorthand()
```
This is FreeSewing's **shorthand** method. It returns an object with a bunch of handy helpers
and you use JavaScript's _object destructuring_ to only get what you need.
The example above makes the following variables available:
- `Point`: The Point constructor
- `points`: A reference to the part's points
- `Path`: The Path constructor
- `paths`: A reference to the part's paths
These will make it possible for you to draw points and paths easily.
The following three variables are also needed to create a full-fledged FreeSewing pattern; their function and usage will
be covered in detail [later on in this tutorial](/tutorials/pattern-design/completing-your-pattern/):
- `complete`: create a _complete_ pattern (or not)
- `sa`: include _seam allowance_ (or not)
- `paperless`: allow the pattern to be _paperless_
For now, we only need these so that the pattern skeleton compiles properly.
<Note>
This will all become clear, but if you're curious, the API docs have all the details
on [the Part.shorthand() method](/reference/api/part/shorthand).
</Note>
## Part boilerplate
```js
// Complete?
if (complete) {
if (sa) {
}
// Paperless?
if (paperless) {
}
}
```
This is some more boilerplate that makes sure we respect the `complete`, `sa`, and `paperless` settings.
For now, you don't need to worry about this. Let's just start designing our bib.

40
markdown/dev/tutorials/pattern-design/structure/en.md
View file

@ -3,10 +3,40 @@ title: Files and folder structure
order: 110 order: 110
--- ---
With our development setup, let's take a moment to see what sort of files and Inside out `tutorial` folder, the `design/src` folder holds the source code for
folders have been created for us, what they all mean, and where to find what. the new pattern we will create.
You will find the following files and folders inside the newly created folder You can safely ignore all other files and folders, as they are part of the
that holds your development environment: FreeSewing development environment.
So feel free to skip ahead to [Your first part](/tutorials/pattern-design/your-first-part).
## Notes
If you'd like to learn about those other files and folders, here's what they do:
### folders
- `design`: Holds the source code for your design
- `lab`: Holds [React][react] hooks and components specific to the development environment
- `node_modules`: Holds installed dependencies
- `pages`: Holds [NextJS][next] client-side routes, aka pages
- `public`: Holds pregenerated translation files
- `shared`: Holds files from FreeSewing's shared codebase for frontend development
### files
- `next.config.mjs`: The [NextJS][next] configuration file
- `next-i18next.config.js`: The configuration file for [next-i18next][i81n] which handles translation within NextJS
- `package.json`: Every NodeJS project has a [package.json][pkg] file which holds important metadata and lists dependencies
- `package-lock.json`: This *lockfile* will only exist if you use the npm package manager
- `postcss.config.js`: Configuration file for [PostCSS][postcss], a tool to transform CSS with Javascript
- `tailwind.config.js`: Configuration file for the [TailwindCSS][tailwind] framework
- `yarn.lock`: This *lockfile* will only exist if you use [the yarn package manager][yarn]
[next]: https://nextjs.org/
[tailwind]: https://tailwindcss.com/
[postcss]: https://postcss.org/
[yarn]: https://yarnpkg.com/
[pkg]: https://docs.npmjs.com/cli/v8/configuring-npm/package-json
[react]: https://reactjs.org/
<Fixme compact>Update this for v3</Fixme>

159
markdown/dev/tutorials/pattern-design/your-first-part/en.md
View file

@ -4,74 +4,137 @@ order: 120
--- ---
Much like garments themselves, patterns are made up of _parts_. Much like garments themselves, patterns are made up of _parts_.
Most patterns will have multiple parts. A sleeve, a back part, the collar, and
so on. Our pattern is very simple, and only has one part: the bib.
Most patterns will have multiple parts. A sleeve, a back part, the collar, and so on. It's a good idea to keep each part in its own file. You don't *have to* do
Our pattern is very simple, and only has one part: the bib. this, but it's a good habit to get into. When you create more elaborate designs
with multiple parts, keeping each in its own file makes for a more tidy
and approachable code base.
The pattern that's been created for us also just has one part to get you started. ## bib.mjs
It's called **box** and it draws a box. If you click on the **To your design**
button in your browser, you'll get to see it:
![The default pattern with its box part](./step1.png) The previous step has already set everything up for us. Our design's main file
lives in `design/src/index.mjs`, and our part lives in `design/src/bib.mjs`.
Since we only need one part, we'll rename this _box_ part, and call it _bib_. This `bib.mjs` is where we'll do all our work. It currently looks like this:
## Rename the box part to bib ```design/src/bib.mjs
function draftBib({ part }) {
First, update the configuration file in `design/config.js`. return part
Update the **parts** array with `bib`, rather than `box`: }
```js export const bib = {
parts: ['bib'], name: 'tutorial.bib',
draft: draftBib,
}
``` ```
<Note> ### The part object
##### Don't worry about the big red error Each part in FreeSewing is an object that describes everything there is to know about the part.
This will (temporarily) cause en error to appear in your development environment, because the rest of the code is still expecting to find a part named `box`, but we will fix this in the next steps. The only mandatory keys on a part object are `name` and `draft`.
</Note> <Related>
Refer to [the part reference documentation](/reference/api/part) for
all details about configuring the part object
</Related>
When that's done, rename the `design/src/box.js` file into `design/src/bib.js`. #### The part name
Then, in the `design/src/index.js` file, change the import accordingly: ```design/src/bib.mjs
name: 'tutorial.bib',
```js
// Change this line
//import draftBox from "./box"
// Into this
import draftBib from "./bib"
``` ```
Finally, still in the `design/src/index.js` file, update the draft method: A part's `name` should be unique in a pattern. Apart from that, anything goes.
Although you probably want to give it a sensible name.
```js As you can see in the example above, we're using `tutorial.bib` as the name.
// Change this line
//Design.prototype.draftBox = draftBox
// Into this
Design.prototype.draftBib = draftBib
```
<Tip> <Tip>
We **strongly** recommend to follow this `design.part` naming scheme to avoid
###### Always use draftPartname naming conflicts when mixing parts from various designs to create new designs.
FreeSewing will expect for each part to find a method named Draft\_Partname\_.
If you have a part named `sleeve` you should have a method called `draftSleeve()` that drafts that part.
In our case, we have a part named `bib` so we're using `draftBib()` as the method that drafts it.
</Tip> </Tip>
Congratulations, your pattern now has a `bib` part, rather than a `box` part. #### The part's draft method
It still looks the same though:
<Example pattern="tutorial" part="step1"> ```design/src/bib.mjs
Our bib part, which is the renamed box part draft: draftBib,
</Example> ```
This `bib` part is where we'll do some real work. But first, we have some more configuration to do. The second mandatory key on the part object is `draft` which should hold the method that drafts the part.
In our example above, it refers to the `draftBib` function we defined at the top of the file.
For now this function doesn't do much, but that will change soon enough.
<Note>
This structure of putting the draft method at the top of the file and
the part object at the bottom is a bit of a convention in FreeSewing.
</Note>
## index.mjs
<Tip>
Feel free to skip to [Adding
measurements](/tutorials/pattern-design/adding-measurements) if you're itching
to get started. Or, read on for an explanation of what's going on in the
`index.mjs` file.
</Tip>
The `index.mjs` file is already complete and we won't be making any changes to
it. But for those who are curious about what's going on inside `index.mjs`,
we're including a version with comments below:
```design/src/index.mjs
/*
* Import the `Design` constructor
* from the FreeSewing core library
*
* This Design constructor is a method
* (also known as a function)
* that creates a new Design
*/
import { Design } from '@freesewing/core'
/*
* Import the `bib` part from the bib.mjs file
* in the same folder as this index.mjs file
*
* This is the part we'll be working on
* in this tutorial
*/
import { bib } from './bib.mjs'
/*
* Create a new Pattern by passing
* a configuration object
* to the Design contructor
*/
const Pattern = new Design({
/*
* This `data` key is optional, but we
* typically add a name and version here
*/
data: {
version: "0.0.1",
name: "Tutorial",
},
/*
* This `parts` key is the most important thing
* It holds a list of `parts` for our Design.
* A Pattern/Design is in the end not much more
* than a collection of parts.
*/
parts: [ bib ],
})
/*
* We are exporting our Pattern
* (so others can use it)
* but we also (re-)export our bib part
* this allows others to re-use it
* in their own designs
*/
export { bib, Pattern }
```