Skip to content

getting-the-code.md

Latest commit

 

History

History
220 lines (137 loc) · 7.8 KB

getting-the-code.md

File metadata and controls

220 lines (137 loc) · 7.8 KB
layout default
title Getting the code

{% include toc.html %}

Setup & installation {#intall}

Using Bower {#installing-polymer}

The recommended way to get the pieces of {{site.project_title}} {{site.latest_version}} is through Bower. We've chosen Bower because removes the hassle of dependency management when developing or consuming elements.

Getting the packages

Everything is à la carte in {{site.project_title}}, so get the parts you're interested in. After running one of these commands, Bower creates a bower_components/ directory and populates it with the packages (and their dependencies) as siblings folders.

Tip: --save adds the item as dependencies in your app's bower.json. {: .alert .alert-success }

  • Install and use the {{site.project_title}} elements:

      bower install --save Polymer/polymer-elements
  bower install --save Polymer/polymer-ui-elements

    Note: installing a set of elements also installs the Polymer/platform and Polymer/polymer dependencies. You do not need to run the other install commands.

  • To build {{site.project_title}} elements, install the core sugaring:

      bower install --save Polymer/polymer

    Note: this also gets you Polymer/platform.

  • Only interested in the polyfill libraries? Install them standalone:

      bower install --save Polymer/platform

Test your environment {#testbower}

In the folder where you ran bower install, create an index.html that loads platform.js and imports the <polymer-ui-tabs> element:

<!DOCTYPE html>
<html>
  <head>
    <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fbower_components%2Fplatform%2Fplatform.js"></script>
    <link rel="import"
          href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fbower_components%2Fpolymer-ui-tabs%2Fpolymer-ui-tabs.html">
  </head>
  <body>
    <polymer-ui-tabs selected="0">
      <span>One</span><span>Two</span><span>Three</span><span>Four</span><span>Five</span>
    </polymer-ui-tabs>
  </body>
</html>

Fire up a web server, navigate to index.html, and feast on your accomplishments. You should see a tabs component like the one below.

<iframe src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fcomponents%2Fpolymer-ui-tabs%2Fsmoke.html" style="border:none;height:80px;width:100%;"></iframe>

Updating packages {#updatebower}

When a new version of {{site.project_title}} is available, run bower update in your app directory to update your copy:

bower update

This updates all packages in bower_components/.

Using a CDN {#cdn}

{{site.project_title}} is maintained on cdnjs and can be loaded from the following URLs:

<script src="proxy.php?url=https%3A%2F%2Fcdnjs.cloudflare.com%2Fajax%2Flibs%2Fpolymer%2F%7B%7Bsite.latest_version%7D%7D%2Fplatform.js"></script>
<script src="proxy.php?url=https%3A%2F%2Fcdnjs.cloudflare.com%2Fajax%2Flibs%2Fpolymer%2F%7B%7Bsite.latest_version%7D%7D%2Fpolymer.js"></script>

Using git {#git}

As an alternative to Bower, you can clone {{site.project_title}}'s important repositories by running our pull-all.sh script:

mkdir polymer_local; cd polymer_local
git clone https://github.com/Polymer/tools.git
./tools/bin/pull-all.sh

Go grab a coffee. This takes a few minutes!

pull-all.sh is great for hacking on the code or if you want the individual polyfill repositories. Running this script sets things up differently than Bower. It creates two directories, components/ and projects/, and checks out a number of sibling repositories to each folder.

components/

  • components/platform/platform.js — The platform shims and polyfills.
  • components/polymer/polymer.js — {{site.project_title}} core
  • components/polymer-elements/ — A folder of the meta collection of the core utility elements.
  • components/polymer-ui-elements/ — A folder of the meta collection of the UI elements.
  • A directory for each polyfill repo (CustomElements, HTMLImports, ShadowDOM).

projects/

Full and sample applications.

Test your environment {#testgit}

To check that your development environment is ready, try trying the playground tool:

cd projects/designer
bower install

Start a web server and navigate to the designer app.

Updating checkouts {#updategit}

To update your local copies, re-run pull-all.sh:

./tools/bin/pull-all.sh

About the repositories {#abouttherepos}

Note: This section should be used for reference purposes only. We recommend using Bower to install and work with {{site.project_title}}. {: .alert }

The entirety of the {{site.project_title}} is composed of a many Git repositories. All of the polyfill libraries, projects, and individual elements each have their own repository.

Specification repositories (da polyfills)

Each new web platform specification has a corresponding polyfill repository. The reasoning for this is two-fold:

  1. make the polyfills work across all modern browsers
  2. each polyfill can stand on its own and be used à la carte in projects.

For example, the following repositories may be useful if you're interested in the individual API:

  • CustomElements
  • HTMLImports
  • PointerEvents
  • PointerGestures
  • ShadowDOM
  • web-animations-js

Other useful repositories

/polymer

github.com/polymer/polymer

A meta repository used to distribute polymer.js builds.

/polymer-dev

github.com/polymer/polymer-dev

The polymer-dev repository contains the {{site.project_title}} core and its tools and tests and is used by the project's developers. You should not have to touch this repository unless you're planning to hack on {{site.project_title}}.

/platform

github.com/polymer/platform

A meta repository used to distribute platform.js builds.

/platform-dev

github.com/polymer/platform-dev

The platform-dev contains integration tests, loader, and build tools for the amalgamated polyfills. It's used by the project's developers. You should not have to touch this repository unless you're planning to hack on {{site.project_title}}.

/polymer-elements

github.com/polymer/polymer-elements

A meta repository compiling the list of utility elements that do not render UI.

/polymer-ui-elements

github.com/polymer/polymer-ui-elements

A meta repository compiling the list of basic UI elements.

/more-elements

github.com/polymer/more-elements

A meta repository compiling the list of extra components and wrappers for third-party code. Examples include Bootstrap, topcoat, Chart.js, pdf.js, x-tags, and AceEditor.