iron-lazy-pages.js

/**
@license
Copyright (C) 2016, Tim van der Lippe
All rights reserved.

This software may be modified and distributed under the terms
of the BSD license.  See the LICENSE file for details.
*/
import '@polymer/polymer/polymer-legacy.js';

import { IronLazyPagesBehavior } from './iron-lazy-pages-behavior.js';
import { Polymer } from '@polymer/polymer/lib/legacy/polymer-fn.js';
import { html } from '@polymer/polymer/lib/utils/html-tag.js';

/**
Big applications have a lot of pages. On first load, loading all page elements
is undesirable. Most of the pages are unused for the current user. To solve
these performance issues, lazy-loading provides an easy-to-use solution.

Lazy-loading means that all elements of your page are loaded when the user
opens the respective page. E.g. when your user visits `domain.com/about`, all
elements on the about page are fetched and loaded.

Example:

```html
<iron-lazy-pages attr-for-selected="data-route" selected="{{route}}">
  <x-foo data-route="foo" data-path="demo/x-foo.html"></x-foo>
  <x-bar data-route="bar" data-path="demo/x-bar.html"></x-bar>
  <section data-route="baz">
    Inline element baz.
  </section>
</iron-lazy-pages>
```

In the above example, whenever the user routes to `domain.com/foo`, the elements defined
in `foo/foo.html` are fetched from the server and loaded by Polymer.

Consequently whenever the selected value changes from `foo` to `bar`, the page `foo`
will be hidden.

Fetching is only performed once, e.g. switching from `foo` to `bar` to `foo` will fetch
`foo` once and show `foo` twice.

## `<dom-if>` support

You can also add `<dom-if>` as a route to enable restamping:

```html
<iron-lazy-pages
    attr-for-selected="data-route"
    selected="{{route}}"
    loading="{{loading}}"
    hide-immediately>
  <template is="dom-if" data-route="foo" restamp>
    Leaving this tab and coming back will loose input value due to restamp<br/>
    <input type="text"/>
  </template>
  <template is="dom-if" data-route="bar">
    Leaving this tab and coming back will keep input value<br/>
    <input type="text"/>
  </template>
</iron-lazy-pages>
```

@group Iron Elements
@element iron-lazy-pages
@demo demo/index.html
*/
Polymer({
  _template: html`
    <style>
      :host {
        display: block;
      }
      :host > ::slotted(:not(.iron-lazy-selected)) {
        display: none !important;
      }
    </style>

    <slot></slot>
`,

  is: 'iron-lazy-pages',

  behaviors: [
    IronLazyPagesBehavior
  ]
});