WIP: Parameter handling, templates

lib/Dancer2/Manual.pod

@@ -190,20 +190,154 @@ Provide examples for:
 
 Route definitions can use C<any> to match all, or a specified list of HTTP methods.
 
-The following will match any HTTP request to the path C</myaction>:
+The following will match any HTTP request to the path C</visitor-center>:
 
-    any '/myaction' => sub {
-        # code
+    any '/visitor-center' => sub {
+        # Write code to do something at the visitor center!
     }
 
-The following will match GET or POST requests to C</myaction>:
+The following will match GET or POST requests to C</visitor-center>:
 
-    any ['get', 'post'] => '/myaction' => sub {
-        # code
+    any ['get', 'post'] => '/visitor-center' => sub {
+        # Write code to do something at the visitor center!
     };
 
 =head2 Parameter Handling
 
+TODO: need an explanation here
+
+=head3 Keywords for working with parameters
+
+=head4 body_parameters
+
+This keyword retrieves parameters from the body of the request, typically
+used in POST requests.
+
+Example of C<body_parameters> with multiple values:
+
+    post '/submit' => sub {
+        my $name  = body_parameters->get('name');
+        my $email = body_parameters->get('email');
+        return "Submitted name: $name, email: $email";
+    };
+
+=head4 query_parameters
+
+This keyword retrieves parameters from the query string of the request URL.
+
+Example of C<query_parameters> with multiple values:
+
+    # Matches URL: /search?q=rides&cat=thrill
+    get '/search' => sub {
+        my $query    = query_parameters->get('q');
+        my $category = query_parameters->get('cat');
+        return "Search query: $query in category: $category";
+    };
+
+=head4 route_parameters
+
+This keyword retrieves parameters from the route pattern.
+
+Example of C<route_parameters>:
+
+    # Matches URL: /user/123
+    get '/user/:id' => sub {
+        my $user_id = route_parameters->get('id');
+        return "User ID: $user_id";
+    };
+
+=head4 get_all
+
+This method works for all of the above parameter-fetching keywords. If
+you have a parameter that may contain more than one value, C<get_all>
+will return an array reference containing all selected values, even if
+there is only a single value returned.
+
+Example of C<get_all>:
+
+    # Matches URL: /all-params?name=John&age=30
+    get '/all-params' => sub {
+        my $params = query_parameters->get_all();
+        return "All query parameters: " . join(', ', %$params);
+    };
+
+=head3 Named Route Parameters
+
+Named route parameters allow you to capture specific segments of the URL
+and use them in your route handler.
+
+Example of named route parameters:
+
+    # Matches URL: /ride/roller-coaster
+    get '/ride/:name' => sub {
+        my $ride_name = route_parameters->get('name');
+        return "Welcome to the $ride_name ride!";
+    };
+
+=head3 Wildcard Route Parameters
+
+Wildcard route parameters allow you to capture arbitrary parts of the URL.
+There are two types: C<splat> and C<megasplat>. C<splat> is represented by
+a single asterisk (C<*>), and megaspat is represented by a double asterisk
+(C<**>).
+
+Examples of wildcard route parameters include:
+
+=over
+
+=item splat: Captures one segment of the URL
+
+    # Matches URL: /files/document.txt
+    get '/files/*' => sub {
+        my ($file) = splat;
+        return "You requested the file: $file";
+    };
+
+=item megasplat: Captures multiple segments of the URL
+
+    # Matches URL: /files/documents/reports/2023/summary.txt
+    get '/files/**' => sub {
+        my @files = splat;
+        return "You requested the files: " . join(', ', @files);
+    };
+
+=head3 Combining named and wildcard parameters
+
+You can combine named and wildcard parameters in your routes to capture
+both specific and arbitrary segments of the URL.
+
+Example combining named and wildcard parameters:
+
+    # Matches URL: /user/123/files/documents/reports/2023/summary.txt
+    get '/user/:id/files/**' => sub {
+        my $user_id = route_parameters->get('id');
+        my @files = splat;
+        return "User ID: $user_id requested the files: " . join(', ', @files);
+    };
+
+=head3 Named parameters with type constraints
+
+TODO/re-do
+
+=head3 Wildcard Parameters with Type Constraints
+
+TODO/re-do
+
+=head3 Regex Route Matching
+
+TODO/re-do
+
+=head3 Combining Examples
+
+TODO/re-do
+
+=head2 Simplifying Route Declarations with prefix
+
+TODO
+
+=head2 Skipping Routes and Actions
+
+TODO
 
 =head1 Templates: Displaying Information, and More!