finished the scheme matching and uri_for updates

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Controller.pm

diff --git a/lib/Catalyst/Controller.pm b/lib/Catalyst/Controller.pm
index 3e3dd79..f2ccfa8 100644 (file)
--- a/lib/Catalyst/Controller.pm
+++ b/lib/Catalyst/Controller.pm
@@ -120,7 +120,7 @@ for more info about how Catalyst dispatches to actions.
 =cut
 
 #I think both of these could be attributes. doesn't really seem like they need
-#to ble class data. i think that attributes +default would work just fine
+#to be class data. i think that attributes +default would work just fine
 __PACKAGE__->mk_classdata($_) for qw/_dispatch_steps _action_class _action_role_prefix/;
 
 __PACKAGE__->_dispatch_steps( [qw/_BEGIN _AUTO _ACTION/] );
@@ -368,7 +368,13 @@ sub gather_default_action_roles {
   my @roles = ();
   push @roles, 'Catalyst::ActionRole::HTTPMethods'
     if $args{attributes}->{Method};
-  return @roles;
+
+  push @roles, 'Catalyst::ActionRole::ConsumesContent'
+    if $args{attributes}->{Consumes};
+
+  push @roles, 'Catalyst::ActionRole::Scheme'
+    if $args{attributes}->{Scheme};
+    return @roles;
 }
 
 sub _parse_attrs {
@@ -830,6 +836,94 @@ When used with L</Path> indicates the number of arguments expected in
 the path.  However if no Args value is set, assumed to 'slurp' all
 remaining path pars under this namespace.
 
+=head2 Consumes('...')
+
+Matches the current action against the content-type of the request.  Typically
+this is used when the request is a POST or PUT and you want to restrict the
+submitted content type.  For example, you might have an HTML for that either
+returns classic url encoded form data, or JSON when Javascript is enabled.  In
+this case you may wish to match either incoming type to one of two different
+actions, for properly processing.
+
+Examples:
+
+    sub is_json       : Chained('start') Consumes('application/json') { ... }
+    sub is_urlencoded : Chained('start') Consumes('application/x-www-form-urlencoded') { ... }
+    sub is_multipart  : Chained('start') Consumes('multipart/form-data') { ... }
+
+To reduce boilerplate, we include the following content type shortcuts:
+
+Examples
+
+      sub is_json       : Chained('start') Consume(JSON) { ... }
+      sub is_urlencoded : Chained('start') Consumes(UrlEncoded) { ... }
+      sub is_multipart  : Chained('start') Consumes(Multipart) { ... }
+
+You may specify more than one match:
+
+      sub is_more_than_one
+        : Chained('start')
+        : Consumes('application/x-www-form-urlencoded')
+        : Consumes('multipart/form-data')
+
+      sub is_more_than_one
+        : Chained('start')
+        : Consumes(UrlEncoded)
+        : Consumes(Multipart)
+
+Since it is a common case the shortcut C<HTMLForm> matches both
+'application/x-www-form-urlencoded' and 'multipart/form-data'.  Here's the full
+list of available shortcuts:
+
+    JSON => 'application/json',
+    JS => 'application/javascript',
+    PERL => 'application/perl',
+    HTML => 'text/html',
+    XML => 'text/XML',
+    Plain => 'text/plain',
+    UrlEncoded => 'application/x-www-form-urlencoded',
+    Multipart => 'multipart/form-data',
+    HTMLForm => ['application/x-www-form-urlencoded','multipart/form-data'],
+
+Please keep in mind that when dispatching, L<Catalyst> will match the first most
+relevant case, so if you use the C<Consumes> attribute, you should place your
+most accurate matches early in the Chain, and your 'catchall' actions last.
+
+See L<Catalyst::ActionRole::ConsumesContent> for more.
+
+=head2 Scheme(...)
+
+Allows you to specify a URI scheme for the action or action chain.  For example
+you can required that a given path be C<https> or that it is a websocket endpoint
+C<ws> or C<wss>.  For an action chain you may currently only have one defined
+Scheme.
+
+    package MyApp::Controller::Root;
+
+    use base 'Catalyst::Controller';
+
+    sub is_http :Path(scheme) Scheme(http) Args(0) {
+      my ($self, $c) = @_;
+      $c->response->body("is_http");
+    }
+
+    sub is_https :Path(scheme) Scheme(https) Args(0)  {
+      my ($self, $c) = @_;
+      $c->response->body("is_https");
+    }
+
+In the above example http://localhost/root/scheme would match the first
+action (is_http) but https://localhost/root/scheme would match the second.
+
+As an added benefit, if an action or action chain defines a Scheme, when using
+$c->uri_for the scheme of the generated URL will use what you define in the action
+or action chain (the current behavior is to set the scheme based on the current
+incoming request).  This makes it easier to use uri_for on websites where some
+paths are secure and others are not.  You may also use this to other schemes
+like websockets.
+
+See L<Catalyst::ActionRole::Scheme> for more.
+
 =head1 OPTIONAL METHODS
 
 =head2 _parse_[$name]_attr