<<

# Bugzilla::User::Setting

- NAME
- SYNOPSIS
- DESCRIPTION
- CLASS FUNCTIONS
- METHODS

# NAME

Bugzilla::User::Setting - Object for a user preference setting

# SYNOPSIS

Setting.pm creates a setting object, which is a hash containing the user preference information for a single preference for a single user. These are usually accessed through the "settings" object of a user, and not directly.

# DESCRIPTION

use Bugzilla::User::Setting; my $settings;

$settings->{$setting_name} = new Bugzilla::User::Setting( $setting_name, $user_id);

OR

$settings->{$setting_name} = new Bugzilla::User::Setting( $setting_name, $user_id, $is_enabled, $default_value, $value, $is_default);

# CLASS FUNCTIONS

`add_setting($name, \@values, $default_value, $subclass, $force_check)`

  Description: Checks for the existence of a setting, and adds it to the database if it does not yet exist.

  Params: `$name` - string - the name of the new setting `$values` - arrayref - contains the new choices for the new Setting. `$default_value` - string - the site default `$subclass` - string - name of the module returning the list of valid values. This means legal values are not stored in the DB. `$force_check` - boolean - when true, the existing setting and all its values are deleted and replaced by new data.

  Returns: a pointer to a hash of settings

`get_all_settings($user_id)`

  Description: Provides the user's choices for each setting in the system; if the user has made no choice, uses the site default instead. Params: `$user_id` - integer - the user id. Returns: a pointer to a hash of settings

`get_defaults($user_id)`

  Description: When a user is not logged in, they must use the site defaults for every settings; this subroutine provides them. Params: `$user_id` (optional) - integer - the user id. Note that this optional parameter is mainly for internal use only. Returns: A pointer to a hash of settings. If $user_id was passed, set the user_id value for each setting.

`set_default($setting_name, $default_value, $is_enabled)`

  Description: Sets the global default for a given setting. Also sets whether users are allowed to choose their own value for this setting, or if they must use the global default. Params: `$setting_name` - string - the name of the setting `$default_value` - string - the new default value for this setting `$is_enabled` - boolean - if false, all users must use the global default Returns: nothing

# METHODS

`legal_values($setting_name)`

  Description: Returns all legal values for this setting Params: none Returns: A reference to an array containing all legal values

`validate_value`

  Description: Determines whether a value is valid for the setting by checking against the list of legal values. Untaints the parameter if the value is indeed valid, and throws a setting_value_invalid code error if not. Params: An lvalue containing a candidate for a setting value Returns: nothing

`reset_to_default`

  Description: If a user chooses to use the global default for a given setting, their saved entry is removed from the database via this subroutine. Params: none Returns: nothing

`set($value)`

  Description: If a user chooses to use their own value rather than the global value for a given setting, OR changes their value for a given setting, this subroutine is called to insert or update the database as appropriate. Params: `$value` - string - the new value for this setting for this user. Returns: nothing

<<