From a079971d8013a0f1f0f27aac0675340f10a78df5 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Sun, 24 Dec 2017 22:49:21 -0500 Subject: [PATCH 1/6] make explanations a bit more accessible and clear and improve grammar and formatting --- lib/Dancer2/Manual.pod | 116 ++++++++++++++++++++++++++++++----------- 1 file changed, 87 insertions(+), 29 deletions(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index 3f689e29b..6b4951e06 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,52 @@ 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, l. + +=item * + +a L directory (where your templates and layouts will live), + +=item * + +an L directory (where environment-specific settings live), + +=item * + +a L directory (where static assets like css file and javascrpt files can +go) + +=item * + +a L 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,24 +142,32 @@ C tool (provided by L) for launching the application: plackup -p 5000 bin/app.psgi -View the web application at: +You can the 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 L, the pattern to match is L, or the root +directory of the website. When a browser visits L with a L request, +the string 'Hello World!' generated by our block of will be sent back in the +response. 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. - =head2 HTTP Methods Here are some of the standard HTTP methods which you can use to define your @@ -122,27 +177,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 "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. From 326d6b2dcb1d6a6d1be5f9529c05049e00a6b631 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Sun, 24 Dec 2017 22:55:14 -0500 Subject: [PATCH 2/6] fix typo --- lib/Dancer2/Manual.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index 6b4951e06..e8c395a73 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -142,7 +142,7 @@ C tool (provided by L) for launching the application: plackup -p 5000 bin/app.psgi -You can the access the web application with your favorite browser at: +You can then access the web application with your favorite browser at: http://localhost:5000 From 59fb06f66274bdb066ca6acc10cf7f2c5cd61494 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Mon, 25 Dec 2017 10:24:04 -0500 Subject: [PATCH 3/6] more improvements to the grammar, clarity and structure of the manual with regards to the basics of route handling --- lib/Dancer2/Manual.pod | 96 ++++++++++++++++++++++++++---------------- 1 file changed, 60 insertions(+), 36 deletions(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index e8c395a73..9afe98c19 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -158,15 +158,29 @@ 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!'; }; + get '/' => sub { return 'Hello World!'; }; -Here, the HTTP method is L, the pattern to match is L, or the root -directory of the website. When a browser visits L with a L request, -the string 'Hello World!' generated by our block of will be sent back in the -response. +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 simiple example: + + 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 @@ -177,7 +191,7 @@ route handlers. =item * B The GET method retrieves information, and is the most common -GET requests are typically used "fetch" requests to retreive information. +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. @@ -230,51 +244,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. +As mentioned previously, any route which matches GET requests will also +match HEAD requests. This is just convenience for web app developers. -=head2 Route Handlers +=head2 Route Patterns -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. +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. -You can have more details about how params are built and how to access them -in the L documentation. - -=head3 Declaring Routes - -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 simplest route patterns provide an exact match to the requested path: -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 en of it, for example: get '/hello/:name?' => sub { my $name = route_parameters->get('name') //= 'Whoever you are'; @@ -353,6 +354,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: From f14a20195c170b5310362c16338c269c0ef67764 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Tue, 26 Dec 2017 03:41:54 -0500 Subject: [PATCH 4/6] fix minor typo --- lib/Dancer2/Manual.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index 9afe98c19..2b2ebc6e0 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -275,7 +275,7 @@ in the block of code. "Hey " . route_parameters->get('name') . ", welcome here!"; }; -Tokens can be optional by tacking a question mark to the en of it, 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'; From a2ef1fec97497ad53e851dd951b07226a94b1bb6 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Sun, 19 Apr 2020 21:25:48 -0400 Subject: [PATCH 5/6] Update Manual.pod fix misspelling of simple --- lib/Dancer2/Manual.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index 2b2ebc6e0..ba46ddc11 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -171,7 +171,7 @@ 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 simiple example: +You can make your route handler dynamic with parameters. As a simple example: get '/hello/:name' => sub { return "Hi there " . route_parameters->get('name'); From 820290a197acbe5d862155cf68b4e92e779365f7 Mon Sep 17 00:00:00 2001 From: Steve Dondley Date: Sun, 19 Apr 2020 21:28:41 -0400 Subject: [PATCH 6/6] fix list items and file links --- lib/Dancer2/Manual.pod | 32 ++++++++------------------------ 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index ba46ddc11..e81ca2d90 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -87,39 +87,23 @@ The L script creates the following: =item * a directory named after the name of the app, L in this case -=item * - -a configuration file, l. - -=item * +=item a configuration file, F. -a L directory (where your templates and layouts will live), +=item a F directory (where your templates and layouts will live), -=item * - -an L directory (where environment-specific settings live), - -=item * +=item F directory (where environment-specific settings live), -a L directory (where static assets like css file and javascrpt files can +=item F directory (where static assets like css file and javascrpt files can go) -=item * - -a L directory (where your tests can go) - -=item * +=item F directory (where your tests can go) -a variety of files for helping you build your application into a +=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 * +=item a module containing the actual guts of your application in L -a script to start your appliaction in L. +=item a script to start your appliaction in L. =back