User::Config::Manual - What is User::Config exactly and how can it be used
version 0.00_01
As applications become bigger and bigger, often the user should be able to tune certain things to fit their needs. These settings are wide spread through the application and its management might become very difficult. In multiuser applications this becomes even more true. Additionally these setting should be saved to be provided even after a restart of this application.
User::Config aims to make this task as easy as possible. While each module can define it's own parameters and options, all of them can be configured via a single Interface. Additionaly modified values will transparently loaded and stored within an database.
While the application starts and the modules are loaded, each option gets registered. Thus an userinterface can show all options of all modules loaded at a given time.
In the following text the different tasks in using User::Config will be highlighted.
Defining a new parameter is as easy as declaring using has_option it
has_option
use User::Config has_option my_setting;
Now, the current value of this parameter for the user called 'foo' can be retrieved eg using the following command:
my $setting = $self->my_setting({ user => 'foo' });
Changing this configuration is possible as well:
$self->my_setting({ user => 'foo'}, "new value");
A context can be a hash-ref or an object. In both cases it must either have an key called User or a method user which can be called to get the name of the currently active user.
User
user
User::Config supports multiple contexts at the same time. If more then one is set, the most specific will be choosen. Currently there are the following contexts (the most specific first):
This context is set at the time, the setting is read or written. The context is passed while calling the corresponding configuration-item. To not set the context, simply do not pass it. This kind of context was used in the previous example.
Each (perl-)modul can set its own persistant context. To set this context, call
$self->context($context);
To unset it, supply undef as context:
undef
$self->context(undef);
There is also a possability to supply a global or default context, used by all modules
User::Config->instance->context($context);
For each setting, a default value can be supplied either using a fixed value, or using a sub-ref for computing a new value on demand. This function will get the current context supplied.
has_option my_setting => ( default => sub { my ($context, $name) = @_; # $name will be "my_setting" ... } )
While defining a setting, provide a cross-reference and the settings in both modules will always have the same value
has_option other_setting => ( references => 'other::modules::name::setting_name' )
When provided, the settings will automaticly saved within a persistant database. While starting, a simple memory-based backend is used, but there are others supplied. One of them can be loaded using for example the following code:
Config::User->instance->db('Keyed', { connector => 'dbi:SQLite:mydatabase', table => 'usersettings' })
All database backends live within the namespace User::Config::DB. See eg User::Config::DB::LDAP, User::Config::DB::DBIC or User::Config::DB::Keyed for more details.
The modules within User::Config::UI provide a interface which can be used to present to the user.
To generate a HTML-Form using HTML::Formhandler, the following code would be sufficient
use User::Config use CGI; my $form = User::Config->ui('HTMLFormHandler', CGI->new->Vars);
For more information see User::Config::UI::HTMLFormHandler
The distribution of User::Config includes a helper-modul for Catalyst. To generate a model with the functional range of User::Config the command
script/myapp_create.pl model UserConfig UserConfig
will generate the needed code. Additionaly this model will incorperate the form-method of "form" in User::Config::UI::HTMLFormHandler
User::Config User::Config::DB User::Config::UI
Benjamin Tietz <benjamin@micronet24.de>
This was licensed under the same terms as Perl itself.
To install User::Config, copy and paste the appropriate command in to your terminal.
cpanm
cpanm User::Config
CPAN shell
perl -MCPAN -e shell install User::Config
For more information on module installation, please visit the detailed CPAN module installation guide.