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

Commit

Permalink
Merge pull request #1774 from Polymer/revert-1767
Browse files Browse the repository at this point in the history 
Revert "Trying to resolve merge conflicts"
  • Loading branch information
Arthur Evans authored Oct 6, 2016
2 parents da82a48 + 13fdda5 commit d019ea2
Show file tree
Hide file tree
Showing 4 changed files with 261 additions and 241 deletions.
90 changes: 51 additions & 39 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 an element
title: Step 3. Add some elements
subtitle: "Build an app with App Toolbox"
---

Expand All @@ -8,67 +8,79 @@ 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.

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).
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].

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.
## Ensure bower is installed

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

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.
Ensure it is installed by running the following command:

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

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

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

## Add the element to your page
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.

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

1. Inside of `src/my-new-view.html`, import `paper-slider.html` below
the existing import for `polymer.html`.
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`:

```
<link rel="import" href="../bower_components/polymer/polymer.html">
<link rel="import" href="../bower_components/paper-slider/paper-slider.html">
```
1. Declare your new element at the bottom of the template for `my-new-view`.
1. Add the `<paper-slider>` element to the template for the element.
```
<h1>New view</h1>
<paper-slider min="-100" max="100" value="50"></paper-slider>
```
All set! If you open up your new page now, you can play with your slider.
You can add it under the `<h1>` you added in the previous step. Your new
template should look like this:
![Example of page with slider](/images/1.0/toolbox/app-drawer-template-slider.png)
```
<!-- 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>
```
## Next steps
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).
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.
![Example of page with slider](/images/1.0/toolbox/starter-kit-slider.png)
## Next steps
<a class="blue-button"
href="deploy">Next step: Deploy</a>
Now that you've added a 3rd-party component to your page, learn how to
[deploy the app to the web](deploy).
[bower]: http://bower.io/
[catalog]: https://elements.polymer-project.org/
Expand Down
180 changes: 112 additions & 68 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,18 +5,20 @@ subtitle: "Build an app with App Toolbox"

<!-- toc -->

This tutorial teaches you how to add a new page (i.e. top-level view) to
your app.
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.

## Create an element for the new page

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.
First, create a new custom element that encapsulates the contents of
your new view.

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

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

```
<link rel="import" href="../bower_components/polymer/polymer.html">
Expand All @@ -27,85 +29,125 @@ the element.
<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',
properties: {
route: Object
}
is: 'my-new-view'
});
</script>
</dom-module>
```
## Add the page element to your app
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.
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.
## Add the element to your app
1. Open `src/my-app.html` in a text editor.
1. Find the `iron-pages` element and declare your new page at the bottom.
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. Add your new page inside the iron-pages:
```
<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>
<my-new-view name="new-view"></my-new-view>
```
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}
Your `<iron-pages>` should now look like this:
### Aside: Where's the HTML import?
```
<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>
```
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.
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.
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.
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.
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.
this.importHref(
this.resolveUrl('my-' + page + '.html'), null, null, true);
}
```
```
_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);
},
```
## Create a navigation menu item
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.
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>
```
1. Find the `<app-drawer>` element in `src/my-app.html` and add a menu
item for your new page at the bottom.
Your menu should now look like the following:
```
...
<!-- Drawer content -->
<app-drawer>
<app-toolbar>Menu</app-toolbar>
Expand All @@ -116,40 +158,42 @@ navigate to the new page.
<a name="new-view" href="/new-view">New View</a>
</iron-selector>
</app-drawer>
...
```
Your new page is now ready!
Your new page is now ready! Open your web browser and view it at
[http://localhost:8080/new-view](http://localhost:8080/new-view).
![Example of new page](/images/1.0/toolbox/app-drawer-template-newview.png)
![Example of new page](/images/1.0/toolbox/starter-kit-newview.png)
## Register the page for the build
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
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
demand-loaded fragments like the lazy-loaded view you just added.
1. Open `polymer.json` in an editor.
1. Open `polymer.json` in a text editor.
1. Add `src/my-new-view.html` to the bottom of the `fragments` list.
1. Add `src/my-new-view.html` to the list of `fragments`.
The new list should look like this:
```
"fragments": [
"src/my-view1.html",
"src/my-view2.html",
"src/my-view3.html",
"src/my-new-view.html"
"src/my-new-view.html",
"src/my-view404.html"
]
```
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`.
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`.
## Next steps
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>
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).
Loading

0 comments on commit d019ea2

Please sign in to comment.