Index: app/views/doc/assets-and-transformers.html |
diff --git a/app/views/doc/assets-and-transformers.html b/app/views/doc/assets-and-transformers.html |
deleted file mode 100644 |
index 1b1aaf98c900800b002103eaecfe160364ed27cb..0000000000000000000000000000000000000000 |
--- a/app/views/doc/assets-and-transformers.html |
+++ /dev/null |
@@ -1,182 +0,0 @@ |
-<p>The <a href="pub-serve.html"><code>pub serve</code></a> and <a href="pub-build.html"><code>pub build</code></a> |
-commands use <a href="glossary.html#transformer">transformers</a> to prepare a package’s <a href="glossary.html#asset">assets</a> to be served |
-locally or to be deployed, respectively.</p> |
- |
-<p>Use the <code>pubspec.yaml</code> file to specify which transformers your package uses |
-and, if necessary, to configure the transformers. (See |
-<a href="#specifying-transformers">Specifying transformers</a> for details.) For example:</p> |
- |
-<pre> |
-name: myapp |
-dependencies: |
- <b>polymer: any</b> |
-<b>transformers: |
-- polymer: |
- entry_points: |
- - web/index.html |
- - web/index2.html</b> |
-</pre> |
- |
-<p>A package’s assets must be in one or more of the following directories: |
-<code>lib</code>, <code>asset</code>, and <code>web</code>. After transformation by <code>pub build</code>, assets are |
-available under a directory called <code>build</code>. Assets generated from |
-files in a package’s <code>lib</code> directory appear under a directory named |
-<code>packages/<em><pkg_name></em></code>, and those from the package’s |
-<code>asset</code> directory appear under <code>assets/<em><pkg_name></em></code>. |
-For details, see |
-<a href="#where-to-put-assets">Where to put assets</a> and |
-<a href="#how-to-refer-to-assets">How to refer to assets</a>.</p> |
- |
-<h2 id="how-transformers-work">How transformers work</h2> |
- |
-<p>Here are some examples of transformers:</p> |
- |
-<ul> |
- <li>The dart2js transformer, which reads in all of the <code>.dart</code> files for a |
-program and compiles them to a single <code>.js</code> file.</li> |
- <li>The polymer transformer, which converts HTML and Dart files into |
-optimized HTML and Dart files.</li> |
- <li>A linter that reads in files and produces warnings but no actual file.</li> |
-</ul> |
- |
-<p>Although you specify which transformers to use, you don’t explicitly say |
-which transformers should be applied to which assets. Instead, each |
-transformer determines which assets it can apply itself to. For <code>pub serve</code>, |
-the transformers run when the dev server starts up and whenever a source |
-asset changes. The <code>pub build</code> command runs the transformers once and |
-then exits.</p> |
- |
-<p>As the following figure shows, source assets can pass through, untransformed, |
-and become generated assets. Or a source asset can be transformed, such as a |
-<code>.dart</code> file (along with the <code>.dart</code> files that it refers to) that is |
-compiled to <code>.js</code>.</p> |
- |
-<p><img src="/img/assets-and-transformers.png" alt="a figure showing source assets and generated assets; the .html, .css, and .png files pass through, untransformed; the .dart file is transformed into a .js file (and, for pub serve only, the .dart file is passed through, as well)" /></p> |
- |
-<p>Dart files are a special case. The <code>pub build</code> command doesn’t produce <code>.dart</code> |
-files because browsers in the wild don’t support Dart natively (yet). The <code>pub |
-serve</code> command, on the other hand, does generate <code>.dart</code> assets, because |
-you can use Dartium while you’re developing your app.</p> |
- |
-<h2 id="specifying-transformers">Specifying transformers</h2> |
- |
-<p>To tell pub to apply a transformer to your package’s assets, specify the |
-transformer, as well as the package that contains the transformer, in your |
-package’s <code>pubspec.yaml</code> file. In the following pubspec, the bold lines |
-specify that this package requires the polymer transformer, which is in the |
-polymer package (along with the rest of Polymer.dart):</p> |
- |
-<pre> |
-name: myapp |
-dependencies: |
- <b>polymer: any</b> |
-<b>transformers: |
-- polymer: |
- entry_points: web/index.html</b> |
-</pre> |
- |
-<p>We expect more transformers to be available in the future. You can specify |
-multiple transformers, to run either in parallel (if they’re independent of |
-each other) or in separate phases. To specify that transformers run in |
-parallel, use [<code><em>transformer_1</em>, ..., |
-<em>transformer_n</em></code>]. If order matters, put the transformers on |
-separate lines.</p> |
- |
-<p>For example, consider three transformers, specified as follows:</p> |
- |
-<div class="highlight"><pre><code class="yaml"><span class="l-Scalar-Plain">transformers</span><span class="p-Indicator">:</span> |
-<span class="p-Indicator">-</span> <span class="p-Indicator">[</span><span class="nv">t1</span><span class="p-Indicator">,</span> <span class="nv">t2</span><span class="p-Indicator">]</span> |
-<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">t3</span> |
-</code></pre></div> |
- |
-<p>The <code>t1</code> and <code>t2</code> transformers run first, in parallel. The <code>t3</code> transformer |
-runs in a separate phase, after <code>t1</code> and <code>t2</code> are finished, and can see the |
-outputs of <code>t1</code> and <code>t2</code>.</p> |
- |
-<p>Pub implicitly appends a transformer that converts your Dart code to |
-JavaScript, so your code can run in any modern browser.</p> |
- |
-<h2 id="where-to-put-assets">Where to put assets</h2> |
- |
-<p>If you want a file to be an <em>asset</em>—to either be in or be used to |
-generate files in the built version of your package—then you need to |
-put it under one of the following directories:</p> |
- |
-<ul> |
- <li><code>lib</code>: Dart libraries defining the package’s public API. Visible in all |
-packages that use this package.</li> |
- <li><code>asset</code>: Other public files. Visible in all packages that use this |
-package.</li> |
- <li><code>web</code>: A web app’s static content plus its main Dart file (the one that |
-defines <code>main()</code>). Visible <em>only</em> to this package.</li> |
-</ul> |
- |
-<p>The following picture shows how you might structure your app’s source assets, |
-with your main Dart file under <code>web</code> and additional Dart files under <code>lib</code>.</p> |
- |
-<pre> |
-<em>app</em>/ |
- lib/ |
- *.dart |
- packages/ |
- pck/ |
- lib/ |
- *.dart |
- *.js |
- asset/ |
- *.png |
- *.html |
- ... |
- web/ |
- <em>app</em>.dart |
- *.html |
- *.css |
- *.png |
- ... |
-</pre> |
- |
-<p>After transformation, <code>pub build</code> places generated assets under a directory |
-named <code>build</code>, which we’ll call the <em>build root</em>. The build root has two |
-special subdirectories: <code>packages</code> and <code>assets</code>. The dev server simulates this |
-hierarchy without generating files.</p> |
- |
-<p>The following figure shows the source assets above, plus the generated assets |
-produced by <code>pub build</code> if the only transformer is dart2js. In this example, |
-all the source files have corresponding generated files, and all the Dart |
-files have been compiled into a single JavaScript file.</p> |
- |
-<p><img src="/img/input-and-output-assets.png" alt="under the build directory are assets/ and packages/ directories, plus a bunch of files derived from the web/ directory: app.dart.js, *.html, *.css, *.png, ..." /></p> |
- |
-<h2 id="how-to-refer-to-assets">How to refer to assets</h2> |
- |
-<p>Here’s how source asset locations correlate to generated asset locations, |
-for untransformed files:</p> |
- |
-<table> |
- <tr> |
- <th> Source asset location </th> |
- <th> Generated asset location<br />(under the build root) </th> |
- </tr> |
- <tr> |
- <td> <code>.../<em><your_pkg></em>/web/<em><path></em></code> </td> |
- <td> <code>/<em><path></em></code> </td> |
- </tr> |
- <tr> |
- <td> <code>.../<em><pkg_name></em>/asset/<em><path></em></code> </td> |
- <td> <code>/assets/<em><pkg_name></em>/<em><path></em></code> </td> |
- </tr> |
- <tr> |
- <td> <code>.../<em><pkg_name></em>/lib/<em><path></em></code> </td> |
- <td> <code>/packages/<em><pkg_name></em>/<em><path></em></code> </td> |
- </tr> |
-</table> |
- |
-<p>For example, consider a helloworld app’s HTML file, which is in the |
-helloworld directory at <code>web/helloworld.html</code>. Running <code>pub build</code> produces a |
-copy at <code>build/helloworld.html</code>. In the dev server, you can get the HTML file |
-contents by using the URL <code>http://localhost:8080/helloworld.html</code>.</p> |
- |
-<p>Transformers might change any part of <em><path></em>, especially the |
-filename, but they can’t change the directory structure above |
-<em><path></em>.</p> |
- |