source: trunk/lib/OpenGuides/Config.pm

Last change on this file was 1395, checked in by bob, 9 years ago

merge changes from release branch

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.6 KB
Line 
1package OpenGuides::Config;
2use strict;
3use warnings;
4
5use vars qw( $VERSION );
6$VERSION = '0.07';
7
8use Carp qw( croak );
9use Config::Tiny;
10
11use base qw( Class::Accessor );
12my @variables = qw(
13   dbtype dbname dbuser dbpass dbport dbhost dbencoding
14   script_name install_directory script_url
15   custom_lib_path use_plucene indexing_directory enable_page_deletion
16   admin_pass stylesheet_url site_name navbar_on_home_page
17   recent_changes_on_home_page random_page_omits_locales
18   random_page_omits_categories content_above_navbar_in_html home_name
19   site_desc default_city default_country contact_email
20   default_language http_charset ping_services
21   formatting_rules_node formatting_rules_link backlinks_in_title template_path
22   custom_template_path geo_handler ellipsoid gmaps_api_key centre_long
23   show_gmap_in_node_display google_analytics_key use_leaflet
24   centre_lat default_gmaps_zoom default_gmaps_search_zoom force_wgs84
25   licence_name licence_url licence_info_url
26   moderation_requires_password moderate_whitelist
27   enable_node_image enable_common_categories enable_common_locales
28   spam_detector_module host_checker_module static_path static_url
29   send_moderation_notifications website_link_max_chars read_only
30);
31my @questions = map { $_ . "__qu" } @variables;
32OpenGuides::Config->mk_accessors( @variables );
33OpenGuides::Config->mk_accessors( @questions );
34
35=head1 NAME
36
37OpenGuides::Config - Handle OpenGuides configuration variables.
38
39=head1 DESCRIPTION
40
41Does config stuff for OpenGuides.  Distributed and installed as part of
42the OpenGuides project, not intended for independent installation.
43This documentation is probably only useful to OpenGuides developers.
44
45=head1 METHODS
46
47=over
48
49=item B<new>
50
51  my $config = OpenGuides::Config->new( file => "wiki.conf" );
52
53Initialises itself from the config file specified.  Variables which
54are not set in that file, and which have sensible defaults, will be
55initialised as described below in ACCESSORS; others will be given a
56value of C<undef>.
57
58  my $config = OpenGuides::Config->new( vars => { dbname => "foo" } );
59
60As above but gets variables from a supplied hashref instead.
61
62=cut
63
64sub new {
65    my $class = shift;
66    my $self = { };
67    bless $self, $class;
68    return $self->_init( @_ );
69}
70
71sub _init {
72    my ($self, %args) = @_;
73
74    # Here are the defaults for the variable values.
75    # Don't forget to add to INSTALL when changing these.
76    my %defaults = (
77                     dbtype => "sqlite",
78                     script_name => "wiki.cgi",
79                     install_directory => "/usr/lib/cgi-bin/openguides/",
80                     use_plucene => 1,
81                     indexing_directory => "/usr/lib/cgi-bin/openguides/indexes/",
82                     enable_page_deletion => 0,
83                     moderation_requires_password => 1,
84                     moderate_whitelist => "",
85                     admin_pass => "Change This!",
86                     enable_node_image => 1,
87                     enable_common_categories => 0,
88                     enable_common_locales => 0,
89                     ping_services => "",
90                     site_name => "Unconfigured OpenGuides site",
91                     navbar_on_home_page => 1,
92                     recent_changes_on_home_page => 1,
93                     random_page_omits_locales => 0,
94                     random_page_omits_categories => 0,
95                     content_above_navbar_in_html => 0,
96                     home_name => "Home",
97                     site_desc => "A default configuration of OpenGuides",
98                     default_city => "",
99                     default_country => "",
100                     default_language => "en",
101                     http_charset => "",
102                     formatting_rules_node => "Text Formatting Examples",
103                     formatting_rules_link => "http://openguides.org/text_formatting",
104                     backlinks_in_title => 0,
105                     geo_handler => 1,
106                     ellipsoid => "WGS-84",
107                     use_leaflet => 0,
108                     show_gmap_in_node_display => 1,
109                     centre_long => 0,
110                     centre_lat => 0,
111                     default_gmaps_zoom => 5,
112                     default_gmaps_search_zoom => 3,
113                     force_wgs84 => 0,
114                     licence_name => "",
115                     licence_url => "",
116                     licence_info_url => "",
117                     spam_detector_module => "",
118                     host_checker_module => "",
119                     static_path => "/usr/local/share/openguides/static",
120                     send_moderation_notifications => 1,
121                     website_link_max_chars => 25,
122                     read_only => 0,
123                   );
124
125    # See if we already have some config variables set.
126    my %stored;
127    if ( $args{file} ) {
128        my $read_config = Config::Tiny->read( $args{file} ) or
129            croak "Cannot read config file '$args{file}': $Config::Tiny::errstr";
130        %stored = %{$read_config->{_}};
131    } elsif ( $args{vars} ) {
132        %stored = %{ $args{vars} };
133    }
134
135    # Set all defaults first, then set the stored values.  This allows us
136    # to make sure that the stored values override the defaults yet be sure
137    # to set any variables which have stored values but not defaults.
138    foreach my $var ( keys %defaults ) {
139        $self->$var( $defaults{$var} );
140    }
141    foreach my $var ( keys %stored ) {
142        if ( $self->can( $var ) ) { # handle any garbage in file gracefully
143            $self->$var( $stored{$var} );
144        } else {
145            warn "Don't know what to do with variable '$var'";
146        }
147    }
148
149    # And the questions.
150    # Don't forget to add to INSTALL when changing these.
151    my %questions = (
152        dbtype => "What type of database do you want the site to run on?  postgres/mysql/sqlite",
153        dbname => "What's the name of the database that this site runs on?",
154        dbuser => "...the database user that can access that database?",
155        dbpass => "...the password that they use to access the database?",
156        dbhost => "...the machine that the database is hosted on? (blank if local)",
157        dbport => "...the port the database is listening on? (blank if default)",
158        dbencoding => "...the encoding that your database uses? (blank if default)",
159        script_name => "What do you want the script to be called?",
160        install_directory => "What directory should I install it in?",
161        template_path => "What directory should I install the templates in?",
162        custom_template_path => "Where should I look for custom templates?",
163        script_url => "What URL does the install directory map to?",
164        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.",
165        use_plucene => "Do you want to use Plucene for searching? (recommended, but see Changes file before saying yes to this if you are upgrading)",
166        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.",
167        enable_page_deletion => "Do you want to enable page deletion?",
168        moderation_requires_password => "Is the admin password required for moderating pages?",
169        admin_pass => "Please specify a password for the site admin.",
170        stylesheet_url => "What's the URL of the site's stylesheet?  If you don't enter one here, the basic OpenGuides stylesheet will be used instead.",
171        enable_node_image => "Should nodes be allowed to have an externally hosted image?",
172        enable_common_categories => "Do you want a common list of categories shown on all node pages?",
173        enable_common_locales => "Do you want a common list of locales shown on all node pages?",
174        ping_services => "Which services do you wish to ping whenever you write a page? Can be pingerati, geourl, or both",
175        site_name => "What's the site called? (should be unique)",
176        navbar_on_home_page => "Do you want the navigation bar included on the home page?",
177        recent_changes_on_home_page => "Do you want the ten most recent changes included on the home page?",
178        random_page_omits_locales => "Do you want the \"Random Page\" link to avoid returning a locale page?",
179        random_page_omits_categories => "Do you want the \"Random Page\" link to avoid returning a category page?",
180        content_above_navbar_in_html => "Do you want the content to appear above the navbar in the HTML?",
181        home_name => "What should the home page of the wiki be called?",
182        site_desc => "How would you describe the site?",
183        default_city => "What city is the site based in?",
184        default_country => "What country is the site based in?",
185        contact_email => "Contact email address for the site administrator?",
186        default_language => "What language will the site be in? (Please give an ISO language code.)",
187        http_charset => "What character set should we put in the http headers? (This won't change the character set internally, just what it's reported as). Leave blank for none to be sent",
188        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",
189        formatting_rules_link => "What URL do you want to use for the text formatting rules (leave blank to use a wiki node instead)?",
190        backlinks_in_title => "Make node titles link to node backlinks (C2 style)?",
191        ellipsoid => "Which ellipsoid do you want to use? (eg 'Airy', 'WGS-84')",
192        use_leaflet => "Do you want to use the Leaflet mapping library? (this is recommended)",
193        gmaps_api_key => "Do you have a Google Maps API key to use with this guide? If so, enter it here. (Note: our Google Maps support is deprecated, and we recommend you choose to use Leaflet instead.)",
194        centre_long => "What is the longitude of the centre point of a map to draw for your guide? (This question can be ignored if you aren't using Google Maps - we recommend you use Leaflet instead, as our Leaflet code will figure this out for you.) You may paste in a Google Maps URL here (hint: copy URL from 'Link to this page')",
195        centre_lat => "What is the latitude of the centre point of a map to draw for your guide? (This question can be ignored if you aren't using Google Maps - we recommend you use Leaflet instead, as our Leaflet code will figure this out for you.)",
196        default_gmaps_zoom => "What default zoom level shall we use for Google Maps? (This question can be ignored if you aren't using Google Maps)",
197        default_gmaps_search_zoom => "What default zoom level shall we use for Google Maps in the search results? (This question can be ignored if you aren't using Google Maps)",
198        show_gmap_in_node_display => "Would you like to display a map on every node that has geodata?",
199        force_wgs84 => "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?",
200        google_analytics_key => "Do you have a Google Analytics key to use with this guide? If you enter it here, then Google Analytics functionality will be automatically enabled.",
201        licence_name => "What licence will you use for the guide?",
202        licence_url => "What is the URL to your licence?",
203        licence_info_url => "What is the URL to your local page about your licensing policy?",
204        spam_detector_module => "What module would you like to use for spam detection? (optional)",
205        host_checker_module => "What module would you like to use to run an IP blacklist? (optional)",
206        static_path => "What directory should we install static content (CSS, images, javascript) to?",
207        static_url => "What is the URL corresponding to the static content?",
208        send_moderation_notifications => "Should we send email notifications when a moderated node is edited?",
209        website_link_max_chars => "How many characters of the URL of node websites should be displayed?",
210        moderate_whitelist => "Enter a comma-separated list of IP addresses able to make changes to moderated nodes and have them show up immediately",
211        read_only => "Should the guide be read-only (no edits permitted)?",
212    );
213
214    foreach my $var ( keys %questions ) {
215        my $method = $var . "__qu";
216        $self->$method( $questions{$var} );
217    }
218
219    return $self;
220}
221
222=back
223
224=head1 ACCESSORS
225
226Each of the accessors described below is read-write.  Additionally,
227for each of them, there is also a read-write accessor called, for
228example, C<dbname__qu>.  This will contain an English-language
229question suitable for asking for a value for that variable.  You
230shouldn't write to them, but this is not enforced.
231
232The defaults mentioned below are those which are applied when
233C<< ->new >> is called, to variables which are not supplied in
234the config file.
235
236=over
237
238=item * dbname
239
240=item * dbuser
241
242=item * dbpass
243
244=item * dbhost
245
246=item * dbport
247
248=item * dbencoding
249
250=item * script_name (default: C<wiki.cgi>)
251
252=item * install_directory (default: C</usr/lib/cgi-bin/openguides/>)
253
254=item * script_url (this is constrained to always end in C</>)
255
256=cut
257
258sub script_url {
259    my $self = shift;
260    # See perldoc Class::Accessor - can't just use SUPER.
261    my $url = $self->_script_url_accessor( @_ );
262    $url .= "/" unless (defined $url && $url =~ /\/$/);
263    return $url;
264}
265
266=item * custom_lib_path
267
268=item * use_plucene (default: true)
269
270=item * indexing_directory (default: C</usr/lib/cgi-bin/openguides/indexes>)
271
272=item * enable_page_deletion (default: false)
273
274=item * admin_pass (default: C<Change This!>)
275
276=item * stylesheet_url
277
278=item * site_name (default: C<Unconfigured OpenGuides site>)
279
280=item * navbar_on_home_page (default: true)
281
282=item * recent_changes_on_home_page (default: true)
283
284=item * random_page_omits_locales (default: false)
285
286=item * random_page_omits_categories (default: false)
287
288=item * content_above_navbar_in_html (default: false)
289
290=item * home_name (default: C<Home>)
291
292=item * site_desc (default: C<A default configuration of OpenGuides>)
293
294=item * default_city (default: C<London>)
295
296=item * default_country (default: C<United Kingdom>)
297
298=item * default_language (default: C<en>)
299
300=item * http_charset
301
302=item * contact_email
303
304=item * formatting_rules_node (default: C<Text Formatting Examples>)
305
306=item * formatting_rules_link (default: C<http://openguides.org/text_formatting>
307
308=item * backlinks_in_title (default: false)
309
310=item * geo_handler (default: C<1>)
311
312=item * ellipsoid (default: C<WGS-84>)
313
314=item * use_leaflet
315
316=item * gmaps_api_key
317
318=item * centre_long
319
320=item * centre_lat
321
322=item * default_gmaps_zoom
323
324=item * default_gmaps_search_zoom
325
326=item * show_gmap_in_node_display
327
328=item * force_wgs84
329
330=item * google_analytics_key
331
332=item * licence_name
333
334=item * licence_url
335
336=item * licence_info_url
337
338=item * spam_detector_module
339
340=item * host_checker_module
341
342=item * static_path
343
344=item * static_url (this is constrained to always end in C</>)
345
346=cut
347
348sub static_url {
349    my $self = shift;
350    # See perldoc Class::Accessor - can't just use SUPER.
351    my $url = $self->_static_url_accessor( @_ );
352    $url .= "/" unless (defined $url && $url =~ /\/$/);
353    return $url;
354}
355
356=item * send_moderation_notifications
357
358=item * moderate_whitelist
359
360=item * website_link_max_chars (default: C<25>)
361
362=item * read_only
363
364=back
365
366=head1 AUTHOR
367
368The OpenGuides Project (openguides-dev@lists.openguides.org)
369
370=head1 COPYRIGHT
371
372     Copyright (C) 2004-2012 The OpenGuides Project.  All Rights Reserved.
373
374The OpenGuides distribution is free software; you can redistribute it
375and/or modify it under the same terms as Perl itself.
376
377=head1 SEE ALSO
378
379L<OpenGuides>
380
381=cut
382
3831;
Note: See TracBrowser for help on using the repository browser.