79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# Overview
|
|
|
|
[Plunker](http://plnkr.co) is an online tool for creating, collaborating and sharing ideas. In AIO
|
|
we use it to share one or more runnable versions of our examples.
|
|
|
|
Plunker comes in two flavours. The [classic UI](http://plnkr.co/edit) and an [embedded UI](http://embed.plnkr.co).
|
|
The latter can be used both in a new tab or embedded within a guide. The AIO project uses the
|
|
embedded version in both ways.
|
|
|
|
* `regularPlunker.js` - generates an HTML file for each example that will post to Plunker to create
|
|
a new editable project, when rendered.
|
|
* `embeddedPlunker.js` - generates an HTML file for each example that can be used in an iframe to
|
|
render an embedded Plunker project.
|
|
* `generatePlunkers.js` - executes each of the `regularPlunker.js` and `embeddedPlunker.js` utilities
|
|
to generate all the example plunker files.
|
|
|
|
## Plunker generation
|
|
|
|
Both flavours are created within `builder.js`. How is a plunker created? What is the process from a
|
|
directory with files to a link with a plunker.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
So the `builder.js` job is to get all the needed files from an example and build this HTML file for you.
|
|
|
|
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.
|
|
|
|
## Customizing the generation per example basis
|
|
|
|
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`.
|
|
|
|
You can use the `plnkr.json` to customize the plunker generation. For example:
|
|
|
|
```json
|
|
{
|
|
"description": "Tour of Heroes: Part 6",
|
|
"basePath": "src/",
|
|
"files":[
|
|
"!**/*.d.ts",
|
|
"!**/*.js",
|
|
"!**/*.[1,2].*"
|
|
],
|
|
"tags": ["tutorial", "tour", "heroes", "http"]
|
|
}
|
|
```
|
|
|
|
Here you can specify a description for the plunker, some tags, a basePath and also a files array where you
|
|
can specify extra files to add or to ignore.
|
|
|
|
## Classic plunkers and embedded ones
|
|
|
|
Luckily, both kind of plunkers are very similar, they are created in the same way with minor exceptions.
|
|
|
|
To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlunker.js`. Thanks to them,
|
|
the `builder.js` is as generic as possible.
|
|
|
|
## Executing the plunker generation
|
|
|
|
`generatePlunkers.js` will create a classic plunker and an embedded plunker for each `plnkr.json` it finds.
|
|
|
|
Where? At `src/generated/live-examples/`.
|
|
|
|
Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the
|
|
example.
|
|
|
|
## Appendix: Why not generating plunkers at runtime?
|
|
|
|
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~.
|