Polymer: importHref() could use better docs

[justinfagnani]

See https://www.polymer-project.org/2.0/docs/api/#function-Polymer.importHref

Current docs:

Polymer.importHref(href: string, onload: Function=, onerror: Function=, optAsync: boolean=): HTMLLinkElement

Convenience method for importing an HTML document imperatively.

This method creates a new element with the provided URL and appends it to the document to start loading. In the onload callback, the import property of the link element will contain the imported document contents.

The signature of the callbacks isn't specified, so the phrase "In the onload callback, the import property of the link element" doesn't make a lot of sense. What link element?

Also, the docs don't specify what happens if I load a URL twice - does it always create a new link element (and thus always fire a new load or error event), or does it reuse existing link elements? ie, should a caller remember if it already imported a URL?

[JamesCoyle]

I'd like to know the behavior on loading an existing resource too. Will it load the resource again and duplicate the link element, will it realize it exists and just run the callback function, or will it detect it exists and not run the callback function? From my testing so far it seems to include the link only once but it also always calls the error function if it exists or not.

A lot of the polymer 2.0 still seems to be somewhat lacking in detail and a lot of things have been bunched into the Upgrade Guide rather than having separate sections like they did in the 1.0 docs. It seems like it assumes you are already familiar with Polymer 1.0 which not everyone is.

[paulcuth]

The docs also do not mention that in Polymer 2 we need to explicitly import this function for it to be available on the Polymer object. I had to read the code to discover that.

<link rel="import" href="/bower_components/polymer/lib/utils/import-href.html">

[hariprasadiit]

@paulcuth thanks for info

<link rel="import" href="/bower_components/polymer/lib/utils/import-href.html"> couldn't find this anywhere. Polymer docs should mention about this.

[xelra]

I've been trying to make sense of the behavior of ImportHref() for more than a day. The documentation is so sparse and I simply don't understand what the exact conditions are for onerror to be called.

I've written a small element that checks auth and is supposed to lazy-load elements using ImportHref(). The code works, but every time authenticated changes, it triggers the console log message from onerror. And it does that despite importHref clearly importing successfully.

Does anyone know why?

<!-- my-check.html -->

<link rel="import" href="../bower_components/polymer/polymer-element.html">
<link rel="import" href="../bower_components/polymer/lib/utils/import-href.html">

<link rel="lazy-import" href="my-app.html">
<link rel="lazy-import" href="my-login.html">

<dom-module id="my-check">
    <template>
        <style>
            :host {
                display: block;
                height: 100%;
            }
        </style>

        <dom-if if="[[!authenticated]]" restamp>
            <template>
                <my-login></my-login>
            </template>
        </dom-if>

        <dom-if if="[[authenticated]]" restamp>
            <template>
                <my-app></my-app>
            </template>
        </dom-if>
    </template>

    <script>
        class MyCheck extends Polymer.Element {
            static get is() { return 'my-check'; }

            static get properties() {
                return {
                    authenticated: {
                        type: Boolean,
                        value: false,
                        observer: '_authChanged',
                    },
                }
            }

            _authChanged(authenticated) {
                if (authenticated) {
                    var page = "app";
                } else {
                    var page = "login";
                }

                var resolvedPageUrl = this.resolveUrl('my-' + page + '.html');
                Polymer.importHref(
                    resolvedPageUrl,
                    null,
                    console.log("There was a problem instantiating " + resolvedPageUrl),
                    true);
            }
        }

        window.customElements.define(MyCheck.is, MyCheck);
    </script>
</dom-module>

[TimvdLippe]

@xelra I think you need to wrap it in a lambda:

Polymer.importHref(
  resolvedPageUrl,
  null,
  () ->{ console.log("There was a problem instantiating " + resolvedPageUrl) },
  true
);

[xelra]

@TimvdLippe Thank you. That worked.

Please add that in some form to the docs. Maybe I'm supposed to know stuff like this, but for a hobbyist, things like this are walls that are almost impossible to overcome without guidance.

And just for the next person reading this, the code above has a -> instead of =>.

[justinfagnani]

@xelra onerror is documented as a Function, so hopefully that part indicates well enough that _some_ kind of function needs to be passed. What prompted me to file was that the signature of that function - what arguments are passed to it - are unspecified.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.