From 6f7aa466ae7857bef459dacea68ea87ac1313fad Mon Sep 17 00:00:00 2001 From: Jesus Rodriguez Date: Wed, 19 Jul 2017 16:32:28 +0200 Subject: [PATCH] docs(aio): complete the plunker-builder docs (#18151) PR Close #18151 --- aio/tools/plunker-builder/README.md | 56 +++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 6 deletions(-) diff --git a/aio/tools/plunker-builder/README.md b/aio/tools/plunker-builder/README.md index 77966ee47e..41c119aa3a 100644 --- a/aio/tools/plunker-builder/README.md +++ b/aio/tools/plunker-builder/README.md @@ -1,10 +1,54 @@ # Overview -In the AIO application, we can embed a running version of the example as a [Plunker](http://plnkr.co/). We can also provide a -link to create a runnable version of the example in the [Plunker](http://plnkr.co/edit) editor. +[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. -This folder contains three utilities: +Plunker comes in two flavours. The [classic UI](http://plnkr.co/edit) and a [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 `
` that makes a post to plunker on submit. It contains an `` element for each file we need in 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 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. + +## Customizing the generation per example basis + +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`. + +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, the are created in the same way with a 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 a embedded plunker for each `plnk.json` it finds. + +Where? at `src/generated/live-examples/`. + +Then the `` embedded component will look at this folder to get the plunker it needs for the example + +## Appendix: Why not generating plunkers on 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~