| 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>
|
| -
|
|
|