"Fossies" - the Fresh Open Source Software Archive

Member "angular-14.0.3/aio/tools/examples/README.md" (22 Jun 2022, 8893 Bytes) of package /linux/www/angular-14.0.3.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.


Overview

Many of the documentation pages contain snippets of code examples. These snippets are extracted from real working example applications, which are stored in sub-folders of the aio/content/examples/ folder. Each example can be built and run independently. Each example also provides tests (mostly e2e and occasionally unit tests), which are run as part of our CircleCI test_docs_examples* jobs, to verify that the examples continue to work as expected, as changes are made to the core Angular libraries.

In order to build, run and test these examples independently, you need to install dependencies into their sub-folder. Also there are a number of common boilerplate files that are needed to configure each example's project. These common boilerplate files are maintained centrally to reduce the amount of effort if one of them needs to change.

Note for Windows users

Setting up the examples involves creating some symbolic links (see here for details). On Windows, this requires to either have Developer Mode enabled (supported on Windows 10 or newer) or run the setup commands as administrator.

Boilerplate overview

As mentioned above, many of the documentation pages contain snippets extracted from real example applications. To achieve that, all those applications need to contain some basic boilerplate, such as a node_modules/ folder, a package.json file with scripts and dependencies, etc.

There are also different project types, each with its own boilerplate. For example, there are projects based on the Angular CLI, projects that use AngularJS, Custom Elements, i18n, server-side rendering, etc. (See the example configuration section below for more info on how to specify the project type.)

To avoid having to maintain the boilerplate in each example, we use the example-boilerplate-js script to provide a set of files that works across all the examples of a specific type.

Boilerplate files

Inside shared/boilerplate/ there is a sub-folder with boilerplate files for each of the different project types.

Currently, the following project types are supported:

There are also the following special folders:

The example-config.json

Each example is identified by an example-config.json configuration file in its root folder. This configuration file indicates what type of boilerplate this example needs and how to test it. For example:

{
  "projectType": "cli"
}

The file is expected to contain a JSON object with zero or more of the following properties:

SystemJS-only properties:

CLI-only properties:

An empty example-config.json file is equivalent with {"projectType": "cli"}.

A node_modules/ to share

With all the boilerplate files in place, the only missing piece is the installed packages. For that we have shared/package.json, which contains all the packages needed to run any example type.

Upon installing these dependencies, a shared/node_modules/ folder is created. This folder will be symlinked into each example. So it is not a copy like the other boilerplate files.

End-to-end tests

End-to-end infrastructure is slightly different between CLI- and SystemJS-based examples.

For CLI-based examples, create an app.e2e-spec.ts file inside the e2e/ folder. This will be picked up by the default testing command (see the example configuration section above). If you are using a custom test command, make sure e2e specs are picked up (if applicable).

For SystemJS-based examples, create an e2e-spec.ts file inside the example root folder. These apps will be tested with the following command (and an optional outputFile to receive log messages):

yarn protractor [--params.outputFile=path/to/logfile.txt]

example-boilerplate.js

The example-boilerplate.js script manages the dependencies for all examples.

run-example-e2e.mjs

The run-example-e2e.mjs script will find and run the e2e tests for all examples. Although it only runs e2e tests by default, it can be configured to run any test command (for CLI-based examples) by using the tests property of the example-config.json file. It is named *-e2e for historical reasons, but it is not limited to running e2e tests.

See aio/README.md for the available command-line options.

Running the script will create an aio/protractor-results.txt file with the results of the tests.

create-example.js

The create-example.js script creates a new example under the aio/content/examples directory.

You must provide a new name for the example. By default the script will place basic scaffold files into the new example (from shared/example-scaffold). But you can also specify the path to a separate CLI project, from which the script will copy files that would not be considered "boilerplate". See the Boilerplate overview for more information.

Updating example dependencies

With every major Angular release, we update the examples to be on the latest version. See UPDATING.md for instructions.