RT 5.0.1 Documentation
RT::Config
NAME
RT::Config - RT's configSYNOPSYS
# 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.
SectionMap
A data structure used to breakup the option list into tabs/sections/subsections/options This is done by parsing RT_Config.pm.
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.pmwill have anextensionvalue ofRTIR. - site
-
True if the file is considered a site-level override. For example,
sitewill be false forRT_Config.pmand true forRT_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.