diff --git a/app/1.0/start/toolbox/add-elements.md b/app/1.0/start/toolbox/add-elements.md index 71f48591e1..eecba6186b 100644 --- a/app/1.0/start/toolbox/add-elements.md +++ b/app/1.0/start/toolbox/add-elements.md @@ -1,5 +1,5 @@ --- -title: Step 3. Add some elements +title: Step 3. Add an element subtitle: "Build an app with App Toolbox" --- @@ -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 `` 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`. ``` + ``` -1. Add the `` element to the template for the element. +1. Declare your new element at the bottom of the template for `my-new-view`. ``` +

New view

``` - You can add it under the `

` 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. - ``` - - - ``` - -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. + +Next step: Deploy [bower]: http://bower.io/ [catalog]: https://elements.polymer-project.org/ diff --git a/app/1.0/start/toolbox/create-a-page.md b/app/1.0/start/toolbox/create-a-page.md index 86efd0faa0..16f3582c41 100644 --- a/app/1.0/start/toolbox/create-a-page.md +++ b/app/1.0/start/toolbox/create-a-page.md @@ -5,20 +5,18 @@ subtitle: "Build an app with App Toolbox" -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`. ``` @@ -29,125 +27,85 @@ your new view. -

New view

- ``` -For now your element is very basic, and just has a `

` 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 ``: - - ``` - - - - - - - ``` - - The `` 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: ``` - + + + + + + ``` - Your `` 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} - ``` - - - - - - - - ``` +### 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 `` 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 `` 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 `` element. - - ``` - - - Menu - - View One - View Two - View Three - - - ``` - - Each navigation menu item consists of an anchor element (``) styled with CSS. - -1. Add the following new navigation item to the bottom of the menu. - - ``` - New View - ``` +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 `` element in `src/my-app.html` and add a menu + item for your new page at the bottom. ``` - ... Menu @@ -158,42 +116,40 @@ your new page. New View - ... ``` -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 -`` 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. `` 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. + +Next step: Add an element diff --git a/app/1.0/start/toolbox/deploy.md b/app/1.0/start/toolbox/deploy.md index 5d119ff2ef..79e7a72205 100644 --- a/app/1.0/start/toolbox/deploy.md +++ b/app/1.0/start/toolbox/deploy.md @@ -5,12 +5,12 @@ subtitle: "Build an app with App Toolbox" -In this step, you'll deploy your application to the web. +This tutorial teaches you how to build your website so that it's optimized +to be as fast as possible, and then deploy your app to a secure web site. ## Build for deployment -Run the following Polymer CLI command to perform a number of steps to prepare your -application for deployment: +Run the following to prepare your application for deployment. polymer build @@ -18,46 +18,51 @@ This command minifies the HTML, JS, and CSS dependencies of your application, and generates a service worker that precaches all of the dependencies of your application so that it can work offline. -The built files are output to the following folders: +The build command creates two optimized versions of your app: -* `build/unbundled`. Contains granular resources suitable for serving via HTTP/2 -with server push. -* `build/bundled`. Contains bundled (concatenated) resources suitable for serving -from servers or to clients that do not support HTTP/2 server push. +* `build/unbundled`. Contains granular resources suitable for serving via + HTTP/2 with server push. +* `build/bundled`. Contains bundled (concatenated) resources suitable for + serving from servers or to clients that do not support HTTP/2 server push. ## Deploy to a server Polymer applications can be deployed to any web server. +Whatever hosting option you choose, keep in mind that **Progressive Web Apps +must be served over secure (HTTPS) connections**. -This template utilizes the `` element to enable URL-based routing, -which requires that the server serve the `index.html` entry point for all -routes. +The app template you're using uses the `` element to enable +URL-based routing, which requires that the server serve the `index.html` entry +point for all routes. You can follow one of the sections below to deploy this app to either -[Google AppEngine](https://cloud.google.com/appengine) or [Firebase +[Google App Engine](https://cloud.google.com/appengine) or [Firebase Static Hosting](https://www.firebase.com/docs/hosting/), which are both free and secure approaches for deploying a Polymer app. The approach is similar for other hosting providers. ### Deploy with AppEngine -1. Download the [Google App Engine SDK](https://cloud.google.com/appengine/downloads) -and follow the instructions for your platform to install it. +1. Download and install the [Google App Engine + SDK](https://cloud.google.com/appengine/downloads). This tutorial is going + to use the Python SDK for example, but you can use any of the other ones. -1. [Sign up for an AppEngine account](https://cloud.google.com/appengine). +1. Open up the Google App Engine Launcher (`GoogleAppEngineLauncher`) + at least once and give the launcher permission to create symlinks. -1. [Open the project dashboard](https://console.cloud.google.com/iam-admin/projects) -and create a new project +1. [Sign up for a Google App Engine + account](https://cloud.google.com/appengine). - * Click the Create Project button. - * Type a project name. - * Click the Create button. +1. Open the [project + dashboard](https://console.cloud.google.com/iam-admin/projects). + +1. Create a new project. 1. `cd` into your project directory. -1. Create an `app.yaml` file and instruct the server to serve up -`index.html` for any URL's that don't otherwise end in a file extension. -Replace `{project name}` with the name you chose in the previous step. +1. Create an `app.yaml` file with the following contents. Replace + `{project name}` with the project name that you just created in the + Google App Engine dashboard. ``` application: {project name} @@ -95,47 +100,52 @@ Replace `{project name}` with the name you chose in the previous step. secure: always ``` -1. Deploy. +1. Run the following command to deploy. Replace `{project name}` with your + Google App Engine project name. appcfg.py -A {project name} update app.yaml + If you didn't open up Google App Engine Launcher and give it permission to + create symlinks, the `appcfg.py` command probably won't be available on + your command line. + {.alert .alert-warning} + ### Deploy with Firebase The instructions below are based on the [Firebase hosting quick start guide](https://www.firebase.com/docs/hosting/quickstart.html). -1. [Sign up for a Firebase account](https://www.firebase.com/signup/). +1. [Sign up for a Firebase account](https://firebase.google.com/). + +1. Go to the [Firebase console](https://console.firebase.google.com) + and create a new project. 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 the root directory of your project. -1. `cd` into your project directory. - -1. Inititalize the Firebase application. +1. Log in to your account. firebase login + +1. Initialize your Firebase project. + firebase init - Firebase asks you which app you would like to use for hosting. If you just - signed up, you should see one app with a randomly-generated name. You can - use that one. Otherwise go to - [https://www.firebase.com/account](https://www.firebase.com/account) to - create a new app. + Firebase CLI asks you various questions: -1. Firebase asks you the name of your app's public directory. Enter - `build/bundled`. This works because when you run `polymer build` to - build your application, Polymer CLI places your bundled application - appropriate for serving on Firebase into the `build/bundled` folder. + * Press the `Space` key to disable the `Database: Deploy Firebase + Realtime Database Rules` option. Keep the `Hosting` option enabled. + Press the `Enter` key to confirm. + * Use `build/bundled` for your public directory. + * For `Configure as a single-page app` type `y`. + * Associate your app with the Firebase project that you just created. -1. Edit your firebase configuration to add support for URL routing. Add - the following section to your `firebase.json` file, which will instruct - Firebase to serve up `index.html` for any URL's that don't otherwise - end in a file extension. +1. Edit your firebase configuration to add support for URL routing. Edit + the following section of your `firebase.json` file to match the code + below. ``` "rewrites": [ { @@ -144,8 +154,13 @@ guide](https://www.firebase.com/docs/hosting/quickstart.html). } ] ``` + This instructs Firebase to serve up `index.html` for any URLs that don't + otherwise end in a file extension. + {.alert .alert-info} + 1. Deploy. firebase deploy - The URL to your live site is listed in the output. + The URL to your live site is listed in the output. You can also open + the site in your default browser by running `firebase open hosting:site`. diff --git a/app/1.0/start/toolbox/set-up.md b/app/1.0/start/toolbox/set-up.md index 556b544246..89c3b1676f 100644 --- a/app/1.0/start/toolbox/set-up.md +++ b/app/1.0/start/toolbox/set-up.md @@ -5,85 +5,106 @@ subtitle: "Build an app with App Toolbox" -The [Polymer App Toolbox][toolbox] is a collection of components, tools and -templates for building Progressive Web Apps with Polymer. +These tutorials teach you how to initialize, customize, and deploy a +[Progressive Web App][PWA] using Polymer in less than 30 minutes. -Follow the instructions below to install, build, and deploy a project using an -App Toolbox template in less than 15 minutes. +The app you'll be building is built on top of the [Polymer App +Toolbox][toolbox]. The Toolbox is a collection of reusable web components, +tools, and app templates. -## Install the Polymer CLI +[PWA]: https://developers.google.com/web/progressive-web-apps -1. Install the LTS version (4.x) of Node.js. The current version (6.x) should work, but is not - officially supported. Versions below LTS are not supported. +## Install Polymer CLI -1. Install the Polymer CLI +Polymer CLI is an all-in-one command line tool for Polymer projects. In these +tutorials you use Polymer CLI to initialize, serve, and build your project. You +can also use it for linting and testing, but these tutorials won't cover those +topics. - npm install -g polymer-cli - -## Initialize your project from a template - -1. Create a new project folder to start from - - mkdir my-app - cd my-app +1. Check that you have already installed all of Polymer CLI's dependencies + by running the following commands. -1. Initialize your project with an app template + * Git - polymer init starter-kit + git --version -## Serve your project + * Node.js (LTS version or higher) -The App Toolbox templates do not require any build steps to get started -developing. You can serve the application using the Polymer CLI, and -file changes you make will be immediately visible by refreshing -your browser. + node -v - polymer serve --open + * Bower -The task above automatically opens up your default web browser and -fetches the locally-hosted application (at `http://localhost:8080`). + bower -v -![App Toolbox: Starter Kit Template](/images/1.0/toolbox/starter-kit.png) + You should see the typical output indicating what version you're running + of each of these dependencies. + If you're missing any of these dependencies, follow the instructions in + the following section from the Polymer CLI guide to learn how to install + each one: [Install section from Polymer + CLI guide](/1.0/docs/tools/polymer-cli#install). -## Initialize Git repository (optional) +1. Install Polymer CLI. -Your app template 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 project. + npm install -g polymer-cli -1. Initialize a Git repository. +## Initialize your project - git init +1. Create a new directory for your project. -1. Add and commit all of the files. + mkdir my-app + cd my-app - git add . && git commit -m "Initial commit." +1. Initialize your project. -## Directory structure + polymer init app-drawer-template -The diagram below is a brief summary of the directories within the template. +## Serve your project - / - |---index.html - |---src/ - |---bower_components/ - |---images/ - |---test/ +As you progress through the tutorials, keep the following command running +in the background to locally serve your app. Whenever you make a change +to a file, just refresh your browser to view the changes. + polymer serve --open -* `index.html` is the main entry point into your application -* `src/` is where your application-specific custom elements will go -* `bower_components/` is where reusable custom elements and/or libraries - fetched via bower will go -* `images/` is for static images -* `test/` is where you [define tests for your web - components](https://github.com/Polymer/web-component-tester). +This command starts the local server, automatically opens up your default +browser and fetches your app at `http://localhost:8080`. + +You can pass a string after `--open` to use a different browser (e.g. +`polymer serve --open 'Google Chrome Canary'`). +{.alert .alert-info} + +![App Toolbox Drawer Template](/images/1.0/toolbox/app-drawer-template.png) + +## Project structure + +The diagram below is a brief summary of the files and directories within +the project. + +``` +bower.json # bower configuration +bower_components/ # app dependencies +images/ +index.html # main entry point into your app +manifest.json # app manifest configuration +polymer.json # Polymer CLI configuration +service-worker.js # auto-generated service worker +src/ # app-specific elements + my-app.html # top-level element + my-icons.html # app icons + my-view1.html # sample views or "pages" + my-view2.hmtl + my-view3.html +sw-precache-config.js # service worker pre-cache configuration +test/ # unit tests +``` ## Next steps -Now that your App Toolbox template is up and running, learn how to [add a new -page of content](create-a-page), or how to [deploy the app to the web](deploy). +Your app is now up and running locally. Next, learn how to add +a page to your app. + +Next step: Create a page [toolbox]: /1.0/toolbox/ [shared styles]: /1.0/docs/devguide/styling.html#style-modules