Dancer::Introduction man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Dancer::Introduction(3User Contributed Perl DocumentatiDancer::Introduction(3)

NAME
       Dancer::Introduction - A gentle introduction to Dancer

DESCRIPTION
       Dancer is a free and open source micro web application framework
       written in Perl.

INSTALL
       Installation of Dancer is simple:

	   perl -MCPAN -e 'install Dancer'

       Thanks to the magic of cpanminus, if you do not have CPAN.pm
       configured, or just want a quickfire way to get running, the following
       should work, at least on Unix-like systems:

	   wget -O - http://cpanmin.us | sudo perl - Dancer

       (If you don't have root access, omit the 'sudo', and cpanminus will
       install Dancer and prereqs into "~/perl5".)

SETUP
       Create a web application using the dancer script:

	   dancer -a MyApp

       Run the web application:

	   cd MyApp
	   bin/app.pl

       You can read the output of "bin/app.pl --help" to change any settings
       such as the port number.

       View the web application at:

	   http://localhost:3000

USAGE
       When Dancer is imported to a script, that script becomes a webapp, and
       at this point, all the script has to do is declare a list of routes.  A
       route handler is composed by an HTTP method, a path pattern and a code
       block.  "strict" and "warnings" pragmas are also imported with Dancer.

       The code block given to the route handler has to return a string which
       will be used as the content to render to the client.

       Routes are defined for a given HTTP method. For each method supported,
       a keyword is exported by the module.

       The following is an example of a route definition. The route is defined
       for the method 'get', so only GET requests will be honoured by that
       route:

	   get '/hello/:name' => sub {
	       # do something

	       return "Hello ".params->{name};
	   };

   HTTP METHODS
       Here are some of the standard HTTP methods which you can use to define
       your route handlers.

       GET	  The GET method retrieves information (when defining a route
       handler for the GET method, Dancer automatically defines a route
       handler for the HEAD method, in order to honour HEAD requests for each
       of your GET route handlers). To define a GET action, use the get
       keyword.
       POST	  The POST method is used to create a resource on the server.
       To define a POST action, use the post keyword.
       PUT	  The PUT method is used to update an existing resource. To
       define a PUT action, use the put keyword.
       DELETE	  The DELETE method requests that the origin server delete the
       resource identified by the Request-URI. To define a DELETE action, use
       the del keyword.

       To define a route for multiple methods you can also use the special
       keyword any. This example illustrates how to define a route for both
       GET and POST methods:

	   any ['get', 'post'] => '/myaction' => sub {
	       # code
	   };

       Or even, a route handler that would match any HTTP methods:

	   any '/myaction' => sub {
	       # code
	   };

   ROUTE HANDLERS
       The route action is the code reference declared. It can access
       parameters through the `params' keyword, which returns a hashref.  This
       hashref is a merge of the route pattern matches and the request params.

       You can have more details about how params are built and how to access
       them in the Dancer::Request documentation.

   NAMED MATCHING
       A route pattern can contain one or more tokens (a word prefixed with
       ':'). Each token found in a route pattern is used as a named-pattern
       match. Any match will be set in the params hashref.

	   get '/hello/:name' => sub {
	       "Hey ".params->{name}.", welcome here!";
	   };

       Tokens can be optional, for example:

	   get '/hello/:name?' => sub {
	       "Hello there " . params->{name} || "whoever you are!";
	   };

   WILDCARDS MATCHING
       A route can contain a wildcard (represented by a '*'). Each wildcard
       match will be returned in an arrayref, accessible via the `splat'
       keyword.

	   get '/download/*.*' => sub {
	       my ($file, $ext) = splat;
	       # do something with $file.$ext here
	   };

   REGULAR EXPRESSION MATCHING
       A route can be defined with a Perl regular expression.

       In order to tell Dancer to consider the route as a real regexp, the
       route must be defined explicitly with "qr{}", like the following:

	   get qr{/hello/([\w]+)} => sub {
	       my ($name) = splat;
	       return "Hello $name";
	   };

   CONDITIONAL MATCHING
       Routes may include some matching conditions (on the useragent and the
       hostname at the moment):

	   get '/foo', {agent => 'Songbird (\d\.\d)[\d\/]*?'} => sub {
	     'foo method for songbird'
	   }

	   get '/foo' => sub {
	     'all browsers except songbird'
	   }

   PREFIX
       A prefix can be defined for each route handler, like this:

	   prefix '/home';

       From here, any route handler is defined to /home/*

	   get '/page1' => sub {}; # will match '/home/page1'

       You can unset the prefix value

	   prefix '/'; # or: prefix undef;
	   get '/page1' => sub {}; will match /page1

       Alternatively, to prevent you from ever forgetting to undef the prefix,
       you can use lexical prefix like this:

	   prefix '/home' => sub {
	     get '/page1' => sub {}; # will match '/home/page1'
	   }; ## prefix reset to previous value on exit

	   get '/page1' => sub {}; will match /page1

ACTION SKIPPING
       An action can choose not to serve the current request and ask Dancer to
       process the request with the next matching route.

       This is done with the pass keyword, like in the following example

	   get '/say/:word' => sub {
	       return pass if (params->{word} =~ /^\d+$/);
	       "I say a word: ".params->{word};
	   };

	   get '/say/:number' => sub {
	       "I say a number: ".params->{number};
	   };

   DEFAULT ERROR PAGES
       When an error is rendered (the action responded with a status code
       different than 200), Dancer first looks in the public directory for an
       HTML file matching the error code (eg: 500.html or 404.html).

       If such a file exists, it's used to render the error, otherwise, a
       default error page will be rendered on the fly.

   EXECUTION ERRORS
       When an error occurs during the route execution, Dancer will render an
       error page with the HTTP status code 500.

       It's possible either to display the content of the error message or to
       hide it with a generic error page.

       This is a choice left to the end-user and can be set with the
       show_errors setting.

       Note that you can also choose to consider all warnings in your route
       handlers as errors when the setting warnings is set to 1.

FILTERS
   Before filters
       Before filters are evaluated before each request within the context of
       the request and can modify the request and response. It's possible to
       define variables which will be accessible in the action blocks with the
       keyword 'var'.

	   before sub {
	       var note => 'Hi there';
	       request->path_info('/foo/oversee')
	   };

	   get '/foo/*' => sub {
	       my ($match) = splat; # 'oversee';
	       vars->{note}; # 'Hi there'
	   };

       For another example, this can be used along with session support to
       easily give non-logged-in users a login page:

	   before sub {
	       if (!session('user') && request->path_info !~ m{^/login}) {
		   # Pass the original path requested along to the handler:
		   var requested_path => request->path_info;
		   request->path_info('/login');
	       }
	   };

       The request keyword returns the current Dancer::Request object
       representing the incoming request. See the documentation of the
       Dancer::Request module for details.

   After filters
       "after" filters are evaluated after the response has been built by a
       route handler, and can alter the response itself, just before it's sent
       to the client.

       The filter is given the response object as its first argument:

	   after sub {
	       my $response = shift;
	       $response->{content} = 'after filter got here!';
	   };

   Before template filters
       "before_template" hooks are called whenever a template is going to be
       processed, they are passed the tokens hash which they can alter.

	   before_template sub {
	       my $tokens = shift;
	       $tokens->{foo} = 'bar';
	   }

       The tokens hash will then be passed to the template with all the
       modifications performed by the filter. This is a good way to setup some
       global vars you like to have in all your templates, like the name of
       the user logged in or a section name.

CONFIGURATION AND ENVIRONMENTS
       Configuring a Dancer application can be done in many ways. The easiest
       one (and maybe the dirtiest) is to put all your settings statements at
       the top of your script, before calling the dance() method.

       Other ways are possible, you can write all your setting calls in the
       file `appdir/config.yml'. For this, you must have installed the YAML
       module, and of course, write the conffile in YAML.

       That's better than the first option, but it's still not perfect as you
       can't switch easily from an environment to another without rewriting
       the config.yml file.

       The better way is to have one config.yml file with default global
       settings, like the following:

	   # appdir/config.yml
	   logger: 'file'
	   layout: 'main'

       And then write as many environment files as you like in
       appdir/environments.  That way, the appropriate	environment config
       file will be loaded according to the running environment (if none is
       specified, it will be 'development').

       Note that you can change the running environment using the
       --environment commandline switch.

       Typically, you'll want to set the following values in a development
       config file:

	   # appdir/environments/development.yml
	   log: 'debug'
	   startup_info: 1
	   show_errors:	 1

       And in a production one:

	   # appdir/environments/production.yml
	   log: 'warning'
	   startup_info: 0
	   show_errors:	 0

   load
       You can use the load method to include additional routes into your
       application:

	   get '/go/:value', sub {
	       # foo
	   };

	   load 'more_routes.pl';

	   # then, in the file more_routes.pl:
	   get '/yes', sub {
	       'orly?';
	   };

       load is just a wrapper for require, but you can also specify a list of
       routes files:

	   load 'login_routes.pl', 'session_routes.pl', 'misc_routes.pl';

   Accessing configuration data
       A Dancer application can access the information from its config file
       easily with the config keyword:

	   get '/appname' => sub {
	       return "This is " . config->{appname};
	   };

Importing just the syntax
       If you want to use more complex file hierarchies, you can import just
       the syntax of Dancer.

	   package App;

	   use Dancer;		  # App may contain generic routes
	   use App::User::Routes; # user-related routes

       Then in App/User/Routes.pm:

	   use Dancer ':syntax';

	   get '/user/view/:id' => sub {
	       ...
	   };

LOGGING
       It's possible to log messages sent by the application. In the current
       version, only one method is possible for logging messages but future
       releases may add additional logging methods, for instance logging to
       syslog.

       In order to enable the logging system for your application, you first
       have to start the logger engine in your config.yml

	   logger: 'file'

       Then you can choose which kind of messages you want to actually log:

	   log: 'debug'	    # will log debug, warning and errors
	   log: 'warning'   # will log warning and errors
	   log: 'error'	    # will log only errors

       A directory appdir/logs will be created and will host one logfile per
       environment. The log message contains the time it was written, the PID
       of the current process, the message and the caller information (file
       and line).

       To log messages, use the debug, warning and error methods, for
       instance:

	   debug "This is a debug message";

USING TEMPLATES
VIEWS
       It's possible to render the action's content with a template; this is
       called a view. The `appdir/views' directory is the place where views
       are located.

       You can change this location by changing the setting 'views', for
       instance if your templates are located in the 'templates' directory, do
       the following:

	   set views => path(dirname(__FILE__), 'templates');

       By default, the internal template engine is used
       (Dancer::Template::Simple) but you may want to upgrade to
       Template::Toolkit. If you do so, you have to enable this engine in your
       settings as explained in Dancer::Template::TemplateToolkit. If you do
       so, you'll also have to import the Template module in your application
       code. Note that Dancer configures the Template::Toolkit engine to use
       <% %> brackets instead of its default [% %] brackets, although you can
       change this in your config file.

       All views must have a '.tt' extension. This may change in the future.

       In order to render a view, just call the 'template' keyword at the end
       of the action by giving the view name and the HASHREF of tokens to
       interpolate in the view (note that the request, session and route
       params are automatically accessible in the view, named request, session
       and params):

	   use Dancer;
	   use Template;

	   get '/hello/:name' => sub {
	       template 'hello' => { number => 42 };
	   };

       And the appdir/views/hello.tt view can contain the following code:

	  <html>
	   <head></head>
	   <body>
	       <h1>Hello <% params.name %></h1>
	       <p>Your lucky number is <% number %></p>
	       <p>You are using <% request.user_agent %></p>
	       <% IF session.user %>
		   <p>You're logged in as <% session.user %></p>
	       <% END %>
	   </body>
	  </html>

   LAYOUTS
       A layout is a special view, located in the 'layouts' directory (inside
       the views directory) which must have a token named `content'. That
       token marks the place where to render the action view. This lets you
       define a global layout for your actions. Any tokens that you defined
       when you called the 'template' keyword are available in the layouts, as
       well as the standard session, request, and params tokens. This allows
       you to insert per-page content into the HTML boilerplate, such as page
       titles, current-page tags for navigation, etc.

       Here is an example of a layout: views/layouts/main.tt:

	   <html>
	       <head><% page_title %></head>
	       <body>
	       <div id="header">
	       ...
	       </div>

	       <div id="content">
	       <% content %>
	       </div>

	       </body>
	   </html>

       This layout can be used like the following:

	   use Dancer;
	   set layout => 'main';

	   get '/' => sub {
	       template 'index' => { page_title => "Your website Homepage" };
	   };

       Of course, if a layout is set, it can also be disabled for a specific
       action, like the following:

	   use Dancer;
	   set layout => 'main';

	   get '/nolayout' => sub {
	       template 'some_ajax_view',
		   { tokens_var => "42" },
		   { layout => 0 };
	   };

STATIC FILES
   STATIC DIRECTORY
       Static files are served from the ./public directory. You can specify a
       different location by setting the 'public' option:

	   set public => path(dirname(__FILE__), 'static');

       Note that the public directory name is not included in the URL. A file
       ./public/css/style.css is made available as example.com/css/style.css.

   STATIC FILE FROM A ROUTE HANDLER
       It's possible for a route handler to send a static file, as follows:

	   get '/download/*' => sub {
	       my $params = shift;
	       my ($file) = @{ $params->{splat} };

	       send_file $file;
	   };

       Or even if you want your index page to be a plain old index.html file,
       just do:

	   get '/' => sub {
	       send_file '/index.html'
	   };

SETTINGS
       It's possible to change quite every parameter of the application via
       the settings mechanism.

       A setting is key/value pair assigned by the keyword set:

	   set setting_name => 'setting_value';

       More usefully, settings can be defined in a YAML configuration file.
       Environment-specific settings can also be defined in environment-
       specific files (for instance, you don't want auto_reload in production,
       and might want extra logging in development).  See the cookbook for
       examples.

       See Dancer::Config for complete details about supported settings.

SERIALIZERS
       When writing a webservice, data serialization/deserialization is a
       common issue to deal with. Dancer can automatically handle that for
       you, via a serializer.

       When setting up a serializer, a new behaviour is authorized for any
       route handler you define: any non-scalar response will be rendered as a
       serialized string, via the current serializer.

       Here is an example of a route handler that will return a HashRef

	   use Dancer;
	   set serializer => 'JSON';

	   get '/user/:id/' => sub {
	       { foo => 42,
		 number => 100234,
		 list => [qw(one two three)],
	       }
	   };

       As soon as the content is not a scalar - and a serializer is set, which
       is not the case by default - Dancer renders the response via the
       current serializer.

       Hence, with the JSON serializer set, the route handler above would
       result in a content like the following:

	   {"number":100234,"foo":42,"list":["one","two","three"]}

       The following serializers are available, be aware they dynamically
       depend on Perl modules you may not have on your system.

       JSON
	   requires JSON

       YAML
	   requires YAML

       XML requires XML::Simple

       Mutable
	   will try to find the appropriate serializer using the Content-Type
	   and Accept-type header of the request.

EXAMPLE
       This is a possible webapp created with Dancer:

	   #!/usr/bin/perl

	   # make this script a webapp
	   use Dancer;

	   # declare routes/actions
	   get '/' => sub {
	       "Hello World";
	   };

	   get '/hello/:name' => sub {
	       "Hello ".params->{name}"
	   };

	   # run the webserver
	   Dancer->dance;

perl v5.14.1			  2011-07-26	       Dancer::Introduction(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net