Skip to content
This repository has been archived by the owner on May 29, 2019. It is now read-only.

Commit

Permalink
Trying to resolve merge conflicts
Browse files Browse the repository at this point in the history
  • Loading branch information
Kate Jeffreys committed Sep 28, 2016
1 parent 32b1a8f commit 19c2122
Show file tree
Hide file tree
Showing 4 changed files with 241 additions and 261 deletions.
90 changes: 39 additions & 51 deletions app/1.0/start/toolbox/add-elements.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Step 3. Add some elements
title: Step 3. Add an element
subtitle: "Build an app with App Toolbox"
---

Expand All @@ -8,79 +8,67 @@ subtitle: "Build an app with App Toolbox"
Now that you've added a new view to your application, you can start building
out the details of that view.

In the process, you'll likely want to turn
to some off-the-shelf components, for example from the
[Polymer Element Catalog][catalog] or community catalogs like
[customelements.io][ceio].
One of the appeals of the web component approach to web development
is the ecosystem. Rather than building everything in your app from scratch,
you can find and use off-the-shelf elements that suit your needs. Two examples
of places you can find reusable components are the
[Polymer Element Catalog][catalog] (elements built by the Polymer team) and
[customelements.io][ceio] (elements built by the web components community).

## Ensure bower is installed
In this tutorial you install a third-party component and use it in the new
page that you created in the last step. The element that you're going to
install is called `paper-slider`. It's a simple UI subcomponent that lets you
drag a slider bar.

[Bower][bower] is a front-end package manager which is the most common
tool used for fetching and managing web components.
## Install a third-party component

Ensure it is installed by running the following command:
Usually, when working with third-party components, you'd need to browse the
catalogs and find one that suits your needs, and then get the command for
installing the element from the element's page on the catalog. For example,
you can see the command for installing `paper-slider ` on the left-hand side
of its [documentation page][paper-slider]. This tutorial is just going to
give you the command directly.

npm install -g bower
1. Run this command from your project root directory to install your new
element.

## Install a 3rd-party component
bower install --save PolymerElements/paper-slider

Once you've identified a component you'd like to install, you'll want to find
the bower package name for the component.
The `--save` flag instructs Bower to update `bower.json` to include this
element as a dependency of the app.
{.alert .alert-info}

In this step, you'll add Polymer's `<paper-slider>` element to your app, which is listed in the
[Polymer Element Catalog here][paper-slider]. You'll find its bower install
command on the left hand side of that screen.
## Add the element to your page

Run this command from your project root directory:
The third-party element is installed now, but you're not using it yet.

bower install --save PolymerElements/paper-slider

## Add the element to your application

1. Open `src/my-new-view.html` in a text editor.

1. Import `paper-slider.html` as a dependency

Add this import beneath the existing import for `polymer.html`:
1. Inside of `src/my-new-view.html`, import `paper-slider.html` below
the existing import for `polymer.html`.

```
<link rel="import" href="../bower_components/polymer/polymer.html">
<link rel="import" href="../bower_components/paper-slider/paper-slider.html">
```
1. Add the `<paper-slider>` element to the template for the element.
1. Declare your new element at the bottom of the template for `my-new-view`.
```
<h1>New view</h1>
<paper-slider min="-100" max="100" value="50"></paper-slider>
```
You can add it under the `<h1>` you added in the previous step. Your new
template should look like this:
All set! If you open up your new page now, you can play with your slider.
```
<!-- Defines the element's style and local DOM -->
<template>
<style>
:host {
display: block;
padding: 16px;
}
</style>
<h1>New view</h1>
<paper-slider min="-100" max="100" value="50"></paper-slider>
</template>
```
You should be able to see the `paper-slider` working in your new view now:
[http://localhost:8080/new-view](http://localhost:8080/new-view).
![Example of page with slider](/images/1.0/toolbox/starter-kit-slider.png)
![Example of page with slider](/images/1.0/toolbox/app-drawer-template-slider.png)
## Next steps
Now that you've added a 3rd-party component to your page, learn how to
[deploy the app to the web](deploy).
You've initialized an app from a template, created a page from scratch, and
used a third-party element in your app. For the last step in this tutorial,
learn how to deploy your app to the web.
<a class="blue-button"
href="deploy">Next step: Deploy</a>
[bower]: http://bower.io/
[catalog]: https://elements.polymer-project.org/
Expand Down
180 changes: 68 additions & 112 deletions app/1.0/start/toolbox/create-a-page.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,18 @@ subtitle: "Build an app with App Toolbox"

<!-- toc -->

The `starter-kit` includes 3 placeholder pages you can use to start building out
the views of your application. But at some point, you'll probably want to add more.

This step takes you through the process of adding a new page or top-level view
to your application.
This tutorial teaches you how to add a new page (i.e. top-level view) to
your app.

## Create an element for the new page

First, create a new custom element that encapsulates the contents of
your new view.
The new page you're about to create will itself be a Polymer element. All of
the content, style, and behavior of the page will be encapsulated inside of
the element.

1. Create a new file called `src/my-new-view.html` and open it in an editor.

2. Add some scaffolding for a new custom element definition using Polymer:
2. Add the following code to `my-new-view.html`.

```
<link rel="import" href="../bower_components/polymer/polymer.html">
Expand All @@ -29,125 +27,85 @@ your new view.
<style>
:host {
display: block;
padding: 16px;
}
</style>
<h1>New view</h1>
</template>
<!-- Creates the element's prototype and registers it -->
<script>
Polymer({
is: 'my-new-view'
is: 'my-new-view',
properties: {
route: Object
}
});
</script>
</dom-module>
```
For now your element is very basic, and just has a `<h1>` that says "New View",
but we can return to it and make it more interesting later.
## Add the page element to your app
## Add the element to your app
Your element is defined, but your app isn't actually using it yet. To use it,
you need to declare it in your app's HTML.
1. Open `src/my-app.html` in a text editor.
1. Find the set of existing pages inside the `<iron-pages>`:
```
<iron-pages
selected="[[page]]"
attr-for-selected="name"
fallback-selection="view404"
role="main">
<my-view1 name="view1"></my-view1>
<my-view2 name="view2"></my-view2>
<my-view3 name="view3"></my-view3>
<my-view404 name="view404"></my-view404>
</iron-pages>
```
The `<iron-pages>` is bound to the `page` variable that changes with the
route, and selects the active page while hiding the others.
1. Find the `iron-pages` element and declare your new page at the bottom.
1. Add your new page inside the iron-pages:
```
<my-new-view name="new-view"></my-new-view>
<iron-pages role="main" selected="[[page]]" attr-for-selected="name">
<my-view1 name="view1"></my-view1>
<my-view2 name="view2"></my-view2>
<my-view3 name="view3"></my-view3>
<my-new-view name="new-view"></my-new-view>
</iron-pages>
```
Your `<iron-pages>` should now look like this:
The `iron-pages` element is a reusable component that will not be
perceivable to viewers of your live page.
It just handles the logic for deciding which page to
display. The `selected` attribute of `iron-pages` determines which
page is displayed. The value of `selected` may look strange to you.
That's Polymer's data-binding syntax. The `selected` property is hooked
up a variable named `page`. Whenever the value of `page` changes,
`iron-pages` automatically displays the new page.
{.alert .alert-info}
```
<iron-pages
selected="[[page]]"
attr-for-selected="name"
fallback-selection="view404"
role="main">
<my-view1 name="view1"></my-view1>
<my-view2 name="view2"></my-view2>
<my-view3 name="view3"></my-view3>
<my-new-view name="new-view"></my-new-view>
<my-view404 name="view404"></my-view404>
</iron-pages>
```
### Aside: Where's the HTML import?
Note: Normally when adding a new custom element for the first time, you'd
want to add an HTML Import to ensure the component definition has been
loaded. However, this app template is already set up to lazy-load top
level views on-demand based on the route, so in this case you don't need
to add an import for your new `<my-new-view>` element.
Normally when adding a new custom element for the first time, you'd
want to add an HTML Import to ensure the component definition has been
loaded. However, this app template is already set up to lazy-load top
level views on-demand based on the route, so in this case you don't need
to add an import for your new `<my-new-view>` element.
The following code that came with the app template will ensure the
definition for each page has been loaded when the route changes. As
you can see, we followed a simple convention (`'my-' + page + '.html'`)
importing the definition for each route, and you can adapt this code as you
like to handle more complex routing and lazy loading.
The following code from the app template handles the lazy loading.
It follows a simple convention for importing each route
(`'my-' + page + '.html'`). You can adadpt this code as you like to handle
more complex routing and lazy loading.
Existing template code—you do not need to add this { .caption }
Existing template code (You do not need to add this) { .caption }
```
_pageChanged: function(page) {
// Load page import on demand. Show 404 page if fails
var resolvedPageUrl = this.resolveUrl('my-' + page + '.html');
this.importHref(resolvedPageUrl, null, this._showPage404, true);
},
```
```
_pageChanged: function(page) {
// load page import on demand.
this.importHref(
this.resolveUrl('my-' + page + '.html'), null, null, true);
}
```
## Create a navigation menu item
Last, we'll add a menu item in the left-hand drawer to allow navigating to
your new page.
1. Keep `src/my-app.html` open in your editor.
1. Find the navigation menu inside the `<app-drawer>` element.
```
<!-- Drawer content -->
<app-drawer>
<app-toolbar>Menu</app-toolbar>
<iron-selector selected="[[page]]" attr-for-selected="name" class="drawer-list" role="navigation">
<a name="view1" href="/view1">View One</a>
<a name="view2" href="/view2">View Two</a>
<a name="view3" href="/view3">View Three</a>
</iron-selector>
</app-drawer>
```
Each navigation menu item consists of an anchor element (`<a>`) styled with CSS.
1. Add the following new navigation item to the bottom of the menu.
```
<a name="new-view" href="/new-view">New View</a>
```
You've defined your new element and declared it in your app. Now you
just need to add a menu item in the left-hand drawer so that users can
navigate to the new page.
Your menu should now look like the following:
1. Find the `<app-drawer>` element in `src/my-app.html` and add a menu
item for your new page at the bottom.
```
...
<!-- Drawer content -->
<app-drawer>
<app-toolbar>Menu</app-toolbar>
Expand All @@ -158,42 +116,40 @@ your new page.
<a name="new-view" href="/new-view">New View</a>
</iron-selector>
</app-drawer>
...
```
Your new page is now ready! Open your web browser and view it at
[http://localhost:8080/new-view](http://localhost:8080/new-view).
Your new page is now ready!
![Example of new page](/images/1.0/toolbox/starter-kit-newview.png)
![Example of new page](/images/1.0/toolbox/app-drawer-template-newview.png)
## Register the page for the build
When you deploy your application to the web, you'll use the Polymer CLI
to prepare your files for deployment. Polymer CLI will need to know about any
When you deploy your application to the web, you'll use Polymer CLI
to prepare your files for deployment. Polymer CLI needs to know about any
demand-loaded fragments like the lazy-loaded view you just added.
1. Open `polymer.json` in a text editor.
1. Open `polymer.json` in an editor.
1. Add `src/my-new-view.html` to the list of `fragments`.
The new list should look like this:
1. Add `src/my-new-view.html` to the bottom of the `fragments` list.
```
"fragments": [
"src/my-view1.html",
"src/my-view2.html",
"src/my-view3.html",
"src/my-new-view.html",
"src/my-view404.html"
"src/my-new-view.html"
]
```
Note: You only need to add files you will lazy load or import using the `async`
attribute to the `fragments` list. Any files that are imported using synchronous
`<link rel="import">` tags should *not* be added to `fragments`.
You only need to add files to the `fragments` list if you lazy-load them
or import them using the `async` attribute. Any files that are imported
synchronously (e.g. `<link rel="import" ...>` should **not** be added to
`fragments`.
## Next steps
Now that you've added a new page to your application, learn how to [add 3rd-party
elements to your application](add-elements), or how to
[deploy the app to the web](deploy).
You've added a new page to your application. Next, learn how to install and
add a third-party reusable component to your app.
<a class="blue-button"
href="add-elements">Next step: Add an element</a>
Loading

0 comments on commit 19c2122

Please sign in to comment.