You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: aio/tools/README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,5 +65,5 @@ into files that are consumed by the AIO application.
65
65
Dgeni is configured by "packages", which contain services and processors. Some of these packages are installed as `node_modules`
66
66
from the [dgeni-packages](https://github.com/angular/dgeni-packages) and some are specific to the AIO project.
67
67
68
-
The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](plunker-builder/README.md)
69
-
for more details.
68
+
The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](transforms/README.md)
Copy file name to clipboardExpand all lines: aio/tools/example-zipper/README.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ In the AIO application, we offer the reader the option to download each example
4
4
5
5
## Example zipper
6
6
7
-
The `exampleZipper.js` tool is very similar to the Plunker'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 `plnkr.json` file to flag an example as something to plunker a zip. For example:
7
+
The `exampleZipper.js` tool is very similar to the Plunker'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 `plnkr.json` file to flag an example as something to plunker or zip. For example:
8
8
9
9
```json
10
10
{
@@ -21,11 +21,11 @@ The `exampleZipper.js` tool is very similar to the Plunker's `builder.js`. The
21
21
22
22
The zipper will use this information for creating new zips.
23
23
24
-
## Three kind of examples
24
+
## Three kinds of examples
25
25
26
26
The majority of examples in AIO use `System.js` but there are also `CLI` and `Webpack` projects. This tool is able to differentiate between them.
27
27
28
-
The boilerplate uses a `package.json` that contains packages and scripts tags to run any kind of example. Using that `package.json` in the zips would confuse the users.
28
+
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.
29
29
30
30
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.
31
31
@@ -40,19 +40,19 @@ Here you find a:
40
40
***base.json** - All the common scripts and packages
41
41
***cli.json** - Extra scripts and packages for the CLI
42
42
***webpack.json** - Extra scripts and packages for Webpack
43
-
***systemjs.json** - All the system.js related packages but it also contains the remainder scripts that are not in the other files.
43
+
***systemjs.json** - All the System.js related packages but it also contains the remainder scripts that are not in the other files.
44
44
45
45
The tool will also give some standard names to the scripts.
46
46
47
47
## The zipper.json
48
48
49
49
As mentioned, the tool uses the `plnkr.json` as a flag and also a configuration file for the zipper. The problem is that not all examples have a plunker but they could offer a zip instead.
50
50
51
-
In those cases, you can create a `zipper.json` file with with the same syntax. It will be ignored by the plunker tool.
51
+
In those cases, you can create a `zipper.json` file with the same syntax. It will be ignored by the plunker tool.
52
52
53
53
## Choosing the zip "type"
54
54
55
-
In both `plnkr.json` and `zipper.json` you can use two new properties:
55
+
In both `plnkr.json` and `zipper.json` you can use two extra properties for the zipper configuration:
56
56
57
57
```
58
58
{
@@ -62,12 +62,12 @@ In both `plnkr.json` and `zipper.json` you can use two new properties:
62
62
}
63
63
```
64
64
65
-
This would generate a .zip for a webpack application and it will also remove everything related with SystemJS.
65
+
This would generate a zip for a webpack application and it will also remove everything related with SystemJS.
66
66
67
67
## Executing the zip generation
68
68
69
-
`generateSipz.js` will create a zip for each `plnk.json` or `zipper.json` it finds.
69
+
`generateZips.js` will create a zip for each `plnkr.json` or `zipper.json` it finds.
70
70
71
-
Where? at`src/generated/zips/`.
71
+
Where? At`src/generated/zips/`.
72
72
73
73
Then the `<live-example>` embedded component will look at this folder to get the zip it needs for the example.
Copy file name to clipboardExpand all lines: aio/tools/examples/README.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ In order to build, run and test these examples independently we need to install
6
6
7
7
## Boilerplate overview
8
8
9
-
As mentioned, many of the documentation pages contains snippets extracted from real example applications. To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules` folder, `package.json` with scripts, `system.js` configuration, etc.
9
+
As mentioned, many of the documentation pages contain snippets extracted from real example applications. To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules` folder, `package.json` with scripts, `system.js` configuration, etc.
10
10
11
11
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a generic boilerplate that works in all the examples.
12
12
@@ -18,17 +18,17 @@ Among these files, there are a few special ones:
18
18
19
19
***src/systemjs.config.js** - This is the configuration of System.js used to run the example locally.
20
20
***src/systemjs.config.web.js** - This configuration replaces the previous one on Plunkers.
21
-
***/src/systemjs.config.web.build.js** - Same as the previous one but for `-builds` versions.
21
+
***/src/systemjs.config.web.build.js** - Same as the previous one but for using angular's `-builds` versions.
22
22
***src/systemjs-angular-loader.js** - It is a System.js plugin that removes the need of `moduleId`.
23
-
***package.json** - This package.json only contains script tags, no dependencies. It contains the different tasks needed to run any example. Doesn't matter if CLI, System.js or Webpack.
24
-
***plnkr.json** - This file is used by the Plunker tool to generate a plunker for an example. This concrete file is just a placeholder. Authors needs to tweak it for each guide.
23
+
***package.json** - This package.json only contains scripts, no dependencies. It contains the different tasks needed to run any example. Doesn't matter if CLI, System.js or Webpack.
24
+
***plnkr.json** - This file is used by the Plunker tool to generate a plunker for an example. This concrete file is just a placeholder. Authors needs to tweak it for each guide. More at the [plunker docs](../plunker-builder/README.md).
25
25
***example-config.json** - This file serves as a flag to indicate that the current folder is an example. This concrete file is just a placeholder. More on this later in this readme.
26
26
27
27
### The example-config.json
28
28
29
29
So what is this **example-config.json** again? If an author wants to create a new example, say `/aio/content/examples/awesome-example`. The author needs to create an empty `example-config.json` in that folder. That serves as a flag so this tool will say "Hey, that is an example, let's copy all the boilerplate there".
30
30
31
-
So when the tool runs, it finds **all** the folders with a`example-config.json` file, and puts a copy of the boilerplate in those folders.
31
+
So when the tool runs, it finds **all** the folders with an`example-config.json` file, and puts a copy of the boilerplate in those folders.
32
32
33
33
Normally the file is empty, but we can add information in it, for example:
34
34
@@ -46,7 +46,7 @@ In this case, this would indicate that this is a CLI example. Won't make any dif
46
46
47
47
With all the boilerplate files in place, the only missing piece are the installed packages. For that we have a `/aio/tools/examples/shared/package.json` which contains **all** the packages needed to run all the examples.
48
48
49
-
After installing this dependencies, a `node_modules` will be created at `/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example. So it is not a copy like the other boilerplate files. This solution works in all OSes.
49
+
After installing these dependencies, a `node_modules` will be created at `/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example. So it is not a copy like the other boilerplate files. This solution works in all OSes. Windows may require admin rights.
50
50
51
51
### End to end tests
52
52
@@ -56,9 +56,9 @@ This tool expects all the examples to be build with `npm run build`. If an examp
56
56
57
57
### add-example-boilerplate.js
58
58
59
-
This script install all the dependencies that are shared among all the examples, creates the `node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything about plunkers nor e2e tests.
59
+
This script installs all the dependencies that are shared among all the examples, creates the `node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything about plunkers nor e2e tests.
60
60
61
-
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do the job. It will remove all files that doesn't exist in the git repository, **including any new file that you are working on that hasn't been stage yet.** So be sure to save your work before removing the boilerplate.
61
+
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do the job. It will remove all files that don't exist in the git repository, **including any new file that you are working on that hasn't been stage yet.** So be sure to save your work before removing the boilerplate.
Copy file name to clipboardExpand all lines: aio/tools/plunker-builder/README.md
+8-6Lines changed: 8 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,13 +10,15 @@ Both flavours are created within `builder.js`. How is a plunker created? What is
10
10
11
11
An "executable" plunker is an HTML file with a `<form>` that makes a post to plunker on submit. It contains an `<input>` element for each file we need in the plunker.
12
12
13
+
The form will be submitted on load, so you can either double click the HTML file or open it with an anchor tag to open the plunker.
14
+
13
15
So the `builder.js` job is to get all the needed files from an example and build this HTML file for you.
14
16
15
-
For plunkers, we use an special `systemjs.config` that exists in `/aio/tools/examples/shared/boilerplate/src/systemjs.config.web.js` and we also add the Google's copyright to each file.
17
+
For plunkers, we use a special `systemjs.config` that exists in `/aio/tools/examples/shared/boilerplate/src/systemjs.config.web.js` and we also add the Google's copyright to each file.
16
18
17
19
## Customizing the generation per example basis
18
20
19
-
How do this tool know about what is an example and what is not? It will look for all folders containing a `plnkr.json` file. If found, all files within the folder and subfolders will be used in the plunker, with a few generic exceptions that you can find at `builder.js`.
21
+
How does this tool know what is an example and what is not? It will look for all folders containing a `plnkr.json` file. If found, all files within the folder and subfolders will be used in the plunker, with a few generic exceptions that you can find at `builder.js`.
20
22
21
23
You can use the `plnkr.json` to customize the plunker generation. For example:
22
24
@@ -37,18 +39,18 @@ Here you can specify a description for the plunker, some tags, a basePath and al
37
39
38
40
## Classic plunkers and embedded ones
39
41
40
-
Luckily, both kind of plunkers are very similar, the are created in the same way with a minor exceptions.
42
+
Luckily, both kind of plunkers are very similar, they are created in the same way with minor exceptions.
41
43
42
44
To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlunker.js`. Thanks to them, the `builder.js` is as generic as possible.
43
45
44
46
## Executing the plunker generation
45
47
46
-
`generatePlunkers.js` will create a classic plunker and a embedded plunker for each `plnk.json` it finds.
48
+
`generatePlunkers.js` will create a classic plunker and an embedded plunker for each `plnkr.json` it finds.
47
49
48
-
Where? at`src/generated/live-examples/`.
50
+
Where? At`src/generated/live-examples/`.
49
51
50
52
Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the example.
51
53
52
-
## Appendix: Why not generating plunkers on runtime?
54
+
## Appendix: Why not generating plunkers at runtime?
53
55
54
56
At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~.
0 commit comments