Settings Class Reference

The Settings class provides components with a common API for specifying application settings and configuration values. More...

Inherits DataItem.

Public Member Functions
	save ()
	permitsRole ($role)
	formatOptionList ()

Static Public Member Functions
static	getSetting ($component, $name)
static	getValue ($component, $name)
	Retrieve the value of the specified Setting. More...
static	setValue ($component, $name, $value, $field_type, $annotation="", $category="", $options="", $weight=0)
	Sets the value of the given component setting. More...
static	setDefaultValue ($component, $name, $value, $field_type="String", $annotation="", $category="", $options="", $weight=0)
	Sets the default value of the given component setting. More...
static	deleteValue ($component, $name)
	Delete the specified value from the settings table. More...
static	setPermission ($component, $name, $annotation, $value, $weight)
	Set a Permission value indicating which SiteRoles have the given permission. More...
static	setDefaultPermission ($component, $name, $annotation, $value, $weight=0)
	Set a default Permission value indicating which SiteRoles have the given permission. More...
static	checkPermission ($component, $name, $account=null)
	Check whether a user has a specific permission. More...
static	assertPermission ($component, $name, $redirect="", $message="")
	Asserts whether the current user has a specific permission, optionally redirecting to a specified location if they do not. More...
static	checkPermissions ($permissions, $account=null)
	Check all the permissions specified in the given string. More...
static	deletePermission ($component, $name)
	Deletes the specified permissions. More...
static	getComponents ()
static	createPermissionsFieldRenderer ($form, $field, $label="")

Public Attributes
	$primary_key = "settings_id"
	$table = "settings"
	$fields
	$relations = array()

Static Public Attributes
static	$fieldTypes

Detailed Description

The Settings class provides components with a common API for specifying application settings and configuration values.

These settings are stored in the application database and can be modified through the site administration screens.

Author

andy

Definition at line 48 of file settings.inc.

Member Function Documentation

assertPermission()

static Settings::assertPermission (   $component,   $name,   $redirect = "",   $message = ""  )

static

Asserts whether the current user has a specific permission, optionally redirecting to a specified location if they do not.

Parameters

string	$component	the component that owns the permission
string	$name	the unique name of the permission
string	$redirect	URL to redirect to on failure

Definition at line 255 of file settings.inc.

     {
          $roles = Settings::getValue($component, $name);
          
          Fakoli::assertRole($roles, $redirect, $message);
     }

checkPermission()

static Settings::checkPermission (   $component,   $name,   $account = null  )

static

Check whether a user has a specific permission.

Parameters

string	$component	the component that owns the permission
string	$name	the unique name of the permission
object	$account	(optional) user account to test. If not specified the currently logged in user is tested.

Definition at line 241 of file settings.inc.

     {
          $roles = Settings::getValue($component, $name);
          
          return checkRole($roles, $account);
     }

checkPermissions()

static Settings::checkPermissions (   $permissions,   $account = null  )

static

Check all the permissions specified in the given string.

If the user belongs to a role with ONE of the specified permissions, return true. If the user does not, return false.

Parameters

string	$permissions	permission list in the form "[component]:[permission],[component]:[permission]..."
object	$account	(optional) user account to test. If not specified the currently logged in user is tested.

Definition at line 270 of file settings.inc.

     {
          if ($permissions == "") return true;
          
          $perms = explode(",", $permissions);
          
          foreach($perms as $perm)
          {
               list($component, $permission) = explode(":", $perm);
               if (Settings::checkPermission($component, $permission, $account)) return true;
          }
     
          return false;
     }

createPermissionsFieldRenderer()

static Settings::createPermissionsFieldRenderer (   $form,   $field,   $label = ""  )

static

Definition at line 343 of file settings.inc.

     {
          $permissions = Query::create(Settings, "WHERE category='Permissions' ORDER BY component, annotation")->execute();
          
          if (count($permissions) == 0) 
          {
               $form->hide($field);               
               return null;
          }
          
          $options = array();
          
          foreach($permissions as $p)
          {
               $c = prettify($p->component);
               
               if (!array_key_exists($c, $options)) $options[$c] = array();
               $options[$c]["{$p->component}:{$p->name}"] = $p->annotation;
          }
          
          $renderer = new CheckListFieldRenderer($form, $field, $label, $options, true);
          $renderer->setSize(400, 150);
          return $renderer;             
     }

deletePermission()

static Settings::deletePermission (   $component,   $name  )

static

Deletes the specified permissions.

Parameters

string	$component	the name of the component to which the permission belongs
string	$name	the name of the permission to be deleted

Definition at line 290 of file settings.inc.

     {
          Settings::deleteValue($component, $name);
          ComponentManager::fireEvent('PermissionDeleted', "{$component}:{$name}");
     }

deleteValue()

static Settings::deleteValue (   $component,   $name  )

static

Delete the specified value from the settings table.

Parameters

string	$component	the name of the component that owns the setting
string	$name	the name of the setting to be deleted

Definition at line 195 of file settings.inc.

     {
          $settings = Query::create(Settings, "WHERE component=:c and name=:n")
                               ->bind(":c", $component, ":n", $name)
                               ->execute();
          
          foreach($settings as $s)
          {
               $s->delete();
          }
          
          Cache::invalidate("setting_{$component}_{$name}");
     }

formatOptionList()

Settings::formatOptionList

(

)

Definition at line 312 of file settings.inc.

     {
          if(!$this->options)
               return null;
               
          $options = explode("\n", $this->options);
          
          $optionList = array();
          foreach($options as $option)
          {
               if (strpos($option, "=>") !== false)
               {
                    list($val, $text) = explode("=>", $option);
                    $val = trim($val);
                    $text = trim($text);
                    $optionList[$val] = $text;
               }
               else
               {
                    $optionList[$option] = $option;
               }
          }
          
          return $optionList;
     }

getComponents()

static Settings::getComponents ( )

static

Definition at line 338 of file settings.inc.

     {
          return Query::create(Component, "WHERE name in (SELECT DISTINCT component FROM settings) ORDER BY name")->execute();
     }

getSetting()

static Settings::getSetting (   $component,   $name  )

static

Definition at line 83 of file settings.inc.

     {
          try
          {
               $setting = Query::create(Settings, "WHERE component=:component AND name=:name")
                                   ->bind(":component", $component, ":name", $name)
                                   ->executeSingle();
               Cache::put("setting_{$component}_{$name}", $setting->value);
               return $setting;
          }
          catch(DataNotFoundException $e)
          {
               return null;
          }         
     }

getValue()

static Settings::getValue (   $component,   $name  )

static

Retrieve the value of the specified Setting.

Parameters

string	$component	the name of the component that owns the setting
string	$name	the name of the setting

Definition at line 104 of file settings.inc.

     {
          $value = Cache::get("setting_{$component}_{$name}");
          if ($value !== null) return $value;
          
          try 
          {
               $setting = Query::create(Settings, "WHERE component=:c and name=:n")
                              ->filter(new InclusionFilter("value"))
                             ->bind(":c", $component, ":n", $name)
                              ->executeSingle();
               Cache::put("setting_{$component}_{$name}", $setting->value);
               return $setting->value;
          }
          catch (DataNotFoundException $e) 
          {
               trace("Setting not found for $component $name", 3);
               return null;
          }
     }

permitsRole()

Settings::permitsRole

(

$role

)

Definition at line 296 of file settings.inc.

     {
          if (!$role)
          {
               throw new FakoliException("Missing role");
          }
          
          if ($this->options != 'Permissions')
          {
               throw new FakoliException("Role check on non-permissions settings");
          }
          
          $expr = "/\\b{$role}\\b/";
          return (preg_match($expr, $this->value) > 0) ? true : false;
     }

save()

Settings::save

(

)

Definition at line 77 of file settings.inc.

     {
          Cache::invalidate("setting_{$this->component}_{$this->name}");
          parent::save();
     }

setDefaultPermission()

static Settings::setDefaultPermission (   $component,   $name,   $annotation,   $value,   $weight = 0  )

static

Set a default Permission value indicating which SiteRoles have the given permission.

Parameters

string	$component	the name of the component that owns the permission
string	$name	the unique name of the permission
string	$annotation	short description of the permission
string	$value	comma-separated list of roles that have the permission
int	$weight	optional weight parameter to control display order

Definition at line 230 of file settings.inc.

     {
          Settings::setDefaultValue($component, $name, $value, "String", $annotation, "Permissions", "Permissions", $weight);          
     } 

setDefaultValue()

static Settings::setDefaultValue (   $component,   $name,   $value,   $field_type = "String",   $annotation = "",   $category = "",   $options = "",   $weight = 0  )

static

Sets the default value of the given component setting.

Creating settings for a component using this method will generate a tab under the Application Settings area of the site administration interface, allowing your users to control your component's behavior.

Parameters

	string	component the name of the component that owns the setting
string	$name	the name of the setting (this will be automatically prettified when presented to the user)
mixed	$value	the default value for the setting. If the setting has already been defined, the value will not be overwritten
string	$field_type	the type of field renderer to use to display the setting in the admin interface
string	$annotation	any help annotation to display on the form (optional)
string	$category	the sub-category within the form to which the setting belongs. Settings with the same category name are grouped together into fieldsets.
number	$weight	a weighting factor to control display order on the Application Settings form. Controls are sorted (within categories) first by weight, then alphabetically (optional).

Definition at line 174 of file settings.inc.

     {
          $setting = Settings::getSetting($component, $name);
          if ($setting) 
          {
               $setting->annotation = $annotation;
               $setting->category = $category;
               $setting->options = $options;
               $setting->weight = $weight;
               $setting->save();
               return;
          }
          
          Settings::setValue($component, $name, $value, $field_type, $annotation, $category, $options, $weight);
     }

setPermission()

static Settings::setPermission (   $component,   $name,   $annotation,   $value,   $weight  )

static

Set a Permission value indicating which SiteRoles have the given permission.

Parameters

string	$component	the name of the component that owns the permission
string	$name	the unique name of the permission
string	$annotation	short description of the permission
string	$value	comma-separated list of roles that have the permission
int	$weight	optional weight parameter to control display order

Definition at line 217 of file settings.inc.

     {
          Settings::setValue($component, $name, $value, "String", $annotation, "Permissions", "Permissions", $weight = 0);        
     }

setValue()

static Settings::setValue (   $component,   $name,   $value,   $field_type,   $annotation = "",   $category = "",   $options = "",   $weight = 0  )

static

Sets the value of the given component setting.

Parameters

	string	component the name of the component that owns the setting
string	$name	the name of the setting (this will be automatically prettified when presented to the user)
mixed	$value	the default value for the setting. The value will be overwritten, even if previously set
string	$field_type	the type of field renderer to use to display the setting in the admin interface
string	$annotation	any help annotation to display on the form (optional)
string	$category	the sub-category within the form to which the setting belongs. Settings with the same category name are grouped together into fieldsets.
number	$weight	a weighting factor to control display order on the Application Settings form. Controls are sorted (within categories) first by weight, then alphabetically (optional).

Definition at line 138 of file settings.inc.

     {
          $setting = Settings::getSetting($component, $name);
          if (!$setting)
          {
               $setting = new Settings();
               $setting->component = $component;
               $setting->name = $name;
               $setting->field_type = $field_type;
               $setting->annotation = $annotation;
               $setting->options = $options;
               $setting->category = $category;
               $setting->weight = $weight;
          }
          
          $setting->value = $value;
          $setting->save();
          Cache::put("setting_{$component}_{$name}", $setting->value);
     }

Member Data Documentation

$fields

Settings::$fields

Initial value:

= array("settings_id"    =>   Number,
                              "component"         =>   String,
                              "category"          =>   String,
                              "name"              =>   String,
                              "annotation"   =>   Text,
                              "options"      =>   Text,
                              "value"             =>   String,
                              "field_type"   =>   String,
                              "weight"       =>   Number
                         )

Definition at line 54 of file settings.inc.

$fieldTypes

Settings::$fieldTypes

static

Initial value:

= array(
                    "String"  =>   "String",
                    "Number"  =>   "Number",
                    "Boolean" =>   "Boolean",
                    "Date"         =>   "Date",
                    "Currency"     =>   "Currency",
                    "Text"         =>   "Text"
     )

Definition at line 68 of file settings.inc.

$primary_key

Settings::$primary_key = "settings_id"

Definition at line 50 of file settings.inc.

$relations

Settings::$relations = array()

Definition at line 66 of file settings.inc.

$table

Settings::$table = "settings"

Definition at line 51 of file settings.inc.

---

The documentation for this class was generated from the following file:

• C:/code/cms.sonjara.com/cms/components/settings/datamodel/settings.inc