items
- Description:
Items namespace. This namespace handles querying and updating openHAB Items.
- Source:
Classes
Namespaces
Members
(static, constant) DYNAMIC_ITEM_TAG
- Description:
Tag value to be attached to all dynamically created Items.
- Source:
Tag value to be attached to all dynamically created Items.
Methods
(static) NAME() → {Item|null}
- Description:
Gets an openHAB Item by name directly on the
items
namespace. Equivalent toitems.getItem
- Source:
Example
// retrieve item by name directly on the items namespace
console.log(items.KitchenLight.state) // returns 'ON'
// equivalent to
console.log(items.getItem('KitchenLight').state) // returns 'ON'
Returns:
items.Item
Item or null
if Item is missing
- Type
- Item | null
(static) addItem(itemConfig, persistopt) → {Item}
- Description:
Creates a new Item.
If this is called from file-based scripts, the Item is registered with the ScriptedItemProvider and shares the same lifecycle as the script. You can still persist the Item permanently in this case by setting the
persist
parameter totrue
. If this is called from UI-based scripts, the Item is stored to the ManagedItemProvider and independent of the script's lifecycle.Note that all Items created this way have an additional tag attached for simpler retrieval later. This tag is created with the value
DYNAMIC_ITEM_TAG
.
- Source:
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
itemConfig |
ItemConfig | the Item config describing the Item |
||
persist |
boolean |
<optional> |
false
|
whether to persist the Item permanently (only respected for file-based scripts) |
Throws:
-
-
if
ItemConfig
is invalid, e.g.ItemConfig
.name orItemConfig
.type is not set - Type
- Error
-
-
-
if an Item with the same name already exists
- Type
- Error
-
Returns:
Item
- Type
- Item
(static) existsItem(name) → {boolean}
- Description:
Whether an Item with the given name exists.
- Source:
Parameters:
Name | Type | Description |
---|---|---|
name |
string | the name of the Item |
Returns:
whether the Item exists
- Type
- boolean
(static) getItem(name, nullIfMissingopt) → {Item}
- Description:
Gets an openHAB Item.
- Source:
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
name |
string | the name of the Item |
||
nullIfMissing |
boolean |
<optional> |
false
|
whether to return null if the Item cannot be found (default is to throw an ItemNotFoundException) |
Returns:
items.Item
Item or null
if nullIfMissing
is true and Item is missing
- Type
- Item
(static) getItems() → {Array:.<Item:>}
- Description:
Gets all openHAB Items.
- Source:
Returns:
items.Item
[]: all Items
(static) getItemsByTag(…tagNames) → {Array:.<Item:>}
- Description:
Gets all openHAB Items with a specific tag.
- Source:
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
tagNames |
Array:.<string:> |
<repeatable> |
an array of tags to match against |
Returns:
items.Item
[]: the Items with a tag that is included in the passed tags
(static) removeItem(itemOrItemName) → {Item|null}
- Description:
Removes an Item from openHAB. The Item is removed immediately and cannot be recovered.
- Source:
Parameters:
Name | Type | Description |
---|---|---|
itemOrItemName |
string | Item | the Item or the name of the Item to remove |
Returns:
the Item that has been removed or null
if no Item has been found, or it cannot be removed
- Type
- Item | null
(static) replaceItem(itemConfig) → {Item|null}
- Description:
Replaces (or adds) an Item. If an Item exists with the same name, it will be removed and a new Item with the supplied parameters will be created in its place. If an Item does not exist with this name, a new Item will be created with the supplied parameters.
This function can be useful in scripts which create a static set of Items which may need updating either periodically, during startup or even during development of the script. Using fixed Item names will ensure that the Items remain up-to-date, but won't fail with issues related to duplicate Items. When using file-based scripts, it is recommended to use
items.addItem
instead.
- Source:
Parameters:
Name | Type | Description |
---|---|---|
itemConfig |
ItemConfig | the Item config describing the Item |
Throws:
-
-
ItemConfig
.name orItemConfig
.type not set - Type
- Error
-
-
failed to create Item
Returns:
the old Item or null
if it did not exist
- Type
- Item | null
(static) safeItemName(s) → {string}
- Description:
Helper function to ensure an Item name is valid. All invalid characters are replaced with an underscore.
- Source:
Parameters:
Name | Type | Description |
---|---|---|
s |
string | the name to make value |
Returns:
a valid Item name
- Type
- string