diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index 3f689e29b..e81ca2d90 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -20,13 +20,16 @@ way, easily. =head1 INSTALL -Installation of Dancer2 is simple: +Since Dancer2 is available on the Comprehensive Perl Archive Network (CPAN), +the authoritative repository for Perl modules, Dancer 2 can be installed with +one simple command. If you are familiar with Perl and use it, you probably +already have L configured on your machine and can install Dancer 2 with: perl -MCPAN -e 'install Dancer2' -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: +But, if you are newer to Perl, you may not have L configured. No worries. +Thanks to the magic of the L module, you can get up and running +quickly on Unix-like systems with the following: wget -O - http://cpanmin.us | sudo perl - Dancer2 @@ -35,9 +38,13 @@ Dancer2 and prereqs into C<~/perl5>.) =head1 BOOTSTRAPPING A NEW APP -Create a web application using the dancer script: +The Dancer 2 distribution includes a script called L which you can use +to automatically generate a new web application from the command line, like so: $ dancer2 -a MyApp && cd MyApp + +You will then see the following output: + + MyApp + MyApp/config.yml + MyApp/Makefile.PL @@ -73,12 +80,36 @@ Create a web application using the dancer script: + MyApp/views/layouts + MyApp/views/layouts/main.tt -It creates a directory named after the name of the app, along with a -configuration file, a views directory (where your templates and layouts -will live), an environments directory (where environment-specific -settings live), a module containing the actual guts of your application, and -a script to start it. A default skeleton is used to bootstrap the new -application, but you can use the C<-s> option to provide another skeleton. +The L script creates the following: + +=over + +=item * +a directory named after the name of the app, L in this case + +=item a configuration file, F. + +=item a F directory (where your templates and layouts will live), + +=item F directory (where environment-specific settings live), + +=item F directory (where static assets like css file and javascrpt files can +go) + +=item F directory (where your tests can go) + +=item a variety of files for helping you build your application into a +module for release + +=item a module containing the actual guts of your application in L + +=item a script to start your appliaction in L. + +=back + +A default skeleton is used to generate the new application. You can use +the C<-s> option to provide another skeleton. + For example: $ dancer2 -a MyApp -s ~/mydancerskel @@ -95,23 +126,45 @@ C tool (provided by L) for launching the application: plackup -p 5000 bin/app.psgi -View the web application at: +You can then access the web application with your favorite browser at: http://localhost:5000 =head1 USAGE -When Dancer2 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 B. A -route handler is composed by an HTTP method, a path pattern and a code -block. C, C and C pragmas are also imported with -Dancer2. +When Dancer2 is imported to a script with L, that script +becomes a Dancer 2 web app. First, the C, C and C +pragmas are injected into the script by Dancer 2. The import function of the +script is also modified so that Dancer 2's keywords can be imported and used by +the script. + +Now, all the script needs to do is declare its B. A route +handler is a list of three elements: a Dancer 2 keyword for the HTTP method, +a path pattern, and a block of code. For example, here is a simple route handler: + + get '/' => sub { return 'Hello World!'; }; + +Here, the HTTP method is C, the pattern to match is C, which is the root +directory of the website. When a browser visits C with a C request, +the string 'Hello World!' generated by our block of code will be sent back in the +response to the browser. 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. +be used as the content to render for the client. + +Each route handler you create inside of your script is stored in your app so +your app can handle the requests as they come in. + +You can make your route handler dynamic with parameters. As a simple example: -Routes are defined for a given HTTP method. For each method supported, a -keyword is exported by the module. + get '/hello/:name' => sub { + return "Hi there " . route_parameters->get('name'); + }; + +This will create a page that greets the visitor with the string of text that +follows C in the path. More typically, parameters are use to +query a database or determine which page to show. See the +L for more details on route patterns. =head2 HTTP Methods @@ -122,27 +175,30 @@ route handlers. =item * B The GET method retrieves information, and is the most common -GET requests should be used for typical "fetch" requests - retrieving -information. They should not be used for requests which change data on the -server or have other effects. +GET requests are typically used as "fetch" requests to retreive information. +They should not be used for requests which change data on the server or +have other side effects. -When defining a route handler for the GET method, Dancer2 automatically -defines a route handler for the HEAD method (in order to honour HEAD -requests for each of your GET route handlers). +When defining GET route hander, Dancer2 also 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 L keyword. =item * B The POST method is used to create a resource on the server. +POST requests are typically used to submit data to the web application. The +most common example is by sending data from an HTML form. + To define a POST action, use the L keyword. =item * B The PUT method is used to replace an existing resource. To define a PUT action, use the L keyword. -a PUT request should replace the existing resource with that specified - for -instance - if you wanted to just update an email address for a user, you'd -have to specify all attributes of the user again; to make a partial update, +A PUT request should replace the existing resource with that specified. For +instance, if you wanted to just update an email address for a user, you'd +have to specify all attributes of the user again. To make a partial update, a PATCH request is used. =item * B The PATCH method updates some attributes of an existing resource. @@ -172,51 +228,38 @@ The following will match GET or POST requests to C: # code }; -For convenience, any route which matches GET requests will also match HEAD -requests. - -=head2 Route Handlers +As mentioned previously, any route which matches GET requests will also +match HEAD requests. This is just convenience for web app developers. -The route action is the code reference declared. It can access parameters -through the specific C, C, and -C keywords, which return a L object. -This hashref is a merge of the route pattern matches and the request params. +=head2 Route Patterns -You can have more details about how params are built and how to access them -in the L documentation. +After the declaration of the HTTP method, your route handler must supply +a pattern that will be used to match against the path of the incoming request. -=head3 Declaring Routes +The simplest route patterns provide an exact match to the requested path: -To control what happens when a web request is received by your webapp, -you'll need to declare C. A route declaration indicates which HTTP -method(s) it is valid for, the path it matches (e.g. C), and a -coderef to execute, which returns the response. - - get '/hello/:name' => sub { - return "Hi there " . route_parameters->get('name'); - }; - -The above route specifies that, for GET requests to C, the code -block provided should be executed. + get '/foo/bar' => sub { + return 'You are on page /foo/bar'; + } -=head3 Retrieving request parameters +This route will be activated when a client requests the C) path. -The L, -L, and -L keywords provide -a L result from the three different parameters. +Your route patterns can be much more sophisticated and be used to create +parameters to pass data into your action. More advanced types of route +patterns are described below. =head3 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 route parameters. +match will be found in the C variable and can be retrieved +in the block of code. get '/hello/:name' => sub { "Hey " . route_parameters->get('name') . ", welcome here!"; }; -Tokens can be optional, for example: +Tokens can be optional by tacking a question mark to the end of it, for example: get '/hello/:name?' => sub { my $name = route_parameters->get('name') //= 'Whoever you are'; @@ -295,6 +338,29 @@ user_agent, content_length and path_info): 'all browsers except songbird' } +=head2 Route Action + +The route action is the code reference in the route handler which follows the +HTTP method and the route pattern. As we saw in the previous section, your +action can access parameters through the specific C, +C, and C keywords, which return a +L object. This hashref is a merge of the route pattern +matches and the request params. + +=head3 Retrieving request parameters + +As we saw in the previous section, your action can access parameters through +the specific C, C, and C +keywords, which together return a L object. This hashref is +a combination of the route pattern matches and the request params. + +For more information on these types of parameters, see the L, +L, and +L documentation. + +More details about how params are built and how to access them are available +in the L documentation. + =head2 Prefix A prefix can be defined for each route handler, like this: