Saving options

A series of methods are offered to make it easy for plugins to set and retrieve options. These options can be directly edited from inside the Nucleus admin area, taking the need away for the plugin to provide an admin area of its own, and avoiding that options need to be set inside the PHP file itself.

Options are available in different contexts:

Global options: Editable on the admin area from the plugins section.
Blog options: Editable from the blogsettings pages.
Category options: Editable from the blogsettings pages (on the 'edit category' page).
Member options: Editable on the 'edit member' pages
Item options: Editable on the 'add item' or 'edit item' pages

Option types

Several types of options are provided

text: Simple text
yesno: Either the value 'yes' or the value 'no' (on edit, shown as radio button)
password: Text field (starred on edit)
textarea (v2.2): Text field with multiple rows and columns
select (v2.2): Drop down menu. Needs extra info in the following form: Option 1|value1|Option 2|value2|Option 3|value3

Option meta

As of Nucleus v3.2, some option types can be limited to only accept certain values using option-metadata. This metadata is stored in the $typeExtras-field, and is a semicolon-seperated list of values. Note: In a select-option, the select list must be the first value in $typeExtras.

key	explanation
`datatype`	Using '`datatype`' you can give some extra hints to Nucleus about the datatype you want to use. Currently only '`numerical`' is available. '`numerical`' will cause Nucleus to only accept numerical values for this option (using both client-side and server-side check) (available for optiontypes: '`select`' and '`text`')
`access`	If set to '`readonly`', the option will not be editable (available for optiontypes: '`text`' and '`textarea`') If set to '`hidden`', the option will be completely hidden for the end-user (available for optiontypes: '`text`')

some examples:

// following code creates a text-option that only accepts numerical values
$this->createBlogOption('FooBar', 'foobar', 'text', '0', 'datatype=numerical');
// following code creates a select-option that only accepts numerical values
$this->createItemOption('FooBar', 'foobar', 'select', '0', '0|0|1|1|2|2;datatype=numerical');
// following code creates a textarea-option that is readonly
$this->createOption('FooBar', 'foobar', 'textarea', 'Textarea is readonly', 'access=readonly');

Restrictions

The name of an option can contain a maximum of 20 characters
The description of an option can contain a maximum of 255 characters
The value for an option has no limit (Prior to v2.5 the limit was 128 characters)
The characters '=', '|' and ';' can not be used inside a select list (for a select-option), or in option-metadata

The methods

createOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates a new option in the global context

parameter	value
$name	Option name
$desc	Textual description, to be shown on the page where options can be edited
$type	Option type (see above)
$defValue	Initial value
$typeExtras	Extra info on option type (see above)

[v2.2] createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the blog context (see createOption)

[v2.2] createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the category context (see createOption)

[v2.2] createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the member context (see createOption)

[v3.2] createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the item context (see createOption)

setOption($name, $value)

changes the value of an option that was already in the database

parameter	value
$name	Option name
$value	New value for option

[v2.2] setBlogOption($blogid, $name, $value)

Changes the value for a blog option. The blogid attribute indicates for which blog the option is valid. (other options: see setOption)

[v2.2] setCategoryOption($catid, $name, $value)

Changes the value for a category option. The catid attribute indicates for which category the option is valid. (other options: see setOption)

[v2.2] setMemberOption($memberid, $name, $value)

Changes the value for a member option. The memberid attribute indicates for which member the option is valid. (other options: see setOption)

[v3.2] setItemOption($itemid, $name, $value)

Changes the value for an item option. The itemid attribute indicates for which item the option is valid. (other options: see setOption)

getOption($name)

Returns the value for an option in the database

parameter	value
$name	Option name

[v2.2] getBlogOption($blogid, $name)

Returns the value for a blog option. blogid indicates for which blog a value is requested (other parameters: see getOption)

[v2.2] getCategoryOption($catid, $name)

Returns the value for a category option. catid indicates for which category a value is requested (other parameters: see getOption)

[v2.2] getMemberOption($memberid, $name)

Returns the value for a member option. memberid indicates for which member a value is requested (other parameters: see getOption)

[v3.2] getItemOption($itemid, $name)

Returns the value for an item option. itemid indicates for which item a value is requested (other parameters: see getOption)

deleteOption($name)

Deletes an option from the database

parameter	value
$name	Option name

[v2.2] deleteBlogOption($name)

Deletes a blog option (see deleteOption)

[v2.2] deleteCategoryOption($name)

Deletes a category option (see deleteOption)

[v2.2] deleteMemberOption($name)

Deletes a member option (see deleteOption)

[v3.2] deleteItemOption($name)

Deletes an item option (see deleteOption)

[v2.2] getAllBlogOptions($name)

Returns all values for a given blog option. The result is an associative array with a value for each existing blogid

[v2.2] getAllCategoryOptions($name)

Returns all values for a given category option. The result is an associative array with a value for each existing catid

[v2.2] getAllMemberOptions($name)

Returns all values for a given member option. The result is an associative array with a value for each existing memberid

[v3.2] getAllItemOptions($name)

Returns all values for a given item option. The result is an associative array with a value for each existing itemid

[v3.2] getBlogOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each blogid ('id')

parameter	value
$name	Option name
$amount	The amount of options you want
$sort	Sort ascending ('asc') or descending ('desc')

[v3.2] getMemberOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each memberid ('id') (parameters: see getBlogOptionTop)

[v3.2] getCategoryOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each categoryid ('id') (parameters: see getBlogOptionTop)

[v3.2] getItemOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each itemid ('id') (parameters: see getBlogOptionTop)

Note: You can't call these functions from inside constructors of plugin classes. If you want to execute them when the plugin is loaded, place them in the init() method instead.

Plugin API

Nucleus Docs

Navigation