| OLD | NEW |
|---|
| 1 <!doctype html> | 1 <!doctype html> |
| 2 <!-- | 2 <!-- |
| 3 This file is autogenerated with polymer/tool/create_message_details_page.dart | 3 This file is autogenerated with polymer/tool/create_message_details_page.dart |
| 4 --> | 4 --> |
| 5 <html> | 5 <html> |
| 6 <style> | 6 <style> |
| 7 @font-face { | 7 @font-face { |
| 8 font-family: 'Montserrat'; | 8 font-family: 'Montserrat'; |
| 9 font-style: normal; | 9 font-style: normal; |
| 10 font-weight: 400; | 10 font-weight: 400; |
| (...skipping 105 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 116 <h2>Messages from package <code>code_transformers</code></h2> | 116 <h2>Messages from package <code>code_transformers</code></h2> |
| 117 <hr /> | 117 <hr /> |
| 118 | 118 |
| 119 <div id="code_transformers_1"><h3>Absolute paths not allowed <a href="#code_tran
sformers_1">#1</a></h3> | 119 <div id="code_transformers_1"><h3>Absolute paths not allowed <a href="#code_tran
sformers_1">#1</a></h3> |
| 120 <p>The transformers processing your code were trying to resolve a URL and identi
fy | 120 <p>The transformers processing your code were trying to resolve a URL and identi
fy |
| 121 a file that they correspond to. Currently only relative paths can be resolved.</
p> | 121 a file that they correspond to. Currently only relative paths can be resolved.</
p> |
| 122 </div><hr /> | 122 </div><hr /> |
| 123 | 123 |
| 124 <div id="code_transformers_2"><h3>Invalid URL to reach another package <a href="
#code_transformers_2">#2</a></h3> | 124 <div id="code_transformers_2"><h3>Invalid URL to reach another package <a href="
#code_transformers_2">#2</a></h3> |
| 125 <p>To reach an asset that belongs to another package, use <code>package:</code>
URLs in | 125 <p>To reach an asset that belongs to another package, use <code>package:</code>
URLs in |
| 126 Dart code, but in any other language (like HTML or CSS) use relative URLs.</p> | 126 Dart code, but in any other language (like HTML or CSS) use relative URLs that |
| 127 <p>These are the rules you must follow to write URLs that refer to files in othe
r | 127 first go all the way to the <code>packages/</code> directory.</p> |
| 128 packages:</p><ul><li> | 128 <p>The rules for correctly writing these imports are subtle and have a lot of |
| 129 <p>If the file containing the relative URL is an entrypoint under <code>web</cod
e>, use | 129 special cases. Please review |
| 130 <code>packages/package_name/path_to_file</code></p></li><li> | 130 <a href="https://www.dartlang.org/polymer/app-directories.html">https://www.dart
lang.org/polymer/app-directories.html</a> to learn |
| 131 <p>If the file containing the URL is under <code>web</code>, but in a different
directory | 131 more.</p> |
| 132 than your entrypoint, walk out to the same level as the entrypoint first, | |
| 133 then enter the <code>packages</code> directory.</p> | |
| 134 <p><strong>Note</strong>: If two entrypoints include the file under <code>web</c
ode> containing the | |
| 135 URL, either both entrypoints have to live in the same directory, or you need | |
| 136 to move the file to the <code>lib</code> directory.</p></li><li> | |
| 137 <p>If the file containing the URL lives under <code>lib</code>, walk up as many
levels as | |
| 138 directories you have + 1. This is because code in <code>lib/a/b</code> is loaded
from | |
| 139 <code>packages/package_name/a/b</code>.</p></li></ul> | |
| 140 <p>The rules are easier to follow if you know how the code is laid out for | |
| 141 Dartium before you build, and how it is laid out after you build it with <code>p
ub | |
| 142 build</code>. Consider the following example:</p> | |
| 143 <p> package a</p> | |
| 144 <pre><code> lib/ | |
| 145 |- a1.html | |
| 146 | |
| 147 web/ | |
| 148 |- a2.html | |
| 149 </code></pre> | |
| 150 <p> package b</p> | |
| 151 <pre><code> lib/ | |
| 152 |- b1.html | |
| 153 |- b2/ | |
| 154 |- b3.html | |
| 155 </code></pre> | |
| 156 <p> package c</p> | |
| 157 <pre><code> lib/ | |
| 158 |- c3.html | |
| 159 | |
| 160 web/ | |
| 161 |- index.html | |
| 162 |- index.dart | |
| 163 |- c1/ | |
| 164 |- c2.html | |
| 165 </code></pre> | |
| 166 <p>If your app is package <code>c</code>, then <code>pub get</code> generates a
packages directory under | |
| 167 the web directory, like this:</p> | |
| 168 <pre><code> web/ | |
| 169 |- index.html | |
| 170 |- index.dart | |
| 171 |- c1/ | |
| 172 | |- c2.html | |
| 173 |- packages/ | |
| 174 |- a/ | |
| 175 | |- a1.html | |
| 176 |- b/ | |
| 177 | |- b1.html | |
| 178 | |- b2/ | |
| 179 | |- b3.html | |
| 180 |- c/ | |
| 181 |- c3.html | |
| 182 </code></pre> | |
| 183 <p>Note that no <code>lib</code> directory is under the <code>packages</code> di
rectory. | |
| 184 When you launch <code>web/index.html</code> in Dartium, Dartium loads <code>pack
age:</code> imports from | |
| 185 <code>web/packages/</code>.</p> | |
| 186 <p>If you need to refer to any file in other packages from <code>index.html</cod
e>, you can | |
| 187 simply do <code>packages/package_name/path_to_file</code>. For example | |
| 188 <code>packages/b/b2/b3.html</code>. From <code>index.html</code> you can also re
fer to files under the | |
| 189 web directory of the same package using a simple relative URL, like | |
| 190 <code>c1/c2.html</code>.</p> | |
| 191 <p>However, if you want to load <code>a1.html</code> from <code>c2.html</code>,
you need to reach out to | |
| 192 the packages directory that lives next to your entrypoint and then load the file | |
| 193 from there, for example <code>../packages/a/a1.html</code>. Because pub generate
s symlinks | |
| 194 to the packages directory also under c1, you may be tempted to write | |
| 195 <code>packages/a/a1.html</code>, but that is incorrect - it would yield a canoni
calization | |
| 196 error (see more below).</p> | |
| 197 <p>If you want to load a file from the lib directory of your own package, you | |
| 198 should also use a package URL. For example, <code>packages/c/c3.html</code> and
not | |
| 199 <code>../lib/c3.html</code>. This will allow you to write code in <code>lib</cod
e> in a way that it | |
| 200 can be used within and outside your package without making any changes to it.</p
> | |
| 201 <p>Because any time you reach inside a <code>lib/</code> directory you do so usi
ng a | |
| 202 <code>packages/</code> URL, the rules for reaching into other files in other pac
kages are | |
| 203 always consistent: go up to exit the <code>packages</code> directory and go back
inside to | |
| 204 the file you are looking for. For example, to reach <code>a1.html</code> from <
code>b3.html</code> | |
| 205 you need to write <code>../../../packages/a/a1.html</code>.</p> | |
| 206 <p>The motivation behind all these rules is that URLs need to work under many | |
| 207 scenarios at once:</p><ul><li> | |
| 208 <p>They need to work in Dartium without any code transformation: resolving the | |
| 209 path in the context of a simple HTTP server, or using <code>file:///</code> URLs
, | |
| 210 should yield a valid path to assets. The <code>packages</code> directory is safe
to use | |
| 211 because pub already creates it next to entrypoints of your application.</p></li>
<li> | |
| 212 <p>They need to be canonical. To take advantage of caching, multiple URLs | |
| 213 reaching the same asset should resolve to the same absolute URL.</p> | |
| 214 <p>Also, in projects that use HTML imports (like polymer) tools support that | |
| 215 you reach a library with either Dart imports or HTML imports, and correctly | |
| 216 resolve them to be the same library. The rules are designed to allow tools | |
| 217 to support this.</p> | |
| 218 <p>For example, consider you have an import might like:</p> | |
| 219 <pre><code><link rel=import href=packages/a/a.html> | |
| 220 </code></pre> | |
| 221 <p>where a.html has <code><script type="application/dart" src="a.dart"></c
ode>. If your | |
| 222 Dart entrypoint also loads <code>"package:a/a.dart"</code>, then a tool need to
make | |
| 223 sure that both versions of <code>a.dart</code> are loaded from the same URL. Oth
erwise, | |
| 224 you may see errors at runtime like: <code>A is not a subtype of A</code>, which
can be | |
| 225 extremely confusing.</p> | |
| 226 <p>When you follow the rules above, our tools can detect the pattern in the | |
| 227 HTML-import URL containing <code>packages/</code> and canonicalize the import | |
| 228 by converting <code>packages/a/a.dart</code> into <code>package:a/a.dart</code>
under the hood.</p></li><li> | |
| 229 <p>They need to continue to be valid after applications are built. | |
| 230 Technically this could be done automatically with pub transformers, but to | |
| 231 make sure that code works also in Dartium with a simple HTTP Server, | |
| 232 existing transformers do not fix URLs, they just detect inconsistencies and | |
| 233 produce an error message like this one, instead.</p></li></ul> | |
| 234 </div><hr /> | 132 </div><hr /> |
| 235 | 133 |
| 236 <div id="code_transformers_3"><h3>Incomplete URL to asset in another package <a
href="#code_transformers_3">#3</a></h3> | 134 <div id="code_transformers_3"><h3>Incomplete URL to asset in another package <a
href="#code_transformers_3">#3</a></h3> |
| 237 <p>URLs that refer to assets in other packages need to explicitly mention the | 135 <p>URLs that refer to assets in other packages need to explicitly mention the |
| 238 <code>packages/</code> directory. In the future this requirement might be remove
d, but for | 136 <code>packages/</code> directory. In the future this requirement might be remove
d, but for |
| 239 now you must use a canonical URL form for it.</p> | 137 now you must use a canonical URL form for it.</p> |
| 240 <p>For example, if <code>packages/a/a.html</code> needs to import <code>packages
/b/b.html</code>, | 138 <p>For example, if <code>packages/a/a.html</code> needs to import <code>packages
/b/b.html</code>, |
| 241 you might expect a.html to import <code>../b/b.html</code>. Instead, it must imp
ort | 139 you might expect a.html to import <code>../b/b.html</code>. Instead, it must imp
ort |
| 242 <code>../../packages/b/b.html</code>. | 140 <code>../../packages/b/b.html</code>.</p> |
| 243 See <a href="http://dartbug.com/15797">issue 15797</a>.</p> | 141 <p>See <a href="http://dartbug.com/15797">issue 15797</a> and |
| 142 <a href="https://www.dartlang.org/polymer/app-directories.html">https://www.dart
lang.org/polymer/app-directories.html</a> to learn more.</p> |
| 244 </div><hr /><h2>Messages from package <code>observe</code></h2> | 143 </div><hr /><h2>Messages from package <code>observe</code></h2> |
| 245 <hr /> | 144 <hr /> |
| 246 | 145 |
| 247 <div id="observe_1"><h3><code>@observable</code> not supported on libraries <a h
ref="#observe_1">#1</a></h3> | 146 <div id="observe_1"><h3><code>@observable</code> not supported on libraries <a h
ref="#observe_1">#1</a></h3> |
| 248 <p>Only instance fields on <code>Observable</code> classes can be observable, | 147 <p>Only instance fields on <code>Observable</code> classes can be observable, |
| 249 and you must explicitly annotate each observable field as <code>@observable</cod
e>.</p> | 148 and you must explicitly annotate each observable field as <code>@observable</cod
e>.</p> |
| 250 <p>Support for using the <code>@observable</code> annotation in libraries, class
es, and | 149 <p>Support for using the <code>@observable</code> annotation in libraries, class
es, and |
| 251 elsewhere is deprecated.</p> | 150 elsewhere is deprecated.</p> |
| 252 </div><hr /> | 151 </div><hr /> |
| 253 | 152 |
| (...skipping 325 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 579 (<code>html5lib</code>). This message reports a | 478 (<code>html5lib</code>). This message reports a |
| 580 warning that the parser detected.</p> | 479 warning that the parser detected.</p> |
| 581 </div><hr /> | 480 </div><hr /> |
| 582 | 481 |
| 583 <div id="polymer_41"><h3>Possible flash of unstyled content <a href="#polymer_41
">#41</a></h3> | 482 <div id="polymer_41"><h3>Possible flash of unstyled content <a href="#polymer_41
">#41</a></h3> |
| 584 <p>Custom element found in document body without an "unresolved" attribute on it
or | 483 <p>Custom element found in document body without an "unresolved" attribute on it
or |
| 585 one of its parents. This means your app probably has a flash of unstyled content | 484 one of its parents. This means your app probably has a flash of unstyled content |
| 586 before it finishes loading. See <a href="http://goo.gl/iN03Pj">http://goo.gl/iN0
3Pj</a> for more info.</p> | 485 before it finishes loading. See <a href="http://goo.gl/iN03Pj">http://goo.gl/iN0
3Pj</a> for more info.</p> |
| 587 </div><hr /></body> | 486 </div><hr /></body> |
| 588 </html> | 487 </html> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 582673003:
Update messages in code transformers now that we have the article about imports. (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart