GreenPolyProducts/polymer-starter-kit
5
0
Fork 0
mirror of https://github.com/Polymer/polymer-starter-kit.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #846 from kaycebasques/tutorials

Browse Source 
add updated tutorials from polymer-project.org
This commit is contained in:
Kayce Basques
2016-06-07 08:45:54 -07:00
parent 63f2e2ec70 cd1c622753
commit c1f1c0245c
7 changed files with 410 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@@ -20,9 +20,9 @@ See latest Polymer Starter Kit Demo (from master) at https://polymerelements.git
Check out the Polymer Starter Kit tutorials on [polymer-project.org](https://www.polymer-project.org):
* [Set up the PSK](https://www.polymer-project.org/1.0/docs/start/psk/set-up.html)
* [Create a page](https://www.polymer-project.org/1.0/docs/start/psk/create-a-page.html)
* [Deploy the PSK to the web](https://www.polymer-project.org/1.0/docs/start/psk/deploy.html)
* [Set up the PSK](docs/tutorials/set-up.md)
* [Create a page](docs/tutorials/create-a-page.md)
* [Deploy the PSK to the web](docs/tutorials/deploy.md)
## Getting Started

10
docs/README.md
View File

@@ -1,4 +1,12 @@
# Recipes
# Docs
## Tutorials
* [Set up](tutorials/set-up.md)
* [Create a page](tutorials/create-a-page.md)
* [Deploy](tutorials/deploy.md)
## Recipes
* [Add ES2015 (formally ES6) support using Babel](add-es2015-support-babel.md)
* [Polymer Performance Recipe](polymer-perf.md)

210
docs/tutorials/create-a-page.md Normal file
View File

@@ -0,0 +1,210 @@
# Create a new page
This Polymer Starter Kit tutorial teaches you how to:
* Create a new menu item in the navigation menu.
* Create content for a new page.
* Route traffic to your new page.
This tutorial assumes you have already completed the
[Set up tutorial](set-up.md).
## Serve the app locally
1. `cd` to the base directory of your project.
1. Start the local development server.
gulp serve
The local development server opens the application in your default
web browser. As you modify your application, the server detects the
modifications, re-builds the application, and reloads your browser
automatically. There is no need to re-load the browser or the application.
## Create a navigation menu item
1. Open `app/index.html` in a text editor.
1. Find the navigation menu.
```
...
<!-- Drawer Content -->
<paper-menu attr-for-selected="data-route" selected="[[route]]">
<a data-route="home" href="{{baseUrl}}">
<iron-icon icon="home"></iron-icon>
<span>Home</span>
</a>
...
```
Each navigation menu item consists of an anchor element (`<a>`) with two
children: `<iron-icon>` and `<span>`.
* `<iron-icon>` displays a single icon.
* `<span>` displays the text next to the icon.
1. Add the following new navigation item to the bottom of the menu.
```
<a data-route="books" href="{{baseUrl}}books">
<iron-icon icon="book"></iron-icon>
<span>Books</span>
</a>
```
Your menu should now look like the following:
```
...
<!-- Drawer Content -->
<paper-menu attr-for-selected="data-route" selected="[[route]]">
<a data-route="home" href="{{baseUrl}}">
<iron-icon icon="home"></iron-icon>
<span>Home</span>
</a>
...
<a data-route="contact" href="{{baseUrl}}contact">
<iron-icon icon="mail"></iron-icon>
<span>Contact</span>
</a>
<a data-route="books" href="{{baseUrl}}books">
<iron-icon icon="book"></iron-icon>
<span>Books</span>
</a>
</paper-menu>
...
```
If you view the app now, you should see your new item in the navigation
menu, but the link does not point to a valid page yet.
## Add content
In the previous section you added a navigation menu item to enable the
user to navigate to a new page. Now, you add the content for that new page.
1. Open `app/index.html` in a text editor and find the main content.
```
<div class="content">
<iron-pages attr-for-selected="data-route" selected="{{route}}">
<section data-route="home">
<paper-material elevation="1">
<my-greeting></my-greeting>
<p class="subhead">You now have:</p>
<my-list></my-list>
...
</paper-material>
</section>
<section data-route="users">
<paper-material elevation="1">
<h2 class="page-title">Users</h2>
<p>This is the users section</p>
<a href$="{{baseUrl}}users/Addy">Addy</a><br>
<a href$="{{baseUrl}}users/Rob">Rob</a><br>
<a href$="{{baseUrl}}users/Chuck">Chuck</a><br>
<a href$="{{baseUrl}}users/Sam">Sam</a>
</paper-material>
</section>
...
```
* The PSK's design pattern for structuring pages is to make each page a
`<section>` element. The `<iron-pages>` element controls which page is
displayed at any given time.
* The `data-route` attribute is an identifier for the routing system.
You'll set that up for your new page in the next section.
* The `<paper-material>` element creates a card which floats on top of the
main content area. If you want to follow the Material Design
specification, all main content should be displayed on top of one of these
cards.
* The `elevation` attribute determines how high a `<paper-material>` element
appears to visually float above the main content area. Experiment by
setting it to values between `0` and `5`.
1. Add the following content to the bottom of the main section area.
```
<section data-route="books">
<paper-material elevation="1">
<p>Hello, World!</p>
</paper-material>
</section>
```
Your code should now look like the following:
```
...
<!-- Main Content -->
<div class="content">
<iron-pages attr-for-selected="data-route" selected="{{route}}">
...
<section data-route="contact">
<paper-material elevation="1">
<h2 class="page-title">Contact</h2>
<p>This is the contact section</p>
</paper-material>
</section>
<section data-route="books">
<paper-material elevation="1">
<p>Hello, World!</p>
</paper-material>
</section>
</iron-pages>
</div>
...
```
You now have content to link your new navigation item to. In the
next section you'll link your navigation item to your new content.
## Route traffic to the new content
In this last tutorial, you make a minor modification to the routing system
so that when a user clicks on the new "Books" navigation menu item, they
get routed properly to your new page.
1. Open `app/elements/routing.html` in a text editor and add the following
code near the bottom of the script, just below the page rule for
`/contact`.
```
page('/books', function () {
app.route = 'books';
});
```
Your script should now look like the following:
```
...
page('/', function () {
app.route = 'home';
});
...
page('/contact', function () {
app.route = 'contact';
});
page('/books', function () {
app.route = 'books';
});
...
```
Your new page is now ready! Open your web browser and view it at
[http://localhost:5000/#!/books](http://localhost:5000/#!/books).
![Example of new page](psk-tutorial-books-page.png)

54
docs/tutorials/deploy.md Normal file
View File

@@ -0,0 +1,54 @@
# Deploy
This tutorial teaches you how to deploy your Polymer Starter Kit application.
If you have not completed the [Set up tutorial](set-up.md), do so now
before attempting this tutorial.
## Deploy with Firebase (recommended)
Firebase is a very simple and secure way to deploy a PSK site. You can sign
up for a free account and deploy your application in less than 5 minutes.
The instructions below are based on the [Firebase hosting quick start
guide](https://firebase.google.com/docs/hosting/quickstart).
1. [Sign up for a Firebase account](https://firebase.google.com).
1. Install the Firebase command line tools.
npm install -g firebase-tools
The `-g` flag instructs `npm` to install the package globally so that you
can use the `firebase` command from any directory. You may need
to install the package with `sudo` privileges.
1. `cd` into your project directory.
1. Inititalize the Firebase application.
firebase login
firebase init
1. Press `Space` to disable the Database feature. Leave the Hosting feature
enabled. Press `Enter` to confirm your choices.
1. Firebase asks you the name of your app's public directory. Enter `dist`.
This works because when you run `gulp` to build your application, PSK
builds everything and places it all in `dist`. So `dist` contains
everything your application needs to run.
1. When Firebase asks you `Configure as a single-page app
(rewrite all urls to /index.html)?` select `No`.
1. When Firebase asks `File dist/index.html already exists. Overwrite?`
select `No`.
1. Select which app you want to deploy to.
1. Run the following command to deploy.
firebase deploy
1. You can view your site at the URL listed in the output, or by running
`firebase open hosting:site`.

BIN
docs/tutorials/psk-home.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 187 KiB

BIN
docs/tutorials/psk-tutorial-books-page.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

134
docs/tutorials/set-up.md Normal file
View File

@@ -0,0 +1,134 @@
# Set up
The Polymer Starter Kit is a complete starting point for a Polymer 1.0
application. It includes:
* A [Material Design][md] layout.
* Routing with Page.js.
* Unit testing with [web-component-tester](https://github.com/Polymer/web-component-tester).
* An end-to-end toolchain for build and local development.
Follow the instructions below to install, build, and run the
Polymer Starter Kit (PSK) locally in less than 15 minutes.
## Install the Polymer Starter Kit and dependencies
1. Install [Node.js](https://nodejs.org/) (`node`) version 0.12 or above.
Node.js includes Node Package Manager (`npm`) by default. The PSK
uses `npm` to install and manage tooling.
1. Verify that you're running `node` version 0.12 or above and `npm`
version 2.11 or above.
node -v
v0.12.5
npm -v
2.12.2
1. Install Gulp and Bower.
npm install -g gulp bower
Note: the `-g` flag installs Gulp and Bower globally, so you may need to
execute the script with `sudo` privileges. The reason they are installed
globally is because some scripts in the PSK expect
`gulp` and `bower` to be available from the command line.
1. Download the [latest PSK release](https://github.com/PolymerElements/polymer-starter-kit/releases/latest).
There are two versions of the PSK, a light version (e.g.
`polymer-starter-kit-light-x.x.x.zip`)
and a full version (e.g. `polymer-starter-kit-x.x.x.zip`). Download
the full
version.
1. Unzip the file to a suitable location. After unzipping the file
you should have a directory called `polymer-starter-kit-x.x.x`.
You can rename the directory to something more relevant to your project.
1. `cd` into the base directory of your PSK project.
1. Install the build and toolchain dependencies.
npm install
1. Install the application dependencies.
bower install
## Directory structure
The diagram below is a brief summary of the directories within the PSK.
/
|---app/
| |---elements/
| |---images/
| |---scripts/
| |---styles/
| |---test/
|---docs/
|---dist/
* `app/` is where you store all of your source code and do all of your
development.
* `elements/` is where you keep your custom elements.
* `images/` is for static images.
* `scripts/` is the place for JS scripts.
* `styles/` houses your app's [shared styles][shared styles] and CSS rules.
* `test/` is where you [define tests for your web
components](https://github.com/Polymer/web-component-tester).
* `docs/` contains optional "recipes" (how-to guides) for adding features
to your application or for using optional tools or editors.
* `dist/` is the directory to deploy to production. When you run the
build task, files are prepared for production (HTML imports are
vulcanzied, scripts are minimized, and so on) and output to this directory.
## Initialize Git repository (optional)
Your PSK installment does not contain any version control system. Follow the
instructions below if you want to manage your source code with Git.
1. `cd` into the base directory of your PSK project.
1. Initialize a Git repository.
git init
1. Add and commit all of the files.
git add . && git commit -m "Add Polymer Starter Kit."
## Build and serve
The PSK is ready to be built and ran locally.
1. `cd` into the base directory of your PSK project.
1. Build the app.
gulp
1. Serve the app locally.
gulp serve
The local development server automatically detects file modifications
and re-builds the application. As long as you keep the `gulp serve`
task running there is no need to re-build or re-serve the app while
you develop.
The task above automatically opens up your default web browser and
fetches the locally-hosted application (at `http://localhost:5000`).
![PSK homepage](psk-home.png)
## Next steps
Now that your PSK is up and running, learn how to [add a new page of
content](create-a-page.md), or how to [deploy the app to the
web](deploy.md).
[shared styles]: /1.0/docs/devguide/styling.html#style-modules
[md]: http://www.google.com/design/spec/material-design/introduction.html