Manages settings stored in the database

Before trying to access a modules' settings, DON'T forget to call {@see SettingDb::init()} before calling getValue() for the first time!

copyright CONTREXX CMS - COMVATION AG
author Reto Kohli <reto.kohli@comvation.com> (parts)
version 3.0.0
package contrexx
subpackage core
todo Edit PHP DocBlocks!

 Methods

Returns the settings from the old settings table for the given module ID, if available

__getOldSettings(integer $module_id) : array
Static

If the module ID is missing or invalid, or if the settings cannot be read for some other reason, returns null. Don't drop the table after migrating your settings, other modules might still need it! Instead, try this method only after you failed to get your settings from SettingDb.

static

Parameters

$module_id

integer

The module ID

Returns

arrayThe settings array on success, null otherwise

Add a new record to the settings

add(string $name, string $value, integer $ord, string $type, string $values, string $group) : boolean
Static

The class MUST have been initialized by calling {@see init()} or {@see getArray()} before this method is called. The present $group stored in the class is used as a default. If the current class $group is empty, it MUST be specified in the call.

Parameters

$name

string

The setting name

$value

string

The value

$ord

integer

The ordinal value for sorting, defaults to 0

$type

string

The element type for displaying, defaults to 'text'

$values

string

The values for type 'dropdown', defaults to the empty string

$group

string

The optional group

Returns

booleanTrue on success, false otherwise

Returns the current value of the changed flag.

changed() : boolean
Static

If it returns true, you probably want to call {@see updateAll()}.

Returns

booleanTrue if values have been changed in memory, false otherwise

Delete one or more records from the database table

delete(string $name, string $group) : boolean
Static

For maintenance/update purposes only. At least one of the parameter values must be non-empty. It will fail if both are empty. Mind that in this case, no records will be deleted. Does {@see flush()} the currently loaded settings on success.

Parameters

$name

string

The optional setting name. Defaults to null

$group

string

The optional group. Defaults to null

Returns

booleanTrue on success, false otherwise

Deletes all entries for the current section

deleteModule() : boolean
Static

This is for testing purposes only. Use with care! The static $section determines the module affected.

Returns

booleanTrue on success, false otherwise

Should be called whenever there's a problem with the settings table

errorHandler() : boolean
Static

Tries to fix or recreate the settings table.

static

Returns

booleanFalse, always.

Flush the stored settings

flush() : void
Static

Resets the class to its initial state. Does NOT clear the section, however.

Returns the settings array for the given section and group

getArray(string $section, string $group) : array
Static

See {@see init()} on how the arguments are used. If the method is called successively using the same $group argument, the current settings are returned without calling {@see init()}. Thus, changes made by calling {@see set()} will be preserved.

Parameters

$section

string

The section

$group

string

The optional group

Returns

arrayThe settings array on success, false otherwise

Returns the settings value stored in the object for the name given.

getValue(string $name) : mixed
Static

If the settings have not been initialized (see {@see init()}), or if no setting of that name is present in the current set, null is returned.

Parameters

$name

string

The settings name

Returns

mixedThe settings value, if present, null otherwise

Joins the strings in the array with commas into a single values string

joinValues(array $arrValues) : string
Static

Commas within the strings are escaped by a backslash (). The array keys are prepended to the values, separated by a colon. Colons within the strings are escaped by a backslash (). Note that keys MUST NOT contain either commas or colons!

todo Untested! May or may not work as described.

Parameters

$arrValues

array

The array of strings

Returns

stringThe concatenated values string

Updates a setting

set(string $name, string $value) : boolean
Static

If the setting name exists and the new value is not equal to the old one, it is updated, and $changed set to true. Otherwise, nothing happens, and false is returned

see updateAll()

Parameters

$name

string

The settings name

$value

string

The settings value

Returns

booleanTrue if the value has been changed, false otherwise, null on noop

Display the settings present in the $arrSettings class array

show(\Cx\Core\Html\Sigma $objTemplateLocal, string $uriBase, string $section, string $tab_name, string $prefix) : boolean
Static

Uses the indices as the names for any parameter, the values as themselves, and adds language variables for the settings' name with the given prefix (i.e. 'TXT_', or 'TXT_MYMODULE_') plus the upper case indices. Example: Settings: array('shop_dummy' => 1) Prefix: 'TXT_' Results in placeholders to be set as follows: Placeholder Value SETTINGDB_NAME The content of $_ARRAYLANG['TXT_SHOP_DUMMY'] SETTINGDB_VALUE The HTML element for the setting type with a name attribute of 'shop_dummy'

Placeholders: The settings' name is to SETTINGDB_NAME, and the input element to SETTINGDB_VALUE. Set the default block to parse after each array entry if it differs from the default 'core_setting_db'. Make sure to define all the language variables that are expected to be defined here! In addition, some entries from $_CORELANG are set up. These are both used as placeholder name and language array index: - TXT_CORE_SETTINGDB_STORE - TXT_CORE_SETTINGDB_NAME - TXT_CORE_SETTINGDB_VALUE

The template object is given by reference, and if the block 'core_settingdb_row' is not present, is replaced by the default backend template. $uriBase SHOULD be the URI for the current module page. If you want your settings to be stored, you MUST handle the post request, check for the 'bsubmit' index in the $_POST array, and call {@see SettingDb::store()}.

todo Add functionality to handle arrays within arrays
todo Add functionality to handle special form elements
todo Verify special values like e-mail addresses in methods that store them, like add(), update(), and updateAll()

Parameters

$objTemplateLocal

\Cx\Core\Html\Sigma

Template object

$uriBase

string

The base URI for the module.

$section

string

The optional section header text to add

$tab_name

string

The optional tab name to add

$prefix

string

The optional prefix for language variables. Defaults to 'TXT_'

Returns

booleanTrue on success, false otherwise

Adds an external settings view to the current template

show_external(\Cx\Core\Html\Sigma $objTemplateLocal, string $tab_name, string $content) : boolean
Static

The content must contain the full view, including the surrounding form tags and submit button. Note that these are always appended on the right end of the tab list.

Parameters

$objTemplateLocal

\Cx\Core\Html\Sigma

Template object

$tab_name

string

The tab name to add

$content

string

The external content

Returns

booleanTrue on success

Display a section of settings present in the $arrSettings class array

show_section(\Cx\Core\Html\Sigma $objTemplateLocal, string $section, string $prefix) : boolean
Static

See the description of {@see show()} for details.

Parameters

$objTemplateLocal

\Cx\Core\Html\Sigma

The Template object, by reference

$section

string

The optional section header text to add

$prefix

string

The optional prefix for language variables. Defaults to 'TXT_'

Returns

booleanTrue on success, false otherwise

Splits the string value at commas and returns an array of strings

splitValues(string $strValues) : array
Static

Commas escaped by a backslash () are ignored and replaced by a single comma. The values themselves may be composed of pairs of key and value, separated by a colon. Colons escaped by a backslash () are ignored and replaced by a single colon. Leading and trailing whitespace is removed from both keys and values. Note that keys MUST NOT contain commas or colons!

Parameters

$strValues

string

The string to be split

Returns

arrayThe array of strings

Update and store all settings found in the $_POST array

storeFromPost() : boolean
Static

Note that you MUST call {@see init()} beforehand, or your settings will be unknown and thus not be stored. Sets up an error message on failure.

Returns

booleanTrue on success, null on noop, or false on failure

Optionally sets and returns the value of the tab index

tab_index(integer $tab_index) : integer
Static

Parameters

$tab_index

integer

The optional new tab index

Returns

integerThe current tab index

Updates the value for the given name in the settings table

update(string $name) : boolean
Static

The class MUST have been initialized before calling this method using {@see init()}, and the new value been {@see set()}. Sets $changed to true and returns true if the value has been updated successfully. Note that this method does not work for adding new settings. See {@see add()} on how to do this. Also note that the loaded setting is not updated, only the database!

static
global mixed $objDatabase Database connection object

Parameters

$name

string

The settings name

Returns

booleanTrue on successful update or if unchanged, false on failure

Stores all settings entries present in the $arrSettings object array variable

updateAll() : boolean
Static

Returns boolean true if all records were stored successfully, null if nothing changed (noop), false otherwise. Upon success, also resets the $changed class variable to false. The class MUST have been initialized before calling this method using {@see init()}, and the new values been {@see set()}. Note that this method does not work for adding new settings. See {@see add()} on how to do this.

Returns

booleanTrue on success, null on noop, false otherwise

Ensures that a valid template is available

verify_template(\Cx\Core\Html\Sigma $objTemplateLocal) 
Static

Die()s if the template given is invalid, and settingDb.html cannot be loaded to replace it.

Parameters

$objTemplateLocal

\Cx\Core\Html\Sigma

The template, by reference

 Properties

 

$arrSettings : array

.. [more to come]), 'values' => predefined values (for dropdown), 'ord' => ordinal number (for sorting), ), ... more ... );

static
access private
 

$changed : boolean

This flag is set to true as soon as any change to the settings is detected. It is cleared whenever {@see updateAll()} is called.

static
access private
 

$group : string

Defaults to null (ignored).

static
access private
 

$section : string

Defaults to null (which will cause an error in most methods).

static
access private
 

$tab_index : integer
access private

 Constants

 

Default width for input fields

DEFAULT_INPUT_WIDTH 

Note that textareas often use twice that value.

 

Upload path for documents Used externally only, see hotelcard module for an example.

FILEUPLOAD_FOLDER_PATH 
 

TYPE_BUTTON

TYPE_BUTTON 
 

TYPE_CHECKBOX

TYPE_CHECKBOX 
 

TYPE_CHECKBOXGROUP

TYPE_CHECKBOXGROUP 
 

Setting types See {@see show()} for examples on how to extend these.

TYPE_DROPDOWN 
 

TYPE_DROPDOWN_USERGROUP

TYPE_DROPDOWN_USERGROUP 
 

TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE

TYPE_DROPDOWN_USER_CUSTOM_ATTRIBUTE 
 

TYPE_EMAIL

TYPE_EMAIL 
 

TYPE_FILEUPLOAD

TYPE_FILEUPLOAD 
 

TYPE_RADIO

TYPE_RADIO 
 

TYPE_TEXT

TYPE_TEXT 
 

TYPE_TEXTAREA

TYPE_TEXTAREA 
 

TYPE_WYSIWYG

TYPE_WYSIWYG 
© Copyright 2014 by Comvation AG
Generated on 2014-07-11T08:39:24+02:00.