added recipe for configuration files

mojolicious · Feb 10, 2014 · ed9cb42 · ed9cb42
1 parent 2aea4bf
commit ed9cb42
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 13 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,5 @@
 
-4.79  2014-02-10
+4.79  2014-02-11
   - Improved not found page to show the exact path used for route matching.
 
 4.78  2014-02-08
@@ -888,8 +888,8 @@
 3.35  2012-08-28
   - Deprecated Mojolicious::Controller::render_content in favor of content
     helper.
-  - Improved Mojolicious::Plugin::Config to accept mode specific config files
-    without a normal config file. (alexbyk, sri)
+  - Improved Mojolicious::Plugin::Config to accept mode specific configuration
+    files without a normal configuration file. (alexbyk, sri)
 
 3.34  2012-08-24
   - Improved documentation.
@@ -1025,11 +1025,12 @@
   - Fixed small Mojo::Template bug.
 
 3.07  2012-07-13
-  - Improved template error messages for generator commands and config files.
+  - Improved template error messages for generator commands and configuration
+    files.
   - Fixed small bug in Mojolicious::Plugin::EPRenderer that prevented code to
     be added to templates.
   - Fixed small bug in Mojolicious::Plugin::JSONConfig that prevented code to
-    be added to config files.
+    be added to configuration files.
 
 3.06  2012-07-11
   - Added tls_verify option to Mojo::IOLoop::Server::listen. (scottw)
@@ -1140,7 +1141,7 @@
   - Added remove method to Mojolicious::Routes::Route.
   - Improved 32bit Perl support of Mojo::Transaction::WebSocket.
     (mikemagowan, sri)
-  - Improved exception handling of application and config file loaders.
+  - Improved exception handling of application and configuration file loaders.
   - Improved exception handling of Mojolicious::Plugin::I18N.
   - Improved renderer log messages.
   - Fixed bug that prevented helper names from starting with "end". (Akron)

diff --git a/lib/Mojolicious/Guides/Rendering.pod b/lib/Mojolicious/Guides/Rendering.pod
@@ -1006,6 +1006,40 @@ plugin.
   @@ alertassets.html.ep
   %= javascript "/alertassets.js"
 
+=head2 Adding a configuration file
+
+Adding a configuration file to your application is as easy as adding a file to
+its home directory and loading the plugin L<Mojolicious::Plugin::Config>. The
+default name is the same as that of your application script (C<myapp.pl>), but
+with a C<.conf> extension (C<myapp.conf>).
+
+  $ echo '{name => "my Mojolicious application"};' > myapp.conf
+
+Configuration files themselves are just Perl scripts that return a hash
+reference, all settings are available through the method L<Mojo/"config"> and
+the helper L<Mojolicious::Plugin::DefaultHelpers/"config">
+
+  use Mojolicious::Lite;
+
+  plugin 'Config';
+
+  my $name = app->config('name');
+  app->log->debug("Welcome to $name.");
+
+  get '/' => 'with_config';
+
+  app->start;
+  __DATA__
+  @@ with_config.html.ep
+  <!DOCTYPE html>
+  <html>
+    <head><title><%= config 'name' %></title></head>
+    <body>Welcome to <%= config 'name' %></body>
+  </html>
+
+Alternatively you can also have configuration files in the JSON format with
+L<Mojolicious::Plugin::JSONConfig>.
+
 =head1 ADVANCED
 
 Less commonly used and more powerful features.

diff --git a/lib/Mojolicious/Plugin/Config.pm b/lib/Mojolicious/Plugin/Config.pm
@@ -6,7 +6,7 @@ use Mojo::Util qw(decode slurp);
 
 sub load {
   my ($self, $file, $conf, $app) = @_;
-  $app->log->debug(qq{Reading config file "$file".});
+  $app->log->debug(qq{Reading configuration file "$file".});
   return $self->parse(decode('UTF-8', slurp $file), $file, $conf, $app);
 }
 
@@ -18,7 +18,7 @@ sub parse {
     = eval 'package Mojolicious::Plugin::Config::Sandbox; no warnings;'
     . "sub app; local *app = sub { \$app }; use Mojo::Base -strict; $content";
   die qq{Couldn't load configuration from file "$file": $@} if !$config && $@;
-  die qq{Config file "$file" did not return a hash reference.\n}
+  die qq{Configuration file "$file" did not return a hash reference.\n}
     unless ref $config eq 'HASH';
 
   return $config;
@@ -45,7 +45,7 @@ sub register {
 
   # Check for default and mode specific config file
   elsif (!$conf->{default} && !$mode) {
-    die qq{Config file "$file" missing, maybe you need to create it?\n};
+    die qq{Configuration file "$file" missing, maybe you need to create it?\n};
   }
 
   # Merge everything

diff --git a/lib/Mojolicious/Plugin/JSONConfig.pm b/lib/Mojolicious/Plugin/JSONConfig.pm
@@ -72,9 +72,9 @@ L<Mojolicious::Plugin::JSONConfig> is a JSON configuration plugin that
 preprocesses its input with L<Mojo::Template>.
 
 The application object can be accessed via C<$app> or the C<app> function. You
-can extend the normal config file C<myapp.json> with C<mode> specific ones
-like C<myapp.$mode.json>. A default configuration filename will be generated
-from the value of L<Mojolicious/"moniker">.
+can extend the normal configuration file C<myapp.json> with C<mode> specific
+ones like C<myapp.$mode.json>. A default configuration filename will be
+generated from the value of L<Mojolicious/"moniker">.
 
 The code of this plugin is a good example for learning to build new plugins,
 you're welcome to fork it.

diff --git a/t/mojolicious/json_config_lite_app.t b/t/mojolicious/json_config_lite_app.t
@@ -25,7 +25,7 @@ my $cb = app->log->on(message => sub { $log .= pop });
 my $path
   = abs_path(catfile(dirname(__FILE__), 'json_config_lite_app_abs.json'));
 plugin JSONConfig => {file => $path};
-like $log, qr/Reading config file "\Q$path\E"\./, 'right message';
+like $log, qr/Reading configuration file "\Q$path\E"\./, 'right message';
 app->log->unsubscribe(message => $cb);
 is $config->{foo},          'bar',            'right value';
 is $config->{hello},        'there',          'right value';