Update tutorial for 0.3.5 + bugfixes and other improvements.

hansiemithun · Aug 22, 2014 · 200381a · 200381a
1 parent 5118b95
commit 200381a
Show file tree

Hide file tree

Showing 5 changed files with 88 additions and 50 deletions.
diff --git a/docs/start/tutorial/intro.md b/docs/start/tutorial/intro.md
@@ -59,7 +59,7 @@ To get started, download the starter project. This starter project includes all
 
 Unzip the starter project somewhere on your local drive. 
 
-The starter includes an initial version of the project you'll be working with. If you run into trouble, it also includes incremental versions of the project so you can check your work along the way. 
+The starter includes an initial version of the project you'll be working with. It also includes incremental versions of the project so you can check your work along the way. 
 
 While you're working, you'll need a basic HTTP server to serve your pages. If you have Python installed, you can run one of the following commands in the top level of the starter project.
 
@@ -82,9 +82,10 @@ If you're using a different port, substitute the port you're using.
 If the images don't render, try a different web server.
 {: .alert .alert-info }
 
-### Next step
 
+<div horizontal layout end-justified class="stepnav">
 <a href="/docs/start/tutorial/step-1.html">
   <paper-button icon="arrow-forward" label="Step 1: Creating the app structure" raisedButton></paper-button>
 </a>
+</div>
 
diff --git a/docs/start/tutorial/step-1.md b/docs/start/tutorial/step-1.md
@@ -33,9 +33,12 @@ Go to the `starter` directory and open the `index.html` file in your favorite ed
 &lt;html>
 
 &lt;head>
+
   &lt;title>unquote&lt;/title>
+
   &lt;meta name="viewport" 
     content="width=device-width, minimum-scale=1.0, initial-scale=1.0, user-scalable=yes">
+
   &lt;script src="../components/platform/platform.js">
   &lt;/script>
 
@@ -52,23 +55,30 @@ Go to the `starter` directory and open the `index.html` file in your favorite ed
 </aside>
 </side-by-side>
 
+**Note:** The `font-roboto` import loads the `RobotoDraft` font using the 
+[Google Fonts API](https://developers.google.com/fonts/). If you're working
+offline or cannot access the Google Fonts API for any reason, this can block
+rendering of the web page. If you experience this problem, comment out the 
+import for `font-roboto`. 
+{: .alert .alert-info }
+
+
 Skipping over the styles for now, at the end of the file you'll find something new:
 
 <side-by-side>
 <pre>
-  ...
-&lt;body unresolved touch-action="auto">
+...
+&lt;body unresolved>
 
 &lt;/body>
-  ...
+...
 </pre>
 <aside>
   <h4>Key information</h4>
   <ul>
     <li>The <code>unresolved</code> attribute on the <code>&lt;body></code> element is used to prevent a flash of unstyled content 
         (FOUC) on browsers that lack native support for custom elements. For details, see the 
         <a href="/docs/polymer/styling.html#fouc-prevention">Polymer styling reference</a>.</li>
-    <li>The <code>touch-action="auto"</code> attribute is there to ensure touch events are handled properly on some browsers.</li>
   </ul>
 </aside>
 </side-by-side>
@@ -85,7 +95,6 @@ Add HTML import links to import the `<core-header-panel>`, `<core-toolbar>`, and
   src="../components/platform/platform.js"></script>
 &lt;link rel="import" 
   href="../components/font-roboto/roboto.html">
-
 <strong class="highlight nocode">&lt;link rel="import"
   href="../components/core-header-panel/core-header-panel.html">
 &lt;link rel="import"
@@ -118,7 +127,7 @@ To add a toolbar, add the following code inside the `<body>` tag.
 <side-by-side>
 <pre>
 <strong class="highlight nocode">&lt;core-header-panel>
-    
+
   &lt;core-toolbar>
   &lt;/core-toolbar>
 
@@ -160,8 +169,8 @@ tabs.
 &lt;core-toolbar>
 
   <strong class="highlight nocode">&lt;paper-tabs id="tabs" selected="all" self-end>
-    &lt;paper-tab name="all">ALL&lt;/paper-tab>
-    &lt;paper-tab name="favorites">FAVORITES&lt;/paper-tab>
+    &lt;paper-tab name="all">All&lt;/paper-tab>
+    &lt;paper-tab name="favorites">Favorites&lt;/paper-tab>
   &lt;/paper-tabs></strong>
 
 &lt;/core-toolbar>
@@ -196,7 +205,14 @@ tabs.
 Add styles for the new elements. Add the following CSS rules inside the `<style>` element.
 
 <side-by-side>
-<pre><strong class="highlight nocode">
+<pre>
+html,body {
+  height: 100%;
+  margin: 0;
+  background-color: #E5E5E5;
+  font-family: 'RobotoDraft', sans-serif;
+}
+<strong class="highlight nocode">
 core-header-panel {
   height: 100%;
   overflow: auto;
@@ -213,16 +229,21 @@ core-toolbar {
   -moz-user-select: none;
   -ms-user-select: none;
   user-select: none;
+  text-transform: uppercase;
 }</strong>
 </pre>
 <aside>
   <h4>Key information</h4>
   <ul>
     <li>The <code>&lt;core-header-panel&gt;</code> is a generic element that can be used as either a 
         full-page layout or for a card with a toolbar. To use it as a full-page, scrollable container,
-        set its height explicitly. The <code>overflow</code> and <code>-webkit-overflow-scrolling</code> properties ensure that
+        set its height explicitly. </li>
+    <li>Here, the height is set to 100%. This works because the existing style rules ensure that its 
+        parent elements,
+        <code>&lt;html&gt;</code> and <code>&lt;body&gt;</code>, take up 100% of the viewport height.</li>
+    <li>The <code>overflow</code> and <code>-webkit-overflow-scrolling</code> properties ensure that
         scrolling works smoothly on touch devices, especially iOS.</li>
-    <li>The toolbar adds a default margin on its children, to space controls appropriately. The tabs don't need this extra spacing.</li>
+    <li>The <code>#tabs</code> selector selects the `&lt;paper-tabs&gt;` element. The toolbar adds a default margin on its children, to space controls appropriately. The tabs don't need this extra spacing.</li>
     <li>The <code>user-select</code> properties prevent the user from accidentally selecting the tab text.</li>
   </ul>
 </aside>
@@ -232,7 +253,7 @@ core-toolbar {
   <core-icon icon="polymer"></core-icon>
 </div> 
 
-Add a `<script>` tag at the end of the file to handle the tab switching
+Add a `<script>` tag near the end of the file to handle the tab switching
     event.
 
 
@@ -282,12 +303,14 @@ If something isn't working, check your work against the `index.html` file in the
 
 In this step, you used HTML imports to import custom elements, and used them to create a simple app layout.
 
-**Explore:** Can you use other children inside the `<paper-tabs>`? Try an image or a text span
+**Explore:** Can you use other children inside the `<paper-tabs>`? Try an image or a text span.
 {: .alert .alert-info }
 
-### Next step
-
+<div layout horizontal justified class="stepnav">
+<a href="/docs/start/tutorial/intro.html">
+  <paper-button icon="arrow-back" label="Getting Started"></paper-button>
+</a>
 <a href="/docs/start/tutorial/step-2.html">
-  <paper-button icon="arrow-forward" label="Step 2: Your own element" raisedButton></paper-button>
+  <paper-button icon="arrow-forward" label="Step 2: Creating your own element" raisedButton></paper-button>
 </a>
-
+</div>
diff --git a/docs/start/tutorial/step-2.md b/docs/start/tutorial/step-2.md
@@ -3,7 +3,7 @@ layout: default
 type: start
 navgroup: docs
 shortname: Start
-title: "Step 2: Your own element"
+title: "Step 2: Creating your own element"
 subtitle: Your first Polymer application 
 ---
 
@@ -36,7 +36,7 @@ In this step, you'll learn about:
 -   Working with shadow DOM.
 
 <aside class="alert alert-info">
-<p><b>Learn More:</b>Shadow DOM provides you a way to add a local DOM tree
+<p><b>Learn more:</b>Shadow DOM provides you a way to add a local DOM tree
 inside a DOM element, with local styles and markup that are decoupled from the rest of the web page.</p>
 <p>To learn more about shadow DOM, see the <a href="/platform/shadow-dom.html">
 Shadow DOM polyfill docs</a>.</p>
@@ -155,12 +155,13 @@ the shadow DOM tree.</p>
 
 Create the card structure.
 
-Find the `CARD CONTENTS GO HERE` comment and add the `<div>` and
+Find the `CARD CONTENTS GO HERE` comment and replace it with the `<div>` and
 `<content>` tags shown below.
 
 <side-by-side>
 <pre>
-&lt;!-- CARD CONTENTS GO HERE -->
+&lt;/style>
+
 <strong class="highlight nocode">&lt;div class="card-header" layout horizontal center>
   &lt;content select="img">&lt;/content>
   &lt;content select="h2">&lt;/content>
@@ -185,7 +186,7 @@ Find the `CARD CONTENTS GO HERE` comment and add the `<div>` and
   </aside>
 </side-by-side>
 
-**Selecting content**. The `select` attribute on a `content` element accepts a [limited set of 
+**Selecting content**: The `select` attribute on a `content` element accepts a [limited set of 
 CSS selectors](http://w3c.github.io/webcomponents/spec/shadow/#satisfying-matching-criteria). 
 You can only select direct children of the host node, not descendents. 
 {: .alert .alert-info }
@@ -201,10 +202,12 @@ file already includes a `:host` selector, discussed earlier, to style the
 top-level `<post-card>` element. 
 
 To style the children added using the `<content>` element, add the 
-following CSS inside the `<style>` tag:
+following CSS inside the `<style>` tag after the existing rules:
 
 <side-by-side>
-<pre><strong class="highlight nocode">
+<pre>.card-header {
+  margin-bottom: 10px;
+}<strong class="highlight nocode">
 polyfill-next-selector { content: '.card-header h2'; }
 .card-header ::content h2 {
   margin: 0;
@@ -217,6 +220,7 @@ polyfill-next-selector { content: '.card-header img'; }
   border-radius: 50%;
   margin: 10px;
 }</strong>
+&lt;/style>
 </pre>
   <aside>
     <h4>Key information</h4>
@@ -272,15 +276,16 @@ Add a `<post-card>` element to `index.html` directly after the
 <side-by-side>
 <pre>
 ...   
-&lt;/core-toolbar>
-  <strong class="highlight nocode">&lt;div class="container" layout vertical center>
-    &lt;post-card>
-      &lt;img width="70" height="70" 
-        src="../images/avatar-07.svg">
-      &lt;h2>Another Developer&lt;/h2>
-      &lt;p>I'm composing with shadow DOM!&lt;/p>
-    &lt;/post-card>
-  &lt;/div></strong>
+<strong class="highlight nocode">&lt;div class="container" layout vertical center>
+
+  &lt;post-card>
+    &lt;img width="70" height="70" 
+      src="../images/avatar-07.svg">
+    &lt;h2>Another Developer&lt;/h2>
+    &lt;p>I'm composing with shadow DOM!&lt;/p>
+  &lt;/post-card>
+
+&lt;/div></strong>
 ...
 </pre>
   <aside>
@@ -314,9 +319,12 @@ they work. Does anything change if you reorder the `<post-card>`'s children in
 also try swapping the two `select=` attributes in `post-card.html`.
 {: .alert .alert-info }
 
-### Next step
 
+<div layout horizontal justified class="stepnav">
+<a href="/docs/start/tutorial/step-1.html">
+  <paper-button icon="arrow-back" label="Step 1: Creating the app structure"></paper-button>
+</a>
 <a href="/docs/start/tutorial/step-3.html">
   <paper-button icon="arrow-forward" label="Step 3: Using data binding" raisedButton></paper-button>
 </a>
-
+</div>
diff --git a/docs/start/tutorial/step-3.md b/docs/start/tutorial/step-3.md
@@ -31,8 +31,8 @@ To get the data, you'll use the `<post-service>` element provided as part of the
 
 In this section you'll learn about:
 
--   Data binding.
--   Published properties.
+-   Using data binding.
+-   Publishing properties.
 
 ### Edit post-list.html
 
@@ -96,7 +96,7 @@ Add a `<post-service>` element inside the element's `<template>`:
     <ul>
       <li>
         The <code>posts="{%raw%}{{posts}}{%endraw%}"</code> attribute adds a two-way data binding between 
-        the <code>&lt;post-service&gt;</code> element and your custom element.
+        the <code>&lt;post-service&gt;</code> element and the <code>&lt;post-list&gt;</code> element.
       </li>
     </ul>
   </aside>
@@ -119,14 +119,17 @@ Add the following `<div>` and `<template>` tag:
 ...
 &lt;post-service id="service" posts="{{posts}}">
 &lt;/post-service>
+
 <strong class="highlight nocode">&lt;div layout vertical center>
+
   &lt;template repeat="{{post in posts}}">
     &lt;post-card>
       &lt;img src="{{post.avatar}}" width="70" height="70">
       &lt;h2>{{post.username}}&lt;/h2>
       &lt;p>{{post.text}}&lt;/p>
     &lt;/post-card>
   &lt;/template>
+
 &lt;/div></strong>
 ...
 </pre>
@@ -194,9 +197,11 @@ If you have any problems, check your work against the files in the `step-3` fold
 <a href="/docs/elements/core-elements.html#core-ajax">&lt;core-ajax&gt;</a></code> element to make HTTP requests.
 {: .alert .alert-info}
 
-### Next step
-
+<div layout horizontal justified class="stepnav">
+<a href="/docs/start/tutorial/step-2.html">
+  <paper-button icon="arrow-back" label="Step 2: Creating your own element"></paper-button>
+</a>
 <a href="/docs/start/tutorial/step-4.html">
   <paper-button icon="arrow-forward" label="Step 4: Finishing touches" raisedButton></paper-button>
 </a>
-
+</div>
diff --git a/docs/start/tutorial/step-4.md b/docs/start/tutorial/step-4.md
@@ -79,8 +79,7 @@ prototype.
 
 <side-by-side>
 <pre>
-&lt;script>
-<strong class="highlight nocode">   
+&lt;script><strong class="highlight nocode">   
 Polymer({
   publish: {
     favorite: {
@@ -224,15 +223,13 @@ Add an event handler for the `favorite-tap` event to `post-list.html`:
 <side-by-side>
 <pre>
 &lt;script>
-<strong class="highlight nocode">
-Polymer({
+<strong class="highlight nocode">Polymer({
   handleFavorite: function(event, detail, sender) {
     var post = sender.templateInstance.model.post;
     this.$.service.setFavorite(post.uid, post.favorite);
   }
 });
-</strong>
-&lt;/script>
+</strong>&lt;/script>
 </pre>
   <aside>
     <h4>Key information</h4>
@@ -277,8 +274,12 @@ If your project doesn't look quite right, check your work against the files in t
 
 Ready to start a project of your own? Install some {{site.project_title}} components and get to work!
 
+<div layout horizontal justified class="stepnav">
+<a href="/docs/start/tutorial/step-3.html">
+  <paper-button icon="arrow-back" label="Step 3: Using data binding"></paper-button>
+</a>
 <a href="/docs/start/getting-the-code.html#installing-components">
   <paper-button icon="arrow-forward" label="Installing components" raisedButton></paper-button>
 </a>
-
+</div>