diff --git a/markdown/dev/tutorials/pattern-design/adding-measurements/en.md b/markdown/dev/tutorials/pattern-design/adding-measurements/en.md index d21e683e8fa..088bda1982a 100644 --- a/markdown/dev/tutorials/pattern-design/adding-measurements/en.md +++ b/markdown/dev/tutorials/pattern-design/adding-measurements/en.md @@ -8,28 +8,36 @@ we are going to draft our pattern according to the measurements provided to us. Which begs the question, which measurements? -It is you, as the pattern designer, who decides which measurements are required to draft your pattern. -For our bib, the only measurement we need is the baby's _head circumference_. +It is you, as the pattern designer, who decides which measurements are used +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. -## 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 -measurements: ["head"], +We are going to use *the official name* of the measurement. For 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'], +} ``` - - -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. - - - -Now everybody knows your pattern requires the `head` measurement. +Now everybody knows this part requires the `head` measurement. 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. This brings you back to our work in progress: -Nothing has changed, yet + +## 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. + + diff --git a/markdown/dev/tutorials/pattern-design/adding-options/en.md b/markdown/dev/tutorials/pattern-design/adding-options/en.md index 8fbd3f8ca17..e9f66af31b0 100644 --- a/markdown/dev/tutorials/pattern-design/adding-options/en.md +++ b/markdown/dev/tutorials/pattern-design/adding-options/en.md @@ -13,22 +13,30 @@ 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. 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 The first option we're going to add controls the ratio between the neck opening 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: { - // Remove this size option - //size: { pct: 50, min: 10, max: 100 } - // And add the neckRatio options - neckRatio: { pct: 80, min: 70, max: 90 }, - } + neckRatio: { pct: 80, min: 70, max: 90, menu: 'fit' }, + }, +} ``` Can you guess what it means? @@ -37,49 +45,39 @@ Can you guess what it means? - Its minimum value is 70% - Its maximum value is 90% - Its default value is 80% +- We've added this option to the *fit* menu 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). +## Add the widthRatio and lengthRatio options + Let's do something similar for the width and length of our bib: -```js +```design/src/bib.mjs options: { - neckRatio: { pct: 80, min: 70, max: 90 }, - widthRatio: { pct: 45, min: 35, max: 55 }, - lengthRatio: { pct: 75, min: 55, max: 85 }, + neckRatio: { pct: 80, min: 70, max: 90, menu: 'fit' }, + widthRatio: { pct: 45, min: 35, max: 55, menu: 'style' }, + lengthRatio: { pct: 75, min: 55, max: 85, menu: 'style' }, } ``` - You've added `widthRatio` and `lengthRatio` options - You've given all options sensible defaults - You've given all options sensible maximum and minimum boundaries - - +- You've added these two new options to the *style* menu 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. - +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 -optionGroups: { - fit: ["neckRatio", "widthRatio", "lengthRatio"] -}, -``` - - - -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. - - - -Because you have removed the `box` option, the pattern no longer draws a box. -So let's start drawing your bib instead. +The `menu` key on an option 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. diff --git a/markdown/dev/tutorials/pattern-design/draft-structure/en.md b/markdown/dev/tutorials/pattern-design/draft-structure/en.md new file mode 100644 index 00000000000..08f48f78f6f --- /dev/null +++ b/markdown/dev/tutorials/pattern-design/draft-structure/en.md @@ -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*. + + + +If you're new to JavaScript, and don't intuitively _get this_, stick with it. It will become second nature soon enough. + + + +## 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. diff --git a/markdown/dev/tutorials/pattern-design/en.md b/markdown/dev/tutorials/pattern-design/en.md index e0872bc9dec..5af9132c11b 100644 --- a/markdown/dev/tutorials/pattern-design/en.md +++ b/markdown/dev/tutorials/pattern-design/en.md @@ -11,7 +11,7 @@ translate your designs into code. At the end of this tutorial, you will have created this pattern: -Your end result + Before we can get started, let's make sure you have the required software installed on your computer: diff --git a/markdown/dev/tutorials/pattern-design/new-design/en.md b/markdown/dev/tutorials/pattern-design/new-design/en.md index 8421b174941..2acb7ac08c7 100644 --- a/markdown/dev/tutorials/pattern-design/new-design/en.md +++ b/markdown/dev/tutorials/pattern-design/new-design/en.md @@ -6,14 +6,15 @@ order: 100 Open a terminal and enter the following command: ```sh -npx @freesewing/new-design +npx @freesewing/new-design@next ``` +Remove `@next` suffix once v3 is in production -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 name would you like the design to have**: Enter `bib` -- **What package manager do you use?**: Pick `npm` unless you are certain you have `yarn` installed +- *What template would you like to use?* — Pick the default: **Tutorial** +- *What package manager should we use?* — Pick the default: **npm**, unless you are certain you have **yarn** installed 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 -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 -cd bib +cd tutorial npm run dev ``` -Or if you chose to use Yarn as package manager: +Or if you chose to use yarn as package manager: ```sh -cd bib +cd tutorial yarn dev ``` @@ -43,11 +44,9 @@ If all goes well, you should see this landing page: ![The FreeSewing development environment](./nd.png) - +## Notes -###### Need help? +### Need help? 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. - - diff --git a/markdown/dev/tutorials/pattern-design/part-structure/en.md b/markdown/dev/tutorials/pattern-design/part-structure/en.md deleted file mode 100644 index 4119dd74c5e..00000000000 --- a/markdown/dev/tutorials/pattern-design/part-structure/en.md +++ /dev/null @@ -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. - - - -If you're new to JavaScript, and don't intuitively _get this_, stick with it. It will become second nature soon enough. - - - -## 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. - - - -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). - - - -## 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. diff --git a/markdown/dev/tutorials/pattern-design/structure/en.md b/markdown/dev/tutorials/pattern-design/structure/en.md index 7438f68359a..59ae45b242b 100644 --- a/markdown/dev/tutorials/pattern-design/structure/en.md +++ b/markdown/dev/tutorials/pattern-design/structure/en.md @@ -3,10 +3,40 @@ title: Files and folder structure order: 110 --- -With our development setup, let's take a moment to see what sort of files and -folders have been created for us, what they all mean, and where to find what. +Inside out `tutorial` folder, the `design/src` folder holds the source code for +the new pattern we will create. -You will find the following files and folders inside the newly created folder -that holds your development environment: +You can safely ignore all other files and folders, as they are part of the +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/ -Update this for v3 diff --git a/markdown/dev/tutorials/pattern-design/your-first-part/en.md b/markdown/dev/tutorials/pattern-design/your-first-part/en.md index 9c4bce3c425..cb66476ba9c 100644 --- a/markdown/dev/tutorials/pattern-design/your-first-part/en.md +++ b/markdown/dev/tutorials/pattern-design/your-first-part/en.md @@ -4,74 +4,137 @@ order: 120 --- 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. -Our pattern is very simple, and only has one part: the bib. +It's a good idea to keep each part in its own file. You don't *have to* do +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. -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: +## bib.mjs -![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`. -Update the **parts** array with `bib`, rather than `box`: + return part +} -```js -parts: ['bib'], +export const bib = { + name: 'tutorial.bib', + draft: draftBib, +} ``` - +### 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`. - + +Refer to [the part reference documentation](/reference/api/part) for +all details about configuring the part object + -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: - -```js -// Change this line -//import draftBox from "./box" - -// Into this -import draftBib from "./bib" +```design/src/bib.mjs + name: 'tutorial.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 -// Change this line -//Design.prototype.draftBox = draftBox - -// Into this -Design.prototype.draftBib = draftBib -``` +As you can see in the example above, we're using `tutorial.bib` as the name. - -###### Always use draftPartname - -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. - +We **strongly** recommend to follow this `design.part` naming scheme to avoid +naming conflicts when mixing parts from various designs to create new designs. -Congratulations, your pattern now has a `bib` part, rather than a `box` part. -It still looks the same though: +#### The part's draft method - -Our bib part, which is the renamed box part - +```design/src/bib.mjs + draft: draftBib, +``` -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. + + +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. + + +## index.mjs + + +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. + + +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 } +```