https://wpt.fyi/node_modules/@polymer/app-route/app-location.js

1/**
2@license
3Copyright (c) 2016 The Polymer Project Authors. All rights reserved.
4This code may only be used under the BSD style license found at
5http://polymer.github.io/LICENSE.txt The complete set of authors may be found at
6http://polymer.github.io/AUTHORS.txt The complete set of contributors may be
7found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by Google as
8part of the polymer project is also subject to an additional IP rights grant
9found at http://polymer.github.io/PATENTS.txt
10*/
11import '/node_modules/@polymer/polymer/polymer-legacy.js';
12import '/node_modules/@polymer/iron-location/iron-location.js';
13import '/node_modules/@polymer/iron-location/iron-query-params.js';
14
15import {Polymer} from '/node_modules/@polymer/polymer/lib/legacy/polymer-fn.js';
16import {html} from '/node_modules/@polymer/polymer/lib/utils/html-tag.js';
17
18import {AppRouteConverterBehavior} from './app-route-converter-behavior.js';
19
20/**
21`app-location` is an element that provides synchronization between the
22browser location bar and the state of an app. When created, `app-location`
23elements will automatically watch the global location for changes. As changes
24occur, `app-location` produces and updates an object called `route`. This
25`route` object is suitable for passing into a `app-route`, and other similar
26elements.
27
28An example of the public API of a route object that describes the URL
29`https://elements.polymer-project.org/elements/app-location`:
30
31    {
32      prefix: '',
33      path: '/elements/app-location'
34    }
35
36Example Usage:
37
38    <app-location route="{{route}}"></app-location>
39    <app-route route="{{route}}" pattern="/:page" data="{{data}}"></app-route>
40
41As you can see above, the `app-location` element produces a `route` and that
42property is then bound into the `app-route` element. The bindings are two-
43directional, so when changes to the `route` object occur within `app-route`,
44they automatically reflect back to the global location.
45
46### Hashes vs Paths
47
48By default `app-location` routes using the pathname portion of the URL. This has
49broad browser support but it does require cooperation of the backend server. An
50`app-location` can be configured to use the hash part of a URL instead using
51the `use-hash-as-path` attribute, like so:
52
53    <app-location route="{{route}}" use-hash-as-path></app-location>
54
55### Integrating with other routing code
56
57There is no standard event that is fired when window.location is modified.
58`app-location` fires a `location-changed` event on `window` when it updates the
59location. It also listens for that same event, and re-reads the URL when it's
60fired. This makes it very easy to interop with other routing code.
61
62So for example if you want to navigate to `/new_path` imperatively you could
63call `window.location.pushState` or `window.location.replaceState` followed by
64firing a `location-changed` event on `window`. i.e.
65
66    window.history.pushState({}, null, '/new_path');
67    window.dispatchEvent(new CustomEvent('location-changed'));
68
69@element app-location
70@demo demo/index.html
71*/
72Polymer({
73  _template: html`
74    <iron-query-params params-string="{{__query}}" params-object="{{queryParams}}">
75    </iron-query-params>
76    <iron-location path="{{__path}}" query="{{__query}}" hash="{{__hash}}" url-space-regex="[[urlSpaceRegex]]" dwell-time="[[dwellTime]]">
77    </iron-location>
78  `,
79
80  is: 'app-location',
81
82  properties: {
83    /**
84     * A model representing the deserialized path through the route tree, as
85     * well as the current queryParams.
86     */
87    route: {
88      type: Object,
89      notify: true,
90    },
91
92    /**
93     * In many scenarios, it is convenient to treat the `hash` as a stand-in
94     * alternative to the `path`. For example, if deploying an app to a static
95     * web server (e.g., Github Pages) - where one does not have control over
96     * server-side routing - it is usually a better experience to use the hash
97     * to represent paths through one's app.
98     *
99     * When this property is set to true, the `hash` will be used in place of
100
101     * the `path` for generating a `route`.
102     */
103    useHashAsPath: {
104      type: Boolean,
105      value: false,
106    },
107
108    /**
109     * A regexp that defines the set of URLs that should be considered part
110     * of this web app.
111     *
112     * Clicking on a link that matches this regex won't result in a full page
113     * navigation, but will instead just update the URL state in place.
114     *

115     * This regexp is given everything after the origin in an absolute
116     * URL. So to match just URLs that start with /search/ do:
117     *     url-space-regex="^/search/"
118     *
119     * @type {string|RegExp}
120     */
121    urlSpaceRegex: {
122      type: String,
123      notify: true,
124    },
125
126    /**
127     * A set of key/value pairs that are universally accessible to branches
128     * of the route tree.
129     */
130    __queryParams: {
131      type: Object,
132    },
133
134    /**
135     * The pathname component of the current URL.
136     */
137    __path: {
138      type: String,
139    },
140
141    /**
142     * The query string portion of the current URL.
143     */
144    __query: {
145      type: String,
146    },
147
148    /**
149     * The hash portion of the current URL.
150     */
151    __hash: {
152      type: String,
153    },
154
155    /**
156     * The route path, which will be either the hash or the path, depending
157     * on useHashAsPath.
158     */
159    path: {
160      type: String,
161      observer: '__onPathChanged',
162    },
163
164    /**
165     * Whether or not the ready function has been called.
166     */
167    _isReady: {
168      type: Boolean,
169    },
170
171    /**
172     * If the user was on a URL for less than `dwellTime` milliseconds, it
173     * won't be added to the browser's history, but instead will be
174     * replaced by the next entry.
175     *
176     * This is to prevent large numbers of entries from clogging up the
177     * user's browser history. Disable by setting to a negative number.
178     *
179     * See `iron-location` for more information.
180     */
181    dwellTime: {
182      type: Number,
183    }
184  },
185
186  behaviors: [AppRouteConverterBehavior],
187  observers: ['__computeRoutePath(useHashAsPath, __hash, __path)'],
188
189  ready: function() {
190    this._isReady = true;
191  },
192
193  __computeRoutePath: function() {
194    this.path = this.useHashAsPath ? this.__hash : this.__path;
195  },
196
197  __onPathChanged: function() {
198    if (!this._isReady) {
199      return;
200    }
201
202    if (this.useHashAsPath) {
203      this.__hash = this.path;
204    } else {
205      this.__path = this.path;
206    }
207  }
208});