update readme

PolymerElements · Jul 17, 2018 · dd1a4f2 · dd1a4f2
1 parent 2f18992
commit dd1a4f2
Showing 1 changed file with 94 additions and 71 deletions.
diff --git a/README.md b/README.md
@@ -1,90 +1,113 @@
-
-<!---
-
-This README is automatically generated from the comments in these files:
-iron-localstorage.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
-
--->
-
+[![Published on NPM](https://img.shields.io/npm/v/@polymer/iron-localstorage.svg)](https://www.npmjs.com/package/@polymer/iron-localstorage)
 [![Build status](https://travis-ci.org/PolymerElements/iron-localstorage.svg?branch=master)](https://travis-ci.org/PolymerElements/iron-localstorage)
+[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://webcomponents.org/element/@polymer/iron-localstorage)
 
-_[Demo and API docs](https://elements.polymer-project.org/elements/iron-localstorage)_
-
-## Changes in 2.0
-* ⚠️ This element is now deprecated ⚠️
+⚠️ This element is deprecated ⚠️
 
 ## &lt;iron-localstorage&gt;
-
-Element access to Web Storage API (window.localStorage).
-
-Keeps `value` property in sync with localStorage.
+Element access to Web Storage API (window.localStorage) by keeping `value`
+property in sync with localStorage.
 
 Value is saved as json by default.
 
-### Usage:
+See: [Documentation](https://www.webcomponents.org/element/@polymer/iron-localstorage),
+  [Demo](https://www.webcomponents.org/element/@polymer/iron-localstorage/demo/demo/index.html).
 
-`ls-sample` will automatically save changes to its value.
+## Usage
 
-```html
-<dom-module id="ls-sample">
-  <iron-localstorage name="my-app-storage"
-    value="{{cartoon}}"
-    on-iron-localstorage-load-empty="initializeDefaultCartoon"
-  ></iron-localstorage>
-</dom-module>
-
-<script>
-  Polymer({
-    is: 'ls-sample',
-    properties: {
-      cartoon: {
-        type: Object
-      }
-    },
-    // initializes default if nothing has been stored
-    initializeDefaultCartoon: function() {
-      this.cartoon = {
-        name: "Mickey",
-        hasEars: true
-      }
-    },
-    // use path set api to propagate changes to localstorage
-    makeModifications: function() {
-      this.set('cartoon.name', "Minions");
-      this.set('cartoon.hasEars', false);
-    }
-  });
-</script>
+### Installation
+```
+npm install --save @polymer/iron-localstorage
 ```
 
-### Tech notes:
-
-* `value.*` is observed, and saved on modifications. You must use
-  path change notification methods such as `set()` to modify value
-  for changes to be observed.
-
-
-* Set `auto-save-disabled` to prevent automatic saving.
-
-
-* Value is saved as JSON by default.
+### In an html file
+```html
+<html>
+  <body>
+    <iron-localstorage name="my-app-storage"></iron-localstorage>
+
+    <script type="module">
+      import '@polymer/iron-localstorage/iron-localstorage.js';
+
+      const ls = document.querySelector('iron-localstorage');
+      // initializes default if nothing has been stored
+      function initializeDefaultCartoon() {
+        ls.value = {
+          name: "Mickey",
+          hasEars: true
+        };
+      }
 
+      ls.addEventListener(
+          'iron-local-storage-load-empty', initializeDefaultCartoon);
 
-* To delete a key, set value to null
+      // use path set api to propagate changes to localstorage
+      function makeModifications() {
+        ls.set('value.name', "Minions");
+        ls.set('value.hasEars', false);
+      }
+    </script>
+  </body>
+</html>
+```
 
+### In a Polymer 3 element
+```js
+import {PolymerElement, html} from '@polymer/polymer';
+import '@polymer/iron-localstorage/iron-localstorage.js';
+
+class SampleElement extends PolymerElement {
+  static get template() {
+    return html`
+      <iron-localstorage name="my-app-storage"
+          value="{{cartoon}}"
+          on-iron-localstorage-load-empty="initializeDefaultCartoon">
+      </iron-localstorage>
+    `;
+  }
+
+  static get properties() {
+    return {
+      cartoon: { type: Object },
+    }
+  }
 
+  // initializes default if nothing has been stored
+  initializeDefaultCartoon() {
+    this.cartoon = {
+      name: "Mickey",
+      hasEars: true
+    }
+  }
+
+  // use path set api to propagate changes to localstorage
+  makeModifications() {
+    this.set('cartoon.name', "Minions");
+    this.set('cartoon.hasEars', false);
+  }
+}
+customElements.define('sample-element', SampleElement);
+```
 
-Element listens to StorageAPI `storage` event, and will reload upon receiving it.
+## Contributing
+If you want to send a PR to this element, here are
+the instructions for running the tests and demo locally:
 
-__Warning__: do not bind value to sub-properties until Polymer
-[bug 1550](https://github.com/Polymer/polymer/issues/1550)
-is resolved. Local storage will be blown away.
-`<iron-localstorage value="{{foo.bar}}"` will cause __data loss__.
+### Installation
+```sh
+git clone https://github.com/PolymerElements/iron-localstorage
+cd iron-localstorage
+npm install
+npm install -g polymer-cli
+```
 
+### Running the demo locally
+```sh
+polymer serve --npm
+open http://127.0.0.1:<port>/demo/
+```
 
+### Running the tests
+```sh
+polymer test --npm
+```