Merge pull request #109 from florian-h05/fix-createitem-metadata

Items: Fix createItem does not set metadata & further improvement

README.md

@@ -64,6 +64,7 @@ This will be used instead of the binding provided version.
 
 ### Breaking Changes
 - item.history.lastUpdate() returns `ZonedDateTime` instead of `Date`
+- `addItem(...)` and `updateItem(...)` use [`itemConfig`](#itemconfig) as parameter
 
 ## UI Based Rules
 
@@ -242,10 +243,9 @@ See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for fu
     * .getItem(name, nullIfMissing) ⇒ <code>Item</code>
     * .getItems() ⇒ <code>Array.&lt;Item&gt;</code>
     * .getItemsByTag(...tagNames) ⇒ <code>Array.&lt;Item&gt;</code>
-    * .createItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction], [itemMetadata])
-    * .addItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction])
+    * .addItem([itemConfig](#itemconfig))
     * .removeItem(itemOrItemName) ⇒ <code>Boolean</code>
-    * .replaceItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction])
+    * .replaceItem([itemConfig](#itemconfig))
     * .safeItemName(s) ⇒ <code>String</code>
 
 ```javascript
@@ -289,7 +289,56 @@ item.postUpdate("OFF");
 console.log("KitchenLight state", item.state)
 ```
 
-calling `item.history...` returns a ItemHistory object with the following functions:
+#### `itemConfig`
+Calling `addItem(itemConfig)` or `replaceItem(itemConfig)` requires the `itemConfig` object with the following properties:
+
+* itemConfig : <code>object</code>
+    * .type ⇒ <code>String</code>
+    * .name ⇒ <code>String</code>
+    * .label ⇒ <code>String</code>
+    * .category (icon) ⇒ <code>String</code>
+    * .groups ⇒ <code>Array.&lt;String&gt;</code>
+    * .tags ⇒ <code>Array.&lt;String&gt;</code>
+    * .channels ⇒ <code>String|Object { channeluid: { config } }</code>
+    * .metadata ⇒ <code>Object { namespace: value }|Object { namespace: { value: value , config: { config } } }</code>
+    * .giBaseType ⇒ <code>String</code>
+    * .groupFunction ⇒ <code>String</code>
+
+Note: `.type` and `.name` are required.
+
+Example:
+```javascript
+items.replaceItem({
+  type: 'Switch',
+  name: 'Hallway_Light',
+  label: 'Hallway Light',
+  category: 'light',
+  groups: ['Hallway', 'Light'],
+  tags: ['Lightbulb'],
+  channels: {
+    'binding:thing:device:hallway#light': {},
+    'binding:thing:device:livingroom#light': { 
+      profile: 'system:follow' 
+    }
+  },
+  metadata: {
+    expire: '10m,command=OFF',
+    stateDescription: {
+      config: {
+        pattern: '%d%%',
+        min: 0,
+        max: 100,
+        step: 1,
+        options: '1=Red, 2=Green, 3=Blue'
+      }
+    }
+  }
+});
+```
+
+See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for full API documentation.
+#### `item.history`
+Calling `item.history` returns a ItemHistory object with the following functions:
 
 Note `serviceId` is optional, if omitted, the default persistance service will be used.