source: trunk/lib/OpenGuides/Config.pm @ 611

Last change on this file since 611 was 611, checked in by Dominic Hargreaves, 17 years ago

Dev note about documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.5 KB
Line 
1package OpenGuides::Config;
2use strict;
3
4use Config::Tiny;
5
6use base qw( Class::Accessor );
7my @variables = qw(
8   dbtype dbname dbuser dbpass dbhost script_name install_directory script_url
9   custom_lib_path use_plucene indexing_directory enable_page_deletion
10   admin_pass stylesheet_url site_name navbar_on_home_page home_name
11   site_desc default_city default_country contact_email default_language
12   formatting_rules_node formatting_rules_link backlinks_in_title template_path custom_template_path
13   geo_handler ellipsoid
14);
15my @questions = map { $_ . "__qu" } @variables;
16OpenGuides::Config->mk_accessors( @variables );
17OpenGuides::Config->mk_accessors( @questions );
18
19=head1 NAME
20
21OpenGuides::Config - Handle OpenGuides configuration variables.
22
23=head1 DESCRIPTION
24
25Does config stuff for OpenGuides.  Distributed and installed as part of
26the OpenGuides project, not intended for independent installation.
27This documentation is probably only useful to OpenGuides developers.
28
29=head1 METHODS
30
31=over
32
33=item B<new>
34
35  my $config = OpenGuides::Config->new( file => "wiki.conf" );
36
37Initialises itself from the config file specified.  Variables which
38are not set in that file, and which have sensible defaults, will be
39initialised as described below in ACCESSORS; others will be given a
40value of C<undef>.
41
42  my $config = OpenGuides::Config->new( vars => { dbname => "foo" } );
43
44As above but gets variables from a supplied hashref instead.
45
46=cut
47
48sub new {
49    my $class = shift;
50    my $self = { };
51    bless $self, $class;
52    return $self->_init( @_ );
53}
54
55sub _init {
56    my ($self, %args) = @_;
57
58    # Here are the defaults for the variable values.
59    # Don't forget to add to INSTALL when changing these.
60    my %defaults = (
61                     dbtype => "postgres",
62                     script_name => "wiki.cgi",
63                     install_directory => "/usr/lib/cgi-bin/openguides/",
64                     use_plucene => 1,
65                     indexing_directory => "/usr/lib/cgi-bin/openguides/indexes/",
66                     enable_page_deletion => 0,
67                     admin_pass => "Change This!",
68                     site_name => "Unconfigured OpenGuides site",
69                     navbar_on_home_page => 1,
70                     home_name => "Home",
71                     site_desc => "A default configuration of OpenGuides",
72                     default_city => "",
73                     default_country => "",
74                     default_language => "en",
75                     formatting_rules_node => "Text Formatting Examples",
76                     formatting_rules_link => "http://openguides.org/page/text_formatting",
77                     backlinks_in_title => 0,
78                     geo_handler => 1,
79                     ellipsoid => "International"
80                   );
81
82    # See if we already have some config variables set.
83    my %stored;
84    if ( $args{file} ) {
85        my $read_config = Config::Tiny->read( $args{file} );
86        %stored = $read_config ? %{ $read_config->{_} } : ();
87    } elsif ( $args{vars} ) {
88        %stored = %{ $args{vars} };
89    }
90
91    # Set all defaults first, then set the stored values.  This allows us
92    # to make sure that the stored values override the defaults yet be sure
93    # to set any variables which have stored values but not defaults.
94    foreach my $var ( keys %defaults ) {
95        $self->$var( $defaults{$var} );
96    }
97    foreach my $var ( keys %stored ) {
98        if ( $self->can( $var ) ) { # handle any garbage in file gracefully
99            $self->$var( $stored{$var} );
100        } else {
101            warn "Don't know what to do with variable '$var'";
102        }
103    }
104
105    # And the questions.
106    # Don't forget to add to INSTALL when changing these.
107    my %questions = (
108        dbtype => "What type of database do you want the site to run on?  postgres/mysql/sqlite",
109        dbname => "What's the name of the database that this site runs on?",
110        dbuser => "...the database user that can access that database?",
111        dbpass => "...the password that they use to access the database?",
112        dbhost => "...the machine that the database is hosted on? (blank if local)",
113        script_name => "What do you want the script to be called?",
114        install_directory => "What directory should I install it in?",
115        template_path => "What directory should I install the templates in?",
116        custom_template_path => "Where should I look for custom templates?",
117        script_url => "What URL does the install directory map to?",
118        custom_lib_path => "Do you want me to munge a custom lib path into the scripts?  If so, enter it here.  Separate path entries with whitespace.",
119        use_plucene => "Do you want to use Plucene for searching? (recommended, but see Changes file before saying yes to this if you are upgrading)",
120        indexing_directory => "What directory can I use to store indexes in for searching? ***NOTE*** This directory must exist and be writeable by the user that your script will run as.  See README for more on this.",
121        enable_page_deletion => "Do you want to enable page deletion?",
122        admin_pass => "Please specify a password for the site admin.",
123        stylesheet_url => "What's the URL of the site's stylesheet?",
124        site_name => "What's the site called? (should be unique)",
125        navbar_on_home_page => "Do you want the navigation bar included on the home page?",
126        home_name => "What should the home page of the wiki be called?",
127        site_desc => "How would you describe the site?",
128        default_city => "What city is the site based in?",
129        default_country => "What country is the site based in?",
130        contact_email => "Contact email address for the site administrator?",
131        default_language => "What language will the site be in? (Please give an ISO language code.)",
132        formatting_rules_node => "What's the name of the node or page to use for the text formatting rules link (this is by default an external document, but if you make formatting_rules_link empty, it will be a wiki node instead",
133        formatting_rules_link => "What URL do you want to use for the text formatting rules (leave blank to use a wiki node instead)?",
134        backlinks_in_title => "Make node titles link to node backlinks (C2 style)?",
135        ellipsoid => "Which ellipsoid do you want to use? (eg 'Airy', 'WGS-84')",
136    );
137
138    foreach my $var ( keys %questions ) {
139        my $method = $var . "__qu";
140        $self->$method( $questions{$var} );
141    }
142
143    return $self;
144}
145
146=back
147
148=head1 ACCESSORS
149
150Each of the accessors described below is read-write.  Additionally,
151for each of them, there is also a read-write accessor called, for
152example, C<dbname__qu>.  This will contain an English-language
153question suitable for asking for a value for that variable.  You
154shouldn't write to them, but this is not enforced.
155
156The defaults mentioned below are those which are applied when
157C<< ->new >> is called, to variables which are not supplied in
158the config file.
159
160=over
161
162=item * dbname
163
164=item * dbuser
165
166=item * dbpass
167
168=item * dbhost
169
170=item * script_name (default: C<wiki.cgi>)
171
172=item * install_directory (default: C</usr/lib/cgi-bin/openguides/>)
173
174=item * script_url (this is constrained to always end in C</>)
175
176=cut
177
178sub script_url {
179    my $self = shift;
180    # See perldoc Class::Accessor - can't just use SUPER.
181    my $url = $self->_script_url_accessor( @_ );
182    $url .= "/" unless $url =~ /\/$/;
183    return $url;
184}
185
186=item * custom_lib_path
187
188=item * use_plucene (default: true)
189
190=item * indexing_directory (default: C</usr/lib/cgi-bin/openguides/indexes>)
191
192=item * enable_page_deletion (default: false)
193
194=item * admin_pass (default: C<Change This!>)
195
196=item * stylesheet_url
197
198=item * site_name (default: C<Unconfigured OpenGuides site>)
199
200=item * navbar_on_home_page (default: true)
201
202=item * home_name (default: C<Home>)
203
204=item * site_desc (default: C<A default configuration of OpenGuides>)
205
206=item * default_city (default: C<London>)
207
208=item * default_country (default: C<United Kingdom>)
209
210=item * default_language (default: C<en>)
211
212=item * contact_email
213
214=item * formatting_rules_node (default: C<Text Formatting Examples>)
215
216=item * formatting_rules_link (default: C<http://openguides.org/page/text_formatting>
217
218=item * backlinks_in_title (default: false)
219
220=item * geo_handler (default: C<1>)
221
222=item * ellipsoid (default: C<International>)
223
224=back
225
226=head1 AUTHOR
227
228The OpenGuides Project (openguides-dev@openguides.org)
229
230=head1 COPYRIGHT
231
232     Copyright (C) 2004 The OpenGuides Project.  All Rights Reserved.
233
234The OpenGuides distribution is free software; you can redistribute it
235and/or modify it under the same terms as Perl itself.
236
237=head1 SEE ALSO
238
239L<OpenGuides>
240
241=cut
242
2431;
Note: See TracBrowser for help on using the repository browser.