Skip to content

usingelements.md

Latest commit

 

History

History
111 lines (78 loc) · 5.08 KB

usingelements.md

File metadata and controls

111 lines (78 loc) · 5.08 KB
layout default
type start
navgroup start
shortname Start
title Using elements
subtitle Polymer from the outside

{% include toc.html %}

{{site.project_title}} provides several sets of elements, which you can reuse simply by including them in your project. If you don't want to write any code, keep reading!

Installing elements {#install}

You can install elements one at a time, or install a whole collection of elements.

{{site.project_title}} contains two primary collections of elements:

If you find an element you want while browsing the docs, simply click the download button and choose your install method. See Getting the Code for more information on the various methods.

Click a button below to install one of the element collections:

Note: The PolymerLabs github repo contains a number of unsupported elements that are either experimental or deprecated. In particular, the polymer-elements and polymer-ui-elements collections represent earlier work superseded by the {{site.project_title}} Core elements and Paper elements.

Using elements {#using}

To use elements, first load platform.js. Many browsers have yet to implement the various web components APIs. Until they do, platform.js provides polyfill support. Be sure to include this file before any code that touches the DOM.

Once you have some elements installed and you've loaded platform.js, using an element is simply a matter of loading the element file using an HTML Import.

An example index.html file:

<!DOCTYPE html>
<html>
  <head>
    <!-- 1. Load platform.js for polyfill support. -->
    <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fbower_components%2Fplatform%2Fplatform.js"></script>

    <!-- 2. Use an HTML Import to bring in the element. -->
    <link rel="import"
          href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fbower_components%2Fcore-ajax%2Fcore-ajax.html">
  </head>
  <body>
    <!-- 3. Declare the element. Configure using its attributes. -->
    <core-ajax url="//example.com/json"
               handleAs="json"></core-ajax>

    <script>
      // Wait for 'polymer-ready'. Ensures the element is upgraded.
      window.addEventListener('polymer-ready', function(e) {
        var ajax = document.querySelector('core-ajax');

        // Respond to events it fires.
        ajax.addEventListener('core-response', function(e) {
          console.log(this.response);
        });

        ajax.go(); // Call its API methods.
      });
    </script>
  </body>
</html>

Note: You must run your app from a web server for the HTML Imports polyfill to work properly. This requirement goes away when the API is available natively. {: .alert .alert-info }

Passing object and array values in attributes {#objectarray}

HTML attributes are string values, but sometimes you need to pass more complicated values into a custom element, such as objects or arrays. Ultimately, it's up to the element author to decide how to decode values passed in as attributes, but many {{site.project_title}} elements understand attribute values that are a JSON-serialized object or array. For example:

<roster-list persons='[{"name": "John"}, {"name": "Bob"}]'></roster-list>

For {{site.project_title}} elements, you can find the expected type for each attribute listed in the Elements reference. If you pass the wrong type, it may be decoded incorrectly.

When creating your own {{site.project_title}} elements, you can choose to expose properties as attributes, as described in Published properties.

Next steps {#nextsteps}

Now that you've got the basic idea of using and installing elements, it's time to start building something! In the next section we'll cover the features of {{site.project_title}} and how to create new <polymer-element>s. Continue on to:

Creating elements

If you'd rather browse the existing elements, check out the {{site.project_title}} Core elements and Paper elements catalogs.