README.md

Demo and API docs

Changes in 2.0

• Promise polyfill is now a dev dependency and no longer shipped with iron-ajax.

  iron-ajax uses the Promise API, which is not yet supported in all browsers.

  The 1.x version of iron-ajax automatically loaded the promise polyfill. This forced the application to include the polyfill, whether or not it was needed.

  When using iron-ajax 2.x with Polymer 1.x, you must provide your own Promise polyfill, if needed. For example, you could use the promise polyfill by installing it in your project:

  bower install --save PolymerLabs/promise-polyfill#1 - 2
  

  Then your app should include the promise polyfill before loading iron-ajax:

  <link rel="import" href="bower_components/promise-polyfill/promise-polyfill-lite.html">
  

  You can use a different promise polyfill if you need a more fully-featured implementation of Promise.

  For Polymer 2.x, you do not need to provide your own Promise polyfill if you are using the web components polyfills. Because the web components v1 APIs depend on Promise, a promise polyfill is loaded when needed by the v1 polyfills (web-components-lite.js or webcomponents-loader.js).

• New optional error information.

  The generateRequest method returns an iron-request element representing the request, and the request element provides a completes property, which is a promise that completes when the request either succeeds or fails.

  This version includes a new flag, rejectWithRequest, that modifies the error handling of the completes promise. By default, when the promise is rejected (because the request failed), the rejection callback only receives an Error object describing the failure.

  With rejectWithRequest set to true, the callback receives an object with two keys, error, the error message, and request, the original request that the error is related to:

  let request = ironAjaxElement.generateRequest();
  request.completes.then(function(req) {
      // succesful request, argument is iron-request element
      ...
    }, function(rejected) {
      // failed request, argument is an object
      let req = rejected.request;
      let error = rejected.error;
      ...
    }
  )
  

  Because this change could break existing code, rejectWithRequest is false by default, however, in the next major release, this option will be removed and the new behavior made the default.

<iron-ajax>

The iron-ajax element exposes network request functionality.

<iron-ajax
    auto
    url="https://www.googleapis.com/youtube/v3/search"
    params='{"part":"snippet", "q":"polymer", "key": "YOUTUBE_API_KEY", "type": "video"}'
    handle-as="json"
    on-response="handleResponse"
    debounce-duration="300"></iron-ajax>

With auto set to true, the element performs a request whenever its url, params or body properties are changed. Automatically generated requests will be debounced in the case that multiple attributes are changed sequentially.

Note: The params attribute must be double quoted JSON.

You can trigger a request explicitly by calling generateRequest on the element.

<iron-request>

iron-request can be used to perform XMLHttpRequests.

<iron-request id="xhr"></iron-request>
...
this.$.xhr.send({url: url, body: params});