From 4b0a5be42b5722a994211d106b93b652b7543030 Mon Sep 17 00:00:00 2001 From: Chuck Horton Date: Wed, 1 Jun 2016 10:49:21 -0700 Subject: [PATCH] Remove Docs directory (#836) --- docs/README.md | 11 -- docs/add-es2015-support-babel.md | 149 ------------------------- docs/add-eslint-support.md | 100 ----------------- docs/chrome-dev-editor.md | 52 --------- docs/deploy-to-firebase-pretty-urls.md | 67 ----------- docs/deploy-to-github-pages.md | 32 ------ docs/deploy-to-google-app-engine.md | 108 ------------------ docs/firebase.json | 13 --- docs/mobile-chrome-apps.md | 131 ---------------------- docs/neon-animated-pages.md | 122 -------------------- docs/polymer-perf.md | 124 -------------------- 11 files changed, 909 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/add-es2015-support-babel.md delete mode 100644 docs/add-eslint-support.md delete mode 100644 docs/chrome-dev-editor.md delete mode 100644 docs/deploy-to-firebase-pretty-urls.md delete mode 100644 docs/deploy-to-github-pages.md delete mode 100644 docs/deploy-to-google-app-engine.md delete mode 100644 docs/firebase.json delete mode 100644 docs/mobile-chrome-apps.md delete mode 100644 docs/neon-animated-pages.md delete mode 100644 docs/polymer-perf.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 0dcba3845..000000000 --- a/docs/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Recipes - -* [Add ES2015 (formally ES6) support using Babel](add-es2015-support-babel.md) -* [Polymer Performance Recipe](polymer-perf.md) -* [Use PSK with Chrome Dev Editor](chrome-dev-editor.md) -* [Deploy to Github Pages](deploy-to-github-pages.md) -* [Deploy to Firebase using Pretty URLs](deploy-to-firebase-pretty-urls.md) -* [Deploy to Google App Engine](deploy-to-google-app-engine.md) -* [Use PSK for Mobile Chrome Apps](mobile-chrome-apps.md) -* [Add page transitions with neon-animated-pages](neon-animated-pages.md) -* [Add ESLint support](add-eslint-support.md) diff --git a/docs/add-es2015-support-babel.md b/docs/add-es2015-support-babel.md deleted file mode 100644 index 9a196f0c5..000000000 --- a/docs/add-es2015-support-babel.md +++ /dev/null @@ -1,149 +0,0 @@ -# Add ES2015 support through Babel - -Although support for ES2015 (formerly ES6) is improving in modern browsers, the majority do not yet support the full set of features. To benefit from the awesomeness of the new ES2015 syntax while keeping backwards compatibility with Polymer's supported browsers, you'll need to transpile your JS code from ES2015 to ES5 - -This recipe focuses on adding an ES2015 to ES5 transpile step to Polymer Starter Kit's build pipeline using [BabelJS](https://babeljs.io/). - - -## Create a transpile gulp task - -- Install the gulp Babel, Sourcemap, Crisper plugins and Babel ES2015 preset: `npm install --save-dev gulp-babel gulp-sourcemaps gulp-crisper babel-preset-es2015` -- Add the following gulp task in the `gulpfile.js` file: - -```patch -+ // Transpile all JS to ES5. -+ gulp.task('js', function() { -+ return gulp.src(['app/**/*.{js,html}', '!app/bower_components/**/*']) -+ .pipe($.sourcemaps.init()) -+ .pipe($.if('*.html', $.crisper({scriptInHead: false}))) // Extract JS from .html files -+ .pipe($.if('*.js', $.babel({ -+ presets: ['es2015'] -+ }))) -+ .pipe($.sourcemaps.write('.')) -+ .pipe(gulp.dest('.tmp/')) -+ .pipe(gulp.dest(dist())); -+ }); -``` - -This task will transpile all JS files and inline JS inside HTML files and also generate sourcemaps. The resulting files are generated in the `.tmp` and the `dist` folders - -[Crisper](https://github.com/PolymerLabs/crisper) extracts JavaScript that's inline to HTML files (such as imports). We need this as Babel does not support transpiling HTML files such as ` -``` diff --git a/docs/add-eslint-support.md b/docs/add-eslint-support.md deleted file mode 100644 index 9e06f227c..000000000 --- a/docs/add-eslint-support.md +++ /dev/null @@ -1,100 +0,0 @@ -# Add ESLint support - -This recipe helps you to create a task to use [ESLint](http://eslint.org/) tool. - - -## Create .eslintrc.json file in the root folder - -``` -{ - "extends": "eslint:recommended", - "rules": { - "no-console": 0 - }, - "env": { - "browser": true - }, - "plugins": [ - "html" - ], - "globals": { - "__dirname": false, - "app": false, - "page": false, - "Polymer": false, - "process": false, - "require": false - } -} -``` - -## Create .eslintignore file in the root folder - -``` -/app/bower_components/** -/dist/** -``` - - -## Create a lint gulp task - -- Install the gulp-eslint and eslint-plugin-html: `npm install --save-dev gulp-eslint eslint-plugin-html` -- Add the following gulp task in the `gulpfile.js` file: - -```patch - -+ // Lint JavaScript -+ gulp.task('lint', function() { -+ return gulp.src([ -+ 'app/scripts/**/*.js', -+ 'app/elements/**/*.html', -+ 'gulpfile.js' -+ ]) -+ .pipe(reload({ -+ stream: true, -+ once: true -+ })) -+ .pipe($.eslint()) -+ .pipe($.eslint.format()) -+ .pipe($.eslint.failAfterError()); -+ }); -``` - -This task will check all JS files and JS inside HTML files. - - -## Integrating the lint task - -Make sure the `lint` gulp task is triggered by the common build tasks: - - - In the gulp `serve` task, make sure `lint` is triggered initially and on HTML and JS files changes: - -```patch --gulp.task('serve', ['styles'], function () { -+gulp.task('serve', ['lint', 'styles'], function () { - - ... - - gulp.watch(['app/**/*.html', '!app/bower_components/**/*.html'], reload); - gulp.watch(['app/styles/**/*.css'], ['styles', reload]); -+ gulp.watch(['app/{scripts,elements}/**/{*.js,*.html}'], ['lint', reload]); - gulp.watch(['app/images/**/*'], reload); -}); -``` - - - In the `default` task make sure `lint` is run in parallel to `images`, `fonts` and `html`: - -```patch -gulp.task('default', ['clean'], function (cb) { - - ... - - runSequence( - ['copy', 'styles'], -- ['images', 'fonts', 'html'], -+ ['lint', 'images', 'fonts', 'html'], - 'vulcanize', // 'cache-config', - cb); -}); -``` - diff --git a/docs/chrome-dev-editor.md b/docs/chrome-dev-editor.md deleted file mode 100644 index 547404e6d..000000000 --- a/docs/chrome-dev-editor.md +++ /dev/null @@ -1,52 +0,0 @@ -# Use Polymer Starter Kit on Chrome Dev Editor - -If you are using a Chromebook, one of the few IDE you can use is [Chrome Dev Editor](https://github.com/GoogleChrome/chromedeveditor). - -To use the Polymer Starter Kit you have to download the [latest release](https://github.com/PolymerElements/polymer-starter-kit/releases) in the `light` flavor (the additional tools can't be used from CDE). - -After downloading the `polymer-starter-kit-light-*.zip` file unpack it in a new folder (for Example `psk-light`) you should have a directory structure like - -![psk-light-folder-p1](https://cloud.githubusercontent.com/assets/1431346/9451900/a73ffcf2-4ab1-11e5-8742-e0b5523ba9d5.png) - -When the app first opens you'll notice, in the bottom left, that Bower is updating. - -![bower updating](https://cloud.githubusercontent.com/assets/1066253/11860260/d837edae-a427-11e5-997e-117caa83bbed.png) - -Wait for this process to finish before continuing (it may take a few minutes). When it is complete, you should notice that the `bower_components` directory has moved to `app/bower_components`. This is because CDE is respecting the configuration in our `.bowerrc` file. This is a good thing :) - -We can now `Open Folder...` inside CDE and start renaming the file `app/manifest.json` to `app/web-app-manifest.json`, followed by updating the link to it in the file `app/index.html` - -![manifest json](https://cloud.githubusercontent.com/assets/1431346/9452182/27e41478-4ab3-11e5-8e40-d7c0f1249feb.png) - - -*This change is needed because `manifest.json` is interpreted by CDE as a [Chrome Apps Manifest](https://developer.chrome.com/extensions/manifest) and the [web app manifest](https://w3c.github.io/manifest/) is slightly different* - -Open `app/elements/routing.html` and add the following code after the last route: - -```javascript -page('*', function () { - app.route = 'home'; -}); -``` - -After the change, the code will look like the following: - -```javascript -... -page('/contact', function () { - app.route = 'contact'; -}); - -page('*', function () { - app.route = 'home'; -}); - -// add #! before urls -page({ - hashbang: true -}); -... -``` - - -Select `app/index.html` and hit run (or press CTRL+R) to see the application running in the browser. diff --git a/docs/deploy-to-firebase-pretty-urls.md b/docs/deploy-to-firebase-pretty-urls.md deleted file mode 100644 index 05f820671..000000000 --- a/docs/deploy-to-firebase-pretty-urls.md +++ /dev/null @@ -1,67 +0,0 @@ -# Deploy to Firebase using Pretty URLs - -Firebase is a very simple and secure way to deploy a Polymer Starter Kit 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://www.firebase.com/docs/hosting/quickstart.html). - -1. [Sign up for a Firebase account](https://www.firebase.com/signup/) - -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 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. - -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. Edit firebase.json, change firebase name, and add `rewrites` section ([see example firebase.json](/docs/firebase.json)). - - { - "firebase": "polymer-starter-kit", - "public": "dist", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "rewrites": [ { - "source": "!{/bower_components,/elements}/**", - "destination": "/index.html" - } ] - } - -1. Add `` to `head` near top of index.html, above ```` - -1. Remove `hashbang: true` in routing.html near bottom. The call to `page` should look like this now: - - page(); - -1. Build - - gulp - -1. Deploy - - firebase deploy - - The URL to your live site is listed in the output. - -You can see a demo of Polymer Starter Kit hosted on Firebase using pretty URLs at https://polymer-starter-kit.firebaseapp.com. diff --git a/docs/deploy-to-github-pages.md b/docs/deploy-to-github-pages.md deleted file mode 100644 index 570ee0053..000000000 --- a/docs/deploy-to-github-pages.md +++ /dev/null @@ -1,32 +0,0 @@ -# Deploy to Github Pages - -You can deploy to github pages with a couple minor changes to Polymer Starter Kit: - -1. Uncomment this line `// app.baseUrl = '/polymer-starter-kit/';` in app.js near the top - - ```JavaScript - // Sets app default base URL - app.baseUrl = '/'; - if (window.location.port === '') { // if production - // Uncomment app.baseURL below and - // set app.baseURL to '/your-pathname/' if running from folder in production - // app.baseUrl = '/polymer-starter-kit/'; - } - ``` - -2. Change `app.baseUrl = '/polymer-starter-kit/';` to `app.baseUrl = '/your-pathname/';` (ex: if you repo is `github.com/username/bobs-awesome-site` you would change this to `app.baseUrl = '/bobs-awesome-site/';`) - -3. Add this code at the top of `` tag in the [index.html](../app/index.html) to force HTTPS: - - ```html - - ``` - -4. Run `gulp build-deploy-gh-pages` from command line - -5. To see changes wait 1-2 minutes then load Github pages for your app (ex: https://polymerelements.github.io/polymer-starter-kit) - -### Notes - -* When deploying to Github Pages we recommend using hashbangs which is Polymer Starter Kit default. -* This method should work for most hosting providers when using a subfolder. diff --git a/docs/deploy-to-google-app-engine.md b/docs/deploy-to-google-app-engine.md deleted file mode 100644 index 660daa897..000000000 --- a/docs/deploy-to-google-app-engine.md +++ /dev/null @@ -1,108 +0,0 @@ -# Deploy to Google App Engine - -Google App Engine is a great way to host your Polymer application using Google infrastructure. - -[You can sign up for a Google Cloud Platform free account](https://cloud.google.com/). - -There are multiple ways to host web app on GCP, but my favorite one is using GAE. - -The scripts below are based on the [Using Static Files guide](https://cloud.google.com/appengine/docs/python/gettingstartedpython27/staticfiles) and [Polymer Gmail by @ebidel](https://github.com/ebidel/polymer-gmail) repository. - -1. Install the gcloud command line tools - - curl https://sdk.cloud.google.com | bash - - Detailed instructions can be found [here](https://cloud.google.com/sdk/) - -1. Inititalize gcloud - - gcloud init - - In this step you will be asked to login to your GCP account and set default settings, such as project, zone & region, etc. - -1. Create a new GCP project using the [Developers Console](https://console.developers.google.com/home/dashboard) - -1. Add `app.yaml` to your project root folder - - ```yaml - runtime: python27 - api_version: 1 - threadsafe: yes - - handlers: - - - url: /bower_components - static_dir: bower_components - secure: always - - - url: /images - static_dir: images - secure: always - - - url: /(.*).(html|js|json|css) - static_files: \1.\2 - upload: (.*)\.(html|js|json|css) - secure: always - - - url: / - static_files: index.html - upload: index\.html - http_headers: - Link: '; rel=preload; as=script, ; rel=preload; as=document, ; rel=preload; as=style' - # Access-Control-Allow-Origin: "*" - secure: always - - skip_files: - - ^(.*/)?app\.yaml - ``` - - This is the configuration file for the GCP project. - It sets a python runtime environment and static file handlers. - The configuration utilizes GAE HTTP/2 capabilities in order to minimize load time for HTTP/2 compatible browsers. - - **Please note**: This also ensures HTTPS; if you wish to use custom domains supporting HTTP only, you will need to remove all the 'secure: always’ entries. If you decide to have custom domains that only use HTTP instead of HTTPS, be aware some Web platform APIs such as service workers and Web app manifests, including some elements that depend on such APIs for their functionality, only work with HTTPS. - -1. Add a bash script to build & deploy the application - - ```sh - #!/usr/bin/env bash - - GAE_PROJECT=psk - DEPLOY_VERSION=$1 - - if [ -z "$DEPLOY_VERSION" ] - then - TAG=`git describe --abbrev=0` - # GAE doesn't allow periods - DEPLOY_VERSION=${TAG//.} - fi - - # Build it. - echo "Building $DEPLOY_VERSION" - gulp - cp app.yaml dist/app.yaml - - echo "Deploying $DEPLOY_VERSION" - gcloud preview app deploy dist/app.yaml --project $GAE_PROJECT --promote --version $DEPLOY_VERSION - ``` - - You have to set `GAE_PROJECT` variable to your GAE project id. - A deploy version can be provided as a parameter for the script, if not provided the latest git tag will be used. - -1. Add execution permission to the script - - chmod +x deploy.sh - -1. Run the deploy script - - Without version argument in order to use the latest git tag - - ./deploy.sh - - Or with a version argument (according to GAE version [limitations](https://cloud.google.com/appengine/docs/python/config/appconfig?hl=en)) - - ./deploy.sh v100 - - The URL to your live site is listed in the output. - -Enjoy! diff --git a/docs/firebase.json b/docs/firebase.json deleted file mode 100644 index 5b184bdc5..000000000 --- a/docs/firebase.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "firebase": "polymer-starter-kit", - "public": "dist", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "rewrites": [ { - "source": "!{/bower_components,/elements}/**", - "destination": "/index.html" - } ] -} diff --git a/docs/mobile-chrome-apps.md b/docs/mobile-chrome-apps.md deleted file mode 100644 index 5cf87c7f3..000000000 --- a/docs/mobile-chrome-apps.md +++ /dev/null @@ -1,131 +0,0 @@ -# Use Polymer Starter Kit for [Mobile Chrome Apps](https://github.com/MobileChromeApps/mobile-chrome-apps) - -## Getting started - -Polymer Starter Kit could be fully adapted to Mobile Chrome Apps through mobile-friendly features. Mobile Chrome Apps, is based on Apache Cordova, and requires mobile application SDKs such as Android and iOS. so please make sure that installation development tool by following [installation guide](https://github.com/MobileChromeApps/mobile-chrome-apps/blob/master/docs/Installation.md) of Mobile Chrome Apps. And then, You do some further steps to resolve some of restrictions and configurations to use Polymer Starter Kit on Cordova. Looking for a [guide video](https://www.youtube.com/watch?v=-ifgyobPLVg) below to better understand. - -[![](https://camo.githubusercontent.com/7c498c4d60113dd1ea072576df897283100428b6/687474703a2f2f696d672e796f75747562652e636f6d2f76692f2d696667796f62504c56672f302e6a7067)](https://www.youtube.com/watch?v=-ifgyobPLVg) - -## Download Polymer Starter Kit into your workspace - -To download and preparation, follow this [guide of Polymer Starter Kit](https://github.com/PolymerElements/polymer-starter-kit#getting-started). Make sure that install all of dependencies of npm and Bower. - -## Create a Cordova project - -Create a Cordova project in path `polymer-starter-kit` by following command. `platform` is the path for Cordova project files, `com.your.app` is the project name/id and next following string is the description for your app. - -```sh -cca create platform com.your.app "Your Polymer Starter Kit App" -``` - -If you have no problems while creating a project you will seeing the message of installing successful coming from Cordova and have the tree of the project below. - -```sh -└── polymer-starter-kit - └── app - │   ├── elements - │   ├── images - │   ├── index.html - │   ├── manifest.json - │   ├── scripts - │   ├── styles - │   └── test - ├── bower.json - ├── bower_components - ├── docs - ├── gulpfile.js - ├── node_modules - ├── package.json - ├── platform - │   ├── config.xml - │   ├── hooks - │   ├── platforms - │   ├── plugins - │   └── www -``` - -For further informations of Cordova, please visit [corodova document](https://github.com/MobileChromeApps/mobile-chrome-apps/tree/master/docs) - -## Configuration - -You need to have some changes of configuration to fit for Mobile Chrome Apps as it was mentioned above. - -### Configure path for app built by gulp - -- Change the path `dist` in `gulpfile.js` from `dist` to `platform/www/app`, then the app built with Polymer Starter Kit will be placed under `platform/www` will be used by Cordova. - ```js - var DIST = 'platform/www/app'; - ``` - -- Change the path in `platform/www/background.js` into new path - ```js - chrome.app.runtime.onLaunched.addListener(function() { - chrome.app.window.create('app/index.html', { - width: 244, - height: 380, - }); - }); - ``` - -- Add path `/app` to `app.baseURL` in `app/scripts/app.js'. `platform/www` is root path of app that will prevent errors coming from page routing. - ```js - app.baseUrl = '/app'; - ``` - -### Update gulp tasks - -- Using `polybuild(vulcanize + crisper)` task is mandatory because of Chrome Apps doesn't allow inline script blocks according to [CSP](https://developer.chrome.com/apps/contentSecurityPolicy). You should replace current `vulcanize` task with new task below. To do this install `polybuild` first with `npm install --save-dev polybuild` command - ```js - // load polybuild - var polybuild = require('polybuild'); - - // Vulcanize granular configuration - gulp.task('vulcanize', function() { - return gulp.src('app/elements/elements.html') - .pipe(polybuild({maximumCrush: true})) - .pipe($.rename(function(file) { - if (file.extname === '.html') { - file.basename = file.basename.replace('.build', ''); - } - })) - .pipe(gulp.dest(dist('elements'))) - .pipe($.size({title: 'vulcanize'})); - }); - ``` - -### More updates - -- Remove useless files generated from Cordova. - ```sh - rm platform/www/index.* - ``` -- To complete first route for `home` you need to put try/catch block into the first route code on starting app, in `app/elements/routing.html`, because Chrome Apps doesn't allow using `history` APIs which related to error message `history.pushState/replaceState is not available in packaged apps`. - ```js - try { - page({ - hashbang: true - }); - } catch (e) { - app.route = 'home'; - } - ``` - -- Using `@import` instead of `link` to download external Google robot fonts which is related to `Refused to load the stylesheet` errors. Update code in `bower_components/font-roboto/roboto.html` to using `@import` code below - ``` - @import url(https://fonts.googleapis.com/css?family=Roboto:400,300,300italic,400italic,500,500italic,700,700italic); - @import url(https://fonts.googleapis.com/css?family=Roboto+Mono:400,700); - ``` - -## Build and run app - -After done of above steps. run this command on root path that let you see Chrome Apps built with Polymer Starter Kit. - -```sh -gulp && cd platform && cca run chrome -``` - -or to run on Android emulator or devices - -```sh -gulp && cd platform && cca run android -``` diff --git a/docs/neon-animated-pages.md b/docs/neon-animated-pages.md deleted file mode 100644 index 7219c67c2..000000000 --- a/docs/neon-animated-pages.md +++ /dev/null @@ -1,122 +0,0 @@ -# Add page transitions with neon-animated-pages - -This recipe focuses on replacing the "static" `iron-pages` component with `neon-animated-pages` in order to display slick animations when transitioning between pages. - -## Update your dependencies - -- First thing first, we need to replace the `iron-pages` import in `app/elements/elements.html` with a set of components from the `neon-animation` library, including `neon-animated-pages`: - -```patch -- -... -+ -+ -+ -+ -+ -+ -+ -``` -Note the last two imports are actually animations definitions. We are going to use `slide-from-bottom-animation` and `fade-out-animation` as entry and exit animations respectively. Those animations will apply for all page transitions. - -If you wish to use different animations, make sure you replace those imports by the ones you need. - -## Replace `iron-pages` with `neon-animated-pages` - -- Next, we need to remove the `iron-pages` from `app/index.html` and replace it with `neon-animated-pages`: - -```patch -- -+ -... -- -+ -``` -This is pretty straightforward, as these elements behave similarly and share a common API, being both based on `Polymer.IronSelectableBehavior`. - -- It is then necessary to replace the children `section` of our page selector with `neon-animatable` elements. You should proceed as follows for the contact section/page for example: - -```patch --
-+ - -

Contact

-

This is the contact section

- --
-+ -``` -Until now, all the pages of our web application were embedded in `section` tags under our page selector `iron-pages`. Replacing those `section` with the convenience element `neon-animatable` is now mandatory because all children of `neon-animated-pages` are required to implement `Polymer.NeonAnimatableBehavior` in order to be animated. - -## Fix the CSS - -- In `app/styles/app-theme.html`: - -```patch -- section[data-route="home"] paper-material { -+ neon-animatable[data-route="home"] paper-material { - @apply(--paper-font-body2); - } - -- section[data-route="home"] paper-material .subhead { -+ neon-animatable[data-route="home"] paper-material .subhead { - @apply(--paper-font-subhead); - } - -+ neon-animated-pages { -+ height: 100%; -+ } -+ - paper-material { - border-radius: 2px; -- height: 100%; - padding: 16px 0 16px 0; - width: calc(98.66% - 16px); - margin: 16px auto; - background: white; - } - -... - - /* Tablet+ */ - @media (min-width: 601px) { - - #drawer.paper-drawer-panel > [drawer] { - border-right: 1px solid rgba(0, 0, 0, 0.14); - } - -- iron-pages { -+ neon-animated-pages > * { - padding: 48px 62px; - } - -... -``` - -## Fix the focus management -- In `app/elements/routing.html`: -```patch - function setFocus(selected){ - Polymer.dom(document) -- .querySelector('section[data-route="' + selected +'"].focus-target') -+ .querySelector('neon-animatable[data-route="' + selected + '"] .focus-target') - .focus(); - } -``` - -## Going further - -This recipe took you through a basic integration of `neon-animated-pages` in Polymer Starter Kit with global and declarative transitions. -However, it doesn't stop there, as `neon-animated-pages` can enable your web application to: - -- Have page specific transitions -- Use multiple animations during one transition -- Only animate part of your page or a specific element -- Use complex animations such as cascaded animations or shared element animations (hero animation, ripple animation) - -Those features require you to extract every page of your web application in its own web-component. -Once that is done, we recommend you take a look at the following resources to learn how to make the most of the `neon-animated-pages` element: - -* [Using neon-animation](https://elements.polymer-project.org/guides/using-neon-animations) -* [Polycasts - Slick web animations](https://www.youtube.com/watch?v=Lwvi1u4XXzc) from Rob Dodson -* [Polycasts - Neon-animated-pages](https://www.youtube.com/watch?v=wMhq1o0DULM) from Rob Dodson diff --git a/docs/polymer-perf.md b/docs/polymer-perf.md deleted file mode 100644 index 0b2e8d1a7..000000000 --- a/docs/polymer-perf.md +++ /dev/null @@ -1,124 +0,0 @@ -### Polymer Performance Recipe - -In the following write up we are going to take a look at how to optimize the loading of Web Component enabled websites. The goal here is not to give you a copy and paste approach, but rather to give you the starting components and thought process with how to optimize your web app given your domain constraints. - -Current native support for Web Components is limited but growing, with only Chrome and Opera having a “fully" implemented spec. Due to the limited support, using Polymer or any web components in production across more than just Chrome requires you to load a polyfill. As with any polyfill there is a performance tradeoff, in the run time performance, spec compliance, as well as the network cost overhead. Lets dive into a few approaches that you can use to conditionally load the polyfill only when it is required. - -In your index.html file, create an HTML Import to load your elements bundle. If Web Components are supported, this element will start loading right away, otherwise it will begin loading as soon as the Web Components polyfills have been loaded and given a chance to scan the page. - -Note the use of the `async` attribute on the `link` element. This will ensure that loading the bundle does not block rendering in any way. Also note the `link` element has been given the `id` "bundle," this can be used later to listen for its load event. - -```html - -``` - -Next we need to detect if Web Components are supported by the browser. If it _does_ support them, then we can skip loading the polyfills entirely. Otherwise, we'll use JavaScript to asynchronously load the polyfills. - -Over in GitHub land @geenlen has cooked up a nifty bit of code to feature detect Web Components support - -```js -var webComponentsSupported = ('registerElement' in document - && 'import' in document.createElement('link') - && 'content' in document.createElement('template')); -``` - -```js -if (!webComponentsSupported) { - var script = document.createElement('script'); - script.onload = finishLazyLoading; - script.src = '/bower_components/webcomponentsjs/webcomponents-lite.min.js'; - document.head.appendChild(script); -} else { - finishLazyLoading(); -} -``` - -This bit of code can be placed directly in [`app.js`](https://github.com/PolymerElements/polymer-starter-kit/blob/master/app/scripts/app.js), right under the beginning of the IIFE. - -So what is going on here, how does it work? The first thing that this method does is dynamically create a script tag, then assigns a callback when the resource loads, the code then sets the src of the script tag, and then injects the script tag into the head of our document. Once the tag is placed inside of our document, the network request will start and when the resource is fully downloaded the callback will be invoked. - -Awesome! So now let’s move onto the logic around `finishLazyLoading`. - -```js -function finishLazyLoading() { - - var onImportLoaded = function() { - console.log('Elements are upgraded!'); - // Kickoff your app logic here! - }; - - var link = document.querySelector('#bundle'); - - if (link.import && link.import.readyState === 'complete') { - onImportLoaded(); - } else { - link.addEventListener('load', onImportLoaded); - } -} -``` - -`finishLazyLoading` checks to see if the import has finished loading and calls the `onImportLoaded` handler if it is. `onImportLoaded` is a good place to put your initial application logic because by this point you can be confident that all of your elements are ready. If the import hast not loaded, then we'll setup a listener for the load event of the `link` element and run `onImportLoaded` then. - -As an alternative to having the `link` tag for your imports already in the page, you could choose to load them dynamically. - -```js -function loadElements(pathToBundle, callback) { - var bundle = document.createElement('link'); - bundle.setAttribute('async', true); - bundle.rel = 'import'; - bundle.onload = callback; - bundle.href = pathToBundle; - - document.head.appendChild(bundle); -} -``` - -The `loadElements` function uses a similar approach to the one we used to load our polyfills. Note that the user should pass in a callback which will execute once the bundle has finished loading. - -For initial page load there is a slight performance tradeoff for going this route in browsers with Web Components support as it means the page must wait on JavaScript to execute before it can begin loading the elements. - -However, this approach does open up the possibility for you to only have users download the elements that they need for specific pages in your app, and can be extremely useful for subsequent page loads. Consider for instance an application with an admin panel and a general app view. Given the fact that most users in our made up app do not go to the admin panel too often, there is no need for them to always incur the cost of downloading the admin suite of elements. Instead we will only have users download the "bundle" that they need depending on what page they navigate to. - -For example with page.js your router could be structured as follows to optimize page load time, given a few assumptions about how users will be interacting with your app. - -```js -page.on('admin', function() { - loadElementBundle('elements/admin.html', renderAdminPane); -}); -``` - -#### Further Thoughts - -With Polymer, it is easy to fall into the trap of getting a flash of unstyled content, or a blank page while the polyfill and elements are downloading. The best way to avoid these pitfalls is to use a "loading" screen approach. The simplest of the loading approaches is to create a "splash" screen to display while your elements bundle is downloading. The splash screen can be anything from your logo on a colored background, to a full blown skeleton of what the page will look like once everything has loaded up. - -In your index.html, place the markup for your splashscreen in an element with an `id` of "splash". - -```html -
- -
-``` - -You can easily modify `onImportLoaded` to remove the splash screen once your bundle has loaded in. - -```js -var onImportLoaded = function() { - var splash = document.getElementById('splash'); - splash.remove(); - - console.log('Elements are upgraded!'); - // Kickoff your app logic here! -}; -``` - -Hopefully these approaches give you some ideas on how to make your app lightning fast. - -We hope to explore further ideas including [application shells](https://github.com/ebidel/polymer-experiments/blob/master/polymersummit/fouc/appshell.html) and being smart about your first meaningful paint in the near future. - --------- - -Further reading - -* [Fast Polymer app loading](https://gist.github.com/ebidel/1ba71473d687d0567bd3) from Eric Bidelman -* [Polymer Perf Patterns](https://www.youtube.com/watch?v=Yr84DpNaMfk) from Eric Bidelman -* [Polymer for the Performance-obsessed](https://aerotwist.com/blog/polymer-for-the-performance-obsessed/) from Paul Lewis