Skip to content

getting-started.md

Latest commit

 

History

History
161 lines (105 loc) · 6.53 KB

getting-started.md

File metadata and controls

161 lines (105 loc) · 6.53 KB
layout default
title Getting started
components
<script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fpolymer%2Fpolymer.min.js%3F%7B%7B"now' | date: "%Y%m%d"}}"></script>

{% comment %} {% include outofdate.html %} {% endcomment %}

Basics

The basics of using {{site.project_title}} are simple:

  1. Load platform.js to polyfill missing platform features, such as Shadow DOM and HTML Imports.
  2. Load components with <link rel="import" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fpath%2Fto%2Fcomponent-file.html">
  3. Use the custom element in your page.

Here's a bare bones example:

<!DOCTYPE html>
<html>
  <head>
    <!-- 1. Shim missing platform features -->
    <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fpolymer%2Fplatform%2Fplatform.js"></script>
    <!-- 2. Load a component -->
    <link rel="import" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Ftoolkit-ui%2Felements%2Fg-menu-item.html">
  </head>
  <body>
    <!-- 3. Instantiate the component with its tag. -->
    <g-menu-item src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fimages%2Femail.svg">Email Link</g-menu-item>
  </body>
</html>

Note: You must always run your app from a web server. This is for the HTML Imports polyfill will work properly. This requirement will go away when the API is available natively in browsers.

Components

Custom Elements are the core building blocks of {{site.project_title}}-based applications. You create applications by assembling custom elements together, either ones provided by {{site.project_title}} or that you create yourself.

Creating a basic component

The platform polyfills provided by {{site.project_title}} let you load and display custom elements. Just by loading platform.js you get support for these new technologies.

{% include samples/basic-element.html %}

Creating a {{site.project_title}} element

{{site.project_title}} provides extra goodies for creating custom elements. We call these souped-up custom elements "{{site.project_title}} elements". To create one, follow these steps:

  1. Load {{site.project_title}} core (polymer/polymer.js or polymer/polymer.min.js).

    Note: polymer.js loads platform.js under the hood. You only need to include polymer.js when writing a {{site.project_title}} element. {: .alert }

  2. In your custom element, add a <script> element that calls the {{site.project_title}}.register(). This endows the custom element with {{site.project_title}} features, such as data binding and event mapping.

In the following sample we convert our basic custom element into a {{site.project_title}} element named tk-element.

{% include samples/tk-element.html %}

{{site.project_title}}.register() takes the element it needs to register as its first argument. In the context of <element>, this refers to the element.

{% comment %}

Add properties to our component

The {{site.project_title}}.register() takes an object as a parameter whose members define the properties and methods that belong to our component.

{% include samples/tk-element-property.html %}

Now that we've added a private variable, let's add data binding to display its value in the DOM. {% endcomment %}

Declarative data binding

You can bind properties in your component using declarative data binding and the "double-mustache" syntax ({%raw%}{{}}{%endraw%}) from Model Driven Views. The {%raw%}{{}}{%endraw%} is replaced by the value of the property referenced between the brackets.

{% include samples/tk-element-databinding.html %}

Binding to markup

You can use binding expressions in most HTML markup, except for tag names themselves. In the following example, we create a new property on our component named color whose value is bound to the value of the color style applied to the custom element.

{% include samples/tk-element-databinding-color.html %}

Binding between components and native elements

The following example demonstrates binding component properties to attributes of native input elements.

{% include samples/tk-binding-to-elements.html %}

Adding a ready() lifecycle method

When a component has finished initializing itself, it calls its ready method, if it exists.

{% include samples/tk-element-ready.html %}

Publishing properties

By default, properties you declare are not accessible via attribute. You can publish a property by listing it in the attributes attribute on the <element> tag. Published properties can be initialized using attributes on the node, and can be data-bound using attributes on the node.

A property declared in the attributes attribute is initially set to null. You can provide a more appropriate default value by also including the property directly in your prototype, as usual.

Using the "attributes" attribute

The following example defines an attributes attribute on the custom element whose value is the string "owner color".

{% include samples/tk-element-property-public.html %}

{% comment %}

Using a publish object (advanced)

There is another way to publish a property (but you probably will never need it): the publish object. Properties included in an object named publish are published just like properties named in attributes.

{% include samples/tk-element-property-public-publish.html %}

Change watching

Accessing public properties on an element

A element's published properties can be set using attributes on its custom element, as shown in index.html below.

{% include samples/tk-element-public-access.html %}
{% endcomment %}

Automatic node finding

Shadow DOM is a self-contained document-like subtree; id's in that subtree do not interact with id's in other trees. Each {{site.project_title}} element generates a map of id's to node references in the element's template. This map is accessible as $ on the element.

{% include samples/tk-node-finding.html %}