Converted to Module::Install.

[catagits/Catalyst-Plugin-RequireSSL.git] / README

diff --git a/README b/README
index 5098a8b..400bcf4 100644 (file)
--- a/README
+++ b/README
@@ -2,14 +2,19 @@ NAME
     Catalyst::Plugin::RequireSSL - Force SSL mode on select pages
 
 SYNOPSIS
-        use Catalyst 'RequireSSL';
+        # in MyApp.pm
+        use Catalyst;
+        MyApp->setup( qw/RequireSSL/ );
     
         MyApp->config->{require_ssl} = {
             https => 'secure.mydomain.com',
             http => 'www.mydomain.com',
             remain_in_ssl => 0,
+            no_cache => 0,
+            detach_on_redirect => 1,
         };
 
+        # in any controller methods that should be secured
         $c->require_ssl;
 
 DESCRIPTION
@@ -34,54 +39,76 @@ CONFIGURATION
     values:
 
         https => $ssl_host
-    
+
     If your SSL domain name is different from your non-SSL domain, set this
     value.
 
         http => $non_ssl_host
-    
+
     If you have set the https value above, you must also set the hostname of
     your non-SSL server.
 
         remain_in_ssl
-    
+
     If you'd like your users to remain in SSL mode after visiting an
-    SSL-required page, you can set this option to 1. By default, users will
-    be redirected back to non-SSL mode as soon as possible.
+    SSL-required page, you can set this option to 1. By default, this option
+    is disabled and users will be redirected back to non-SSL mode as soon as
+    possible.
+
+        no_cache
 
-  METHODS
-    require_ssl
-        Call require_ssl in any controller method you wish to be secured.
+    If you have a wildcard certificate you will need to set this option if
+    you are using multiple domains on one instance of Catalyst.
 
-            $c->require_ssl;
+        detach_on_redirect
 
-        The browser will be redirected to the same path on your SSL server.
-        POST requests are never redirected.
+    By default "$c->require_ssl" only calls "$c->response->redirect" but
+    does not stop request processing (so it returns and subsequent
+    statements are run). This is probably not what you want. If you set this
+    option to a true value "$c->require_ssl" will call "$c->detach" when it
+    redirects.
 
-    finalize (extended)
-        Redirect back to non-SSL mode if necessary.
+METHODS
+  require_ssl
+    Call require_ssl in any controller method you wish to be secured.
 
-    setup
-        Setup default values.
+        $c->require_ssl;
+
+    The browser will be redirected to the same path on your SSL server. POST
+    requests are never redirected.
+
+  allow_ssl
+    Call allow_ssl in any controller method you wish to access both in SSL
+    and non-SSL mode.
+
+        $c->allow_ssl;
 
-    _redirect_uri
-        Generate the redirection URI.
+    The browser will not be redirected, independently of whether the request
+    was made to the SSL or non-SSL server.
+
+  setup
+    Disables this plugin if running under an engine which does not support
+    SSL.
+
+  finalize
+    Performs the redirect to SSL url if required.
 
 KNOWN ISSUES
     When viewing an SSL-required page that uses static files served from the
-    Static plugin, the static files are redirected to the non-SSL path. It
-    may be possible to work around this by checking the referer protocol,
-    but currently there is no way to determine if a file being served is
-    static content.
+    Static plugin, the static files are redirected to the non-SSL path.
 
-    For best results, always serve static files directly from your web
-    server without using the Static plugin.
+    In order to get the correct behaviour where static files are not
+    redirected, you should use the Static::Simple plugin or always serve
+    static files directly from your web server.
 
 SEE ALSO
-    Catalyst
+    Catalyst, Catalyst::Plugin::Static::Simple
 
 AUTHOR
-    Andy Grundman, "andy@hybridized.org"
+    Andy Grundman, <andy@hybridized.org>
+
+CONTRIBUTORS
+    Simon Elliott <simon@browsing.co.uk> (support for wildcards)
 
 COPYRIGHT
     This program is free software, you can redistribute it and/or modify it