JavaScript API - key

key

Returns a handle to the plugin key object with the given key. The associated utility methods provide an easy interface to modifying the value of this key.

A few general notes on these functions:

Unless otherwise noted, all error functions will default to creating a proboards.error dialog box with the error message and error code. This is so that errors will be more obvious during the construction of code.

If you're attempting to set the value of a plugin key that is not a super forum key, and you do not supply an object_id, the setting functions will attempt to infer an object_id from the page you're on. For example, on a post creation page, if you try to set an anonymous post key, the object_id will be the id of the post you're creating.

You can use any of these key functions that manipulate the data of a key on a key that is not currently loaded onto the page, however the key's data will not become available to you unless you use the set function.

Parameters

  • key String
    The identifying string for this key.

Returns

Object
The plugin key with the passed-in key name.

Methods:

append
can_read
can_write
decrement
get
increment
pop
prepend
push
set
set_on
shift
type
unshift
Direct Link

append

( options )
Concatenates a given value to the end of the existing key value.

Parameters

  • options Object
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • value String|Number
      The value to be added to the end of the existing value.
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

can_read

( [object_id ] )
Check if the key can be read for the specified object_id.

Parameters

  • [object_id ] Number Optional
    The ID of the object to be checked.
    Defaults To: user_id

Returns

Boolean
True if the key can be read from for the specified object_id, false otherwise.
Direct Link

can_write

( [object_id ] )
Check if the key can be written to for the specified object_id.

Parameters

  • [object_id ] Number Optional
    The ID of the object to be checked.
    Defaults To: user_id

Returns

Boolean
True if the key can be written to for the specified object_id, false otherwise.
Direct Link

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.

Parameters

  • [options] Object Optional
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [value] String|Number Optional
      The amount by which to decrement.
      Defaults To: 1
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

get

( [object_id] )
Returns the value associated with this plugin key for the passed-in object_id.

Parameters

  • [object_id] Number Optional
    The ID of the object.

Returns

String|Number|Array|Object
The value of this plugin key stored under this object_id.
Direct Link

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.

Parameters

  • [options] Object Optional
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [value] String|Number Optional
      The amount by which to increment.
      Defaults To: 1
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

pop

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

Parameters

  • [options] Object Optional
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [num_items] Number Optional
      The number of items to pop.
      Defaults To: 1
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.

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.
Direct Link

prepend

( options )
Inserts a given value in front of the existing key value.

Parameters

  • options Object
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • value String|Number
      The value to be added to the beginning of the existing value.
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

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.

Parameters

  • options Object
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [value] String|Number Optional
      The value to be pushed onto the array.
    • [values] Array Optional
      An array of values to be pushed onto the array.
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

set

( options )
Sets the plugin key.

Parameters

  • options Object
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • value String|Number
      The value to be assigned to this key.
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.
Direct Link

set_on

( hook, [object_id], [value] )
Triggers a plugin key to be set when a specific action occurs.

Parameters

  • hook String
    The name of the action. Right now this is limited to 'thread_new' and 'post_new'.
  • [object_id] Number Optional
    The ID of the object.
  • [value] String|Number Optional
    The value to be assigned to this key.
Direct Link

shift

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

Parameters

  • [options] Object Optional
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [num_items] Number Optional
      The number of items to shift.
      Defaults To: 1
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.

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.
Direct Link

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.
Direct Link

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.

Parameters

  • options Object
    Additional options:
    • [object_id] Number Optional
      The ID of the object.
    • [value] String|Number Optional
      The value to be unshifted onto the array.
    • [values] Array Optional
      An array of values to be unshifted onto the array.
    • [success] Function Optional
      The success callback function.
    • [error] Function Optional
      The error callback function.
    • [complete] Function Optional
      The complete callback function.