diff --git a/aio/content/guide/schematics-for-libraries.md b/aio/content/guide/schematics-for-libraries.md index 4bbe506f79..6b02e2c536 100644 --- a/aio/content/guide/schematics-for-libraries.md +++ b/aio/content/guide/schematics-for-libraries.md @@ -21,18 +21,18 @@ The following steps show you how to add initial support without modifying any pr 1. Edit the `collection.json` file to define the initial schema for your collection. - - + + - * The `$schema` path is relative to the Angular Devkit collection schema. - * The `schematics` object describes the named schematics that are part of this collection. - * The first entry is for a schematic named `ng-add`. It contains the description, and points to the factory function that is called when your schematic is executed. + * The `$schema` path is relative to the Angular Devkit collection schema. + * The `schematics` object describes the named schematics that are part of this collection. + * The first entry is for a schematic named `ng-add`. It contains the description, and points to the factory function that is called when your schematic is executed. 1. In your library project's `package.json` file, add a "schematics" entry with the path to your schema file. The Angular CLI uses this entry to find named schematics in your collection when it runs commands. - - + + The initial schema that you have created tells the CLI where to find the schematic that supports the `ng add` command. Now you are ready to create that schematic. @@ -48,8 +48,8 @@ The following steps will define this type of schematic. 1. Open `index.ts` and add the source code for your schematic factory function. - - + + The only step needed to provide initial `ng add` support is to trigger an installation task using the `SchematicContext`. The task uses the user's preferred package manager to add the library to the project's `package.json` configuration file, and install it in the project’s `node_modules` directory. @@ -85,21 +85,21 @@ To tell the library how to build the schematics, add a `tsconfig.schematics.json 1. Edit the `tsconfig.schematics.json` file to add the following content. - - + + - * The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled. + * The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled. - * The `outDir` maps to the library's output folder. By default, this is the `dist/my-lib` folder at the root of your workspace. + * The `outDir` maps to the library's output folder. By default, this is the `dist/my-lib` folder at the root of your workspace. 1. To make sure your schematics source files get compiled into the library bundle, add the following scripts to the `package.json` file in your library project's root folder (`projects/my-lib`). - - + + - * The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file. - * The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure. - * The `postbuild` script copies the schematic files after the `build` script completes. + * The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file. + * The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure. + * The `postbuild` script copies the schematic files after the `build` script completes. ## Providing generation support @@ -119,20 +119,20 @@ When you add a schematic to the collection, you have to point to it in the colle 1. Edit the `schematics/collection.json` file to point to the new schematic subfolder, and include a pointer to a schema file that will specify inputs for the new schematic. - - + + 1. Go to the `/schematics/my-service/` folder. 1. Create a `schema.json` file and define the available options for the schematic. - - + + - * *id*: A unique id for the schema in the collection. - * *title*: A human-readable description of the schema. - * *type*: A descriptor for the type provided by the properties. - * *properties*: An object that defines the available options for the schematic. + * *id*: A unique id for the schema in the collection. + * *title*: A human-readable description of the schema. + * *type*: A descriptor for the type provided by the properties. + * *properties*: An object that defines the available options for the schematic. Each option associates key with a type, description, and optional alias. The type defines the shape of the value you expect, and the description is displayed when the user requests usage help for your schematic. @@ -141,12 +141,12 @@ When you add a schematic to the collection, you have to point to it in the colle 1. Create a `schema.ts` file and define an interface that stores the values of the options defined in the `schema.json` file. - - + + - * *name*: The name you want to provide for the created service. - * *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory. - * *project*: Provides a specific project to run the schematic on. In the schematic, you can provide a default if the option is not provided by the user. + * *name*: The name you want to provide for the created service. + * *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory. + * *project*: Provides a specific project to run the schematic on. In the schematic, you can provide a default if the option is not provided by the user. ### Add template files @@ -189,18 +189,18 @@ For details of these data structures and syntax, see the [Schematics README](htt 1. First, import the schematics definitions you will need. The Schematics framework offers many utility functions to create and use rules when running a schematic. - - + + 1. Import the defined schema interface that provides the type information for your schematic's options. - - + + 1. To build up the generation schematic, start with an empty rule factory. - - + + This rule factory returns the tree without modification. The options are the option values passed through from the `ng generate` command. @@ -222,31 +222,31 @@ The `Tree` methods give you access to the complete file tree in your workspace, To use `workspaces.readWorkspace` you need to create a `workspaces.WorkspaceHost` from the `Tree`. Add the following code to your factory function. - - + + - * Be sure to check that the context exists and throw the appropriate error. + Be sure to check that the context exists and throw the appropriate error. -1. The `WorkspaceDefinition`, `extensions` property includes a `defaultProject` value for determining which project to use if not provided. +1. The `workspace.extensions` property includes a `defaultProject` value for determining which project to use if not provided. We will use that value as a fallback, if no project is explicitly specified in the `ng generate` command. - - + + 1. Now that you have the project name, use it to retrieve the project-specific configuration information. - - + + - The `workspace projects` object contains all the project-specific configuration information. + The `workspace.projects` object contains all the project-specific configuration information. 1. The `options.path` determines where the schematic template files are moved to once the schematic is applied. The `path` option in the schematic's schema is substituted by default with the current working directory. If the `path` is not defined, use the `sourceRoot` from the project configuration along with the `projectType`. - - + + ### Define the rule @@ -254,25 +254,25 @@ A `Rule` can use external template files, transform them, and return another `Ru 1. Add the following code to your factory function. - - + + - * The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules. - * The `url()` method reads source files from your filesystem, relative to the schematic. - * The `applyTemplates()` method receives an argument of methods and properties you want make available to the schematic template and the schematic filenames. It returns a `Rule`. This is where you define the `classify()` and `dasherize()` methods, and the `name` property. - * The `classify()` method takes a value and returns the value in title case. For example, if the provided name is `my service`, it is returned as `MyService` - * The `dasherize()` method takes a value and returns the value in dashed and lowercase. For example, if the provided name is MyService, it is returned as `my-service`. - * The `move` method moves the provided source files to their destination when the schematic is applied. + * The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules. + * The `url()` method reads source files from your filesystem, relative to the schematic. + * The `applyTemplates()` method receives an argument of methods and properties you want make available to the schematic template and the schematic filenames. It returns a `Rule`. This is where you define the `classify()` and `dasherize()` methods, and the `name` property. + * The `classify()` method takes a value and returns the value in title case. For example, if the provided name is `my service`, it is returned as `MyService` + * The `dasherize()` method takes a value and returns the value in dashed and lowercase. For example, if the provided name is MyService, it is returned as `my-service`. + * The `move` method moves the provided source files to their destination when the schematic is applied. 1. Finally, the rule factory must return a rule. - - + + - The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic. - Here you are only merging the template rules with any code executed by the schematic. + The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic. + Here you are only merging the template rules with any code executed by the schematic. -See a complete exampled of the schematic rule function. +See a complete example of the schematic rule function below.