diff options
Diffstat (limited to 'catapult/third_party/polymer/components/iron-ajax/README.md')
| -rw-r--r-- | catapult/third_party/polymer/components/iron-ajax/README.md | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/catapult/third_party/polymer/components/iron-ajax/README.md b/catapult/third_party/polymer/components/iron-ajax/README.md new file mode 100644 index 00000000..7a1a3697 --- /dev/null +++ b/catapult/third_party/polymer/components/iron-ajax/README.md @@ -0,0 +1,111 @@ + +<!--- + +This README is automatically generated from the comments in these files: +iron-ajax.html iron-request.html + +Edit those files, and our readme bot will duplicate them over here! +Edit this file, and the bot will squash your changes :) + +The bot does some handling of markdown. Please file a bug if it does the wrong +thing! https://github.com/PolymerLabs/tedium/issues + +--> + +[](https://travis-ci.org/PolymerElements/iron-ajax) + +_[Demo and API docs](https://elements.polymer-project.org/elements/iron-ajax)_ + +## 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. + +```html +<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. + +```html +<iron-request id="xhr"></iron-request> +... +this.$.xhr.send({url: url, body: params}); +``` + + |