RT 4.4.1 Documentation

RT::Config

NAME

    RT::Config - RT's config

SYNOPSYS

    # get config object
    use RT::Config;
    my $config = RT::Config->new;
    $config->LoadConfigs;

    # get or set option
    my $rt_web_path = $config->Get('WebPath');
    $config->Set(EmailOutputEncoding => 'latin1');

    # get config object from RT package
    use RT;
    RT->LoadConfig;
    my $config = RT->Config;

DESCRIPTION

RT::Config class provide access to RT's and RT extensions' config files.

RT uses two files for site configuring:

First file is RT_Config.pm - core config file. This file is shipped with RT distribution and contains default values for all available options. You should never edit this file.

Second file is RT_SiteConfig.pm - site config file. You can use it to customize your RT instance. In this file you can override any option listed in core config file.

You may also split settings into separate files under the etc/RT_SiteConfig.d/ directory. All files ending in .pm will be parsed, in alphabetical order, after RT_SiteConfig.pm is loaded.

RT extensions could also provide their config files. Extensions should use <NAME>_Config.pm and <NAME>_SiteConfig.pm names for config files, where <NAME> is extension name.

NOTE: All options from RT's config and extensions' configs are saved in one place and thus extension could override RT's options, but it is not recommended.

%META

Hash of Config options that may be user overridable or may require more logic than should live in RT_*Config.pm

Keyed by config name, there are several properties that can be set for each config optin:

 Section     - What header this option should be grouped
               under on the user Preferences page
 Overridable - Can users change this option
 SortOrder   - Within a Section, how should the options be sorted
               for display to the user
 Widget      - Mason component path to widget that should be used 
               to display this config option
 WidgetArguments - An argument hash passed to the WIdget
    Description - Friendly description to show the user
    Values      - Arrayref of options (for select Widget)
    ValuesLabel - Hashref, key is the Value from the Values
                  list, value is a user friendly description
                  of the value
    Callback    - subref that receives no arguments.  It returns
                  a hashref of items that are added to the rest
                  of the WidgetArguments
 PostSet       - subref passed the RT::Config object and the current and
                 previous setting of the config option.  This is called well
                 before much of RT's subsystems are initialized, so what you
                 can do here is pretty limited.  It's mostly useful for
                 effecting the value of other config options early.
 PostLoadCheck - subref passed the RT::Config object and the current
                 setting of the config option.  Can make further checks
                 (such as seeing if a library is installed) and then change
                 the setting of this or other options in the Config using 
                 the RT::Config option.
   Obfuscate   - subref passed the RT::Config object, current setting of the config option
                 and a user object, can return obfuscated value. it's called in
                 RT->Config->GetObfuscated() 

METHODS

new

Object constructor returns new object. Takes no arguments.

LoadConfigs

Load all configs. First of all load RT's config then load extensions' config files in alphabetical order. Takes no arguments.

LoadConfig

Takes param hash with File field. First, the site configuration file is loaded, in order to establish overall site settings like hostname and name of RT instance. Then, the core configuration file is loaded to set fallback values for all settings; it bases some values on settings from the site configuration file.

Note that core config file don't change options if site config has set them so to add value to some option instead of overriding you have to copy original value from core config file.

Configs

Returns list of config files found in local etc, plugins' etc and main etc directories.

LoadedConfigs

Returns a list of hashrefs, one for each config file loaded. The keys of the hashes are:

as

Name this config file was loaded as (relative filename usually).

filename

The full path and filename.

extension

The "extension" part of the filename. For example, the file RTIR_Config.pm will have an extension value of RTIR.

site

True if the file is considered a site-level override. For example, site will be false for RT_Config.pm and true for RT_SiteConfig.pm.

Get

Takes name of the option as argument and returns its current value.

In the case of a user-overridable option, first checks the user's preferences before looking for site-wide configuration.

Returns values from RT_SiteConfig, RT_Config and then the %META hash of configuration variables's "Default" for this config variable, in that order.

Returns different things in scalar and array contexts. For scalar options it's not that important, however for arrays and hash it's. In scalar context returns references to arrays and hashes.

Use scalar perl's op to force context, especially when you use (..., Argument = RT->Config->Get('ArrayOpt'), ...)> as perl's '=>' op doesn't change context of the right hand argument to scalar. Instead use (..., Argument = scalar RT->Config->Get('ArrayOpt'), ...)>.

It's also important for options that have no default value(no default in etc/RT_Config.pm). If you don't force scalar context then you'll get empty list and all your named args will be messed up. For example (arg1 = 1, arg2 => RT->Config->Get('OptionDoesNotExist'), arg3 => 3)> will result in (arg1 = 1, arg2 => 'arg3', 3)> what is most probably unexpected, or (arg1 = 1, arg2 => RT->Config->Get('ArrayOption'), arg3 => 3)> will result in (arg1 = 1, arg2 => 'element of option', 'another_one' => ..., 'arg3', 3)>.

GetObfuscated

the same as Get, except it returns Obfuscated value via Obfuscate sub

Set

Set option's value to new value. Takes name of the option and new value. Returns old value.

The new value should be scalar, array or hash depending on type of the option. If the option is not defined in meta or the default RT config then it is of scalar type.

Metadata

Meta

AddOption( Name => '', Section => '', ... )

DeleteOption( Name => '' )

UpdateOption( Name => '' ), Section => '', ... )

← Back to index