key

key

pb.plugin.key(name)

Returns a key object for a given key name. The object provides synchronous and asynchronous functions to manipulate stored key data.

Param	Type	Description
name	string	The plugin key name

Key

The corresponding key object is returned when using the "key" function. This key object contains functions to manipulate the stored data for that key.

Methods

• async
  • get
  • set
  • append
  • prepend
  • increment
  • decrement
  • push
  • pop
  • unshift
  • shift
• type
• get
• set
• unset
• setOn
• after
• canRead
• canWrite
• append
• prepend
• increment
• decrement
• push
• pop
• shift
• unshift

async

The async object contains asynchronous versions of the same key manipulation functions.

Properties

Name	Type
async	Object

Methods

• get
• set
• append
• prepend
• increment
• decrement
• push
• pop
• unshift
• shift

get

keyInstance.async.get([object_id])

A function that returns a promise to retrieve the most up to date value for the given object id from the server.

Returns: Promise - Promise object that represents the value for the given object id.

Param	Type	Description
[object_id]	number	The ID of the object.

set

keyInstance.async.set(options)

A function that returns a promise to set the plugin key to a given value.

Returns: Promise - Promise object that represents the new value.

Param	Type	Description
options	Object	Additional options:
options.value	Object | string | number	The value to be assigned to this key.
[options.object_id]	number	The ID of the object.
[options.metadata]	Array.<PageMetadataKey>	An array of strings where each string represents a page data property. This data is added to the value as an object key/value pair.

append

keyInstance.async.append(options)

A function that returns a promise to concatenate a given value to the end of the existing key value. The promise will resolve successfully with the updated value.

Returns: Promise - Promise object that represents the updated value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
options.value	string | number	The value to be added to the end of the existing value.

prepend

keyInstance.async.prepend(options)

A function that returns a promise to insert a given value in front of the existing key value. The promise will resolve successfully with the updated value.

Returns: Promise - Promise object that represents the updated value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
options.value	string | number	The value to be added to the beginning of the existing value.

increment

keyInstance.async.increment([options])

A function that returns a promise to increment a key value. If the key is an integer, increases the key's value by one, or you can optionally supply a different amount to increment by. The promise will resolve successfully with the updated value.

Returns: Promise - Promise object that represents the updated value.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.value]	string | number	1	The amount by which to increment.

decrement

keyInstance.async.decrement([options])

A function that returns a promise to decrement a key value. If the key is an integer, decreases the key's value by one, or you can optionally supply a different amount to decrement by. The promise will resolve successfully with the updated value.

Returns: Promise - Promise object that represents the updated value.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.value]	string | number	1	The amount by which to increment.

push

keyInstance.async.push(options)

A function that returns a promise to add one or more values to the end of an array. You must supply either options.value or options.values. If both are supplied, options.values will be ignored in favor of options.value.

Returns: Promise - Promise object that represents the updated array.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
[options.value]	string | number	The value to be pushed onto the array.
[options.values]	Array	An array of values to be pushed onto the array.
[options.metadata]	Array.<PageMetadataKey>	An array of strings where each string represents a page data property. This data is added to the value as an object key/value pair. It can only use it when pushing a single item. It cannot be used with the 'values' option.

pop

keyInstance.async.pop([options])

A function that returns a promise to remove the last item in the array. You can supply an options.num_items value to pop multiple items off. The promise will resolve successfully with the item(s) that were removed.

Returns: Promise - Promise object that represents the item(s) popped off from the array.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.num_items]	number	1	The number of items to pop.

unshift

keyInstance.async.unshift(options)

A function that returns a promise to add one or more values to the front of an array. You must supply either options.value or options.values. If both are supplied, options.values will be ignored in favor of options.value.

Returns: Promise - Promise object that represents the updated array.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
[options.value]	string | number	The value to be unshifted onto the array.
[options.values]	Array	An array of values to be unshifted onto the array.

shift

keyInstance.async.shift([options])

A function that returns a promise to remove the first item in the array. You can supply an options.num_items value to shift multiple items off. The promise will resolve successfully with the item(s) that were removed.

Returns: Promise - Promise object that represents the item(s) shifted off from the array.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.num_items]	number	1	The number of items to shift.

type

keyInstance.type()

Returns the type code of this plugin key. The reference function pb.plugin.key_types() may be handy when used in conjunction with this function.

Returns: number - The numeric code that represents this key type.

get

keyInstance.get([object_id])

Returns the value associated with this plugin key for the passed-in object_id.

Returns: string | number | Array | Object - The value of this plugin key stored under this object_id.

Param	Type	Description
[object_id]	number	The ID of the object.

set

keyInstance.set(options)

Sets the plugin key.

Param	Type	Description
options	Object	Additional options:
options.value	Object | string | number	The value to be assigned to this key.
[options.object_id]	number	The ID of the object.
[options.success]	function	The success callback function.
[options.metadata]	Array.<PageMetadataKey>	An array of strings where each string represents a page data property. This data is added to the value as an object key/value pair.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

unset

keyInstance.unset(options)

Sets the plugin key value to undefined. Object ID must be explicitly defined.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
[options.success]	function	The success callback function.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

setOn

keyInstance.setOn(hook, [objectId], [value])

Triggers a plugin key to be set when a specific hook event occurs.

Param	Type	Description
hook	string	The name of the event. Limited to 'thread_new' and 'post_new'.
[objectId]	number	The ID of the object.
[value]	string | number	The value to be assigned to this key.

after

keyInstance.after(hook, callback)

Execute a callback after a specified hook event occurs.

Param	Type	Description
hook	string	The name of the event. Limited to 'thread_new', 'thread_edit', 'post_new', 'post_edit', and 'user_edit'.
callback	function	A method to run after the hook event happens. The first parameter is the new id related to the event. The second parameter is the plugin key object. The owner of the method, 'this', is also the plugin key object.

canRead

keyInstance.canRead([object_id])

Check if the key can be read for the specified object_id.

Returns: Boolean - True if the key can be read from for the specified object_id

Param	Type	Default	Description
[object_id]	number	user_id	The ID of the object to be checked.

canWrite

keyInstance.canWrite([object_id])

Check if the key can be written to for the specified object_id.

Returns: Boolean - True if the key can be written to for the specified object_id

Param	Type	Default	Description
[object_id]	number	user_id	The ID of the object to be checked.

append

keyInstance.append(options)

Concatenates a given value to the end of the existing key value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
options.value	string | number	The value to be added to the end of the existing value.
[options.success]	function	The success callback function.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

prepend

keyInstance.prepend(options)

Inserts a given value in front of the existing key value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
options.value	string | number	The value to be added to the beginning of the existing value.
[options.success]	function	The success callback function.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

increment

keyInstance.increment([options])

If the key is an integer, increases the key's value by one, or you can optionally supply a different amount to increment by.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.value]	string | number	1	The amount by which to increment.
[options.success]	function		The success callback function.
[options.error]	function		The error callback function.
[options.complete]	function		The complete callback function.

decrement

keyInstance.decrement([options])

If the key is an integer, decreases the key's value by one, or you can optionally supply a different amount to decrement by.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.value]	string | number	1	The amount by which to decrement.
[options.success]	function		The success callback function.
[options.error]	function		The error callback function.
[options.complete]	function		The complete callback function.

push

keyInstance.push(options)

If the key is an array, adds the given value to the back of the array. You must supply either options.value or options.values. If both are supplied, options.values will be ignored in favor of options.value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
[options.value]	string | number	The value to be pushed onto the array.
[options.values]	Array	An array of values to be pushed onto the array.
[options.metadata]	Array.<PageMetadataKey>	An array of strings where each string represents a page data property. This data is added to the value as an object key/value pair. It can only use it when pushing a single item. It cannot be used with the 'values' option.
[options.success]	function	The success callback function.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

pop

keyInstance.pop([options])

If the key is an array, removes the last options.num_items values and returns them.

Returns: string | number | Array | Object | undefined - The last options.num_items values of the array, before they were removed. If multiple items are returned, they will be returned in an array. If popping from a key that is not loaded on the page, nothing will be returned.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.num_items]	number	1	The number of items to pop.
[options.success]	function		The success callback function.
[options.error]	function		The error callback function.
[options.complete]	function		The complete callback function.

shift

keyInstance.shift([options])

If the key is an array, removes the first options.num_items values and returns them.

Returns: string | number | Array | Object | undefined - The first options.num_items values of the array, before they were removed. If multiple items are returned, they will be returned in an array. If shifting from a key that is not loaded on the page, nothing will be returned.

Param	Type	Default	Description
[options]	Object		Additional options:
[options.object_id]	number		The ID of the object.
[options.num_items]	number	1	The number of items to shift.
[options.success]	function		The success callback function.
[options.error]	function		The error callback function.
[options.complete]	function		The complete callback function.

unshift

keyInstance.unshift(options)

If the key is an array, adds the given value to the front of the array. You must supply either options.value or options.values. If both are supplied, options.values will be ignored in favor of options.value.

Param	Type	Description
options	Object	Additional options:
[options.object_id]	number	The ID of the object.
[options.value]	string | number	The value to be unshifted onto the array.
[options.values]	Array	An array of values to be unshifted onto the array.
[options.success]	function	The success callback function.
[options.error]	function	The error callback function.
[options.complete]	function	The complete callback function.

PageMetadataKey

Depending on the page the user is on, there is various metadata about that page that can be accessed. This data can be viewed by using "pb.data.get('page')". PageMetadataKey is a string that acts as a key to access a specific metadata property. Use the function "pb.plugin.getAvailablePageMetadataKeys()" to see what PageMetadataKey values are available for the current page. Some pages may not have any metadata available.