History

George Kalpakas 2e4244d521 fix(docs-infra): fix `elements` example when used with ES5 (#36536 ) Previously, the `elements` docs example only worked in browsers that natively supported Custom Elements and ES2015 modules. Furthermore, it didn't work on StackBlitz, because StackBlitz ignores the specified `target` in `tsconfig.json` and uses the UMD bundles (i.e. ES5 code) even on browsers that do support ES2015. (NOTE: In the past, this was not a problem, because we explicitly did not provide a StackBlitz example. This has changed in #36067.) This commit ensures the example works on all browsers and also on StackBlitz by providing the necessary Custom Elements polyfills. Fixes #36532 PR Close #36536		2020-04-09 13:35:27 -07:00
..
customizer/package-json	fix(docs-infra): fix `elements` example when used with ES5 (#36536 )	2020-04-09 13:35:27 -07:00
README.md	build(docs-infra): remove obsolete properties from `zipper.json` files (#36018 )	2020-03-27 10:48:30 -07:00
exampleZipper.js	build(docs-infra): do not include CI-specific config in docs examples ZIP archives (#36018 )	2020-03-27 10:48:30 -07:00
generateZips.js	build(aio): rename `src/content` to `src/generated`	2017-05-03 13:40:46 -07:00

README.md

Overview

In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file. These zip files are generated by the utility in this folder.

Example zipper

The exampleZipper.js tool is very similar to the Stackblitz's builder.js. The latter creates an HTML file with all the examples' files and the former creates a zip file instead. They both use the stackblitz.json file to flag an example as something to stackblitz or zip. For example:

{
  "description": "Tour of Heroes: Part 6",
  "files":[
    "!**/*.d.ts",
    "!**/*.js",
    "!**/*.[1,2].*"
  ],
  "tags": ["tutorial", "tour", "heroes", "http"]
}

The zipper will use this information for creating new zips.

Three kinds of examples

The majority of examples in AIO use CLI, with some additionally using Webpack and upgrade usiing SystemJS. This tool is able to differentiate between them.

The boilerplate uses a package.json that contains packages and scripts to run any kind of example. Using that package.json in the zips would confuse the users.

Thanks to the package.json customizer, we can create a new package.json on the fly that would only contain the packages and scripts needed to run that example.

The exampleZipper.js won't include any System.js related files for CLI or Webpack projects.

The package.json customizer

Given a type, this tool will populate a package.json file customized for that type.

Here you find a:

base.json - All the common scripts and packages
cli.json - Extra scripts and packages for the CLI
universal.json - Extra scripts and packages for universal
i18n.json - Extra scripts and packages for i18n
systemjs.json - All the System.js related packages but it also contains the remainder scripts that are not in the other files.

The tool will also give some standard names to the scripts.

The zipper.json

As mentioned, the tool uses the stackblitz.json as a flag and also a configuration file for the zipper. The problem is that not all examples have a stackblitz but they could offer a zip instead.

In those cases, you can create a zipper.json file with the same syntax. It will be ignored by the stackblitz tool.

Executing the zip generation

generateZips.js will create a zip for each stackblitz.json or zipper.json it finds.

Where? At src/generated/zips/.

Then the <live-example> embedded component will look at this folder to get the zip it needs for the example.