From 13075e27d727e241343ec8a5bd96ee9d8f6e69f4 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 19 Mar 2013 17:47:56 +0000 Subject: [PATCH] docs: more work --- caf.pod | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/caf.pod b/caf.pod index 5dd2f07..922f7f8 100644 --- a/caf.pod +++ b/caf.pod @@ -111,7 +111,14 @@ The resulting verifier object can be used to process individual requests, in each case with C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>. -=head2 RESPONSES - SIMPLE APPLICATIONS +=head2 CHECKING AND RESPONSE GENERATION + +If the user is logged in, your application is to handle the request. +Otherwise, the user needs to be presented with a login form or error +message, as appropriate. CGI::Auth::Flexible provides two alternative +interfaces for this: + +=head3 Simple applications The simplist usage is to call C<< $request->check_ok() >> which will check the user's authentication. If the user is not logged in it will @@ -126,7 +133,7 @@ After C returns true you should go ahead and process the request; you can use C<< $request->get_username >> to find out which user the request came from. -=head2 RESPONSES - SOPHISTICATED APPLICATIONS +=head2 Sophisticated applications If you want to handle the control flow and to generate login forms, redirections, etc., yourself, you can say @@ -134,7 +141,11 @@ C<< $divert = $request->check_divert >>. This returns undef if the user is logged in, or I if some kind of login page or diversion should be generated. -=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-IGNORANT APPLICATIONS +xxx see below + +=head2 MUTATING OPERATIONS AND EXTERNAL LINKS + +=head3 Mutation-ignorant applications By default CGI::Auth::Flexible does not permit external links into your site. All GET requests give a "click to continue" page which @@ -146,7 +157,7 @@ in the web's security architecture. Such applications are also not able to provide user-specific CSS stylesheets, javascript, favicons, etc. -=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-AWARE APPLICATIONS +=head3 Mutation-aware applications The alternative is for your application to always make a special check when the incoming request is going to do some kind of action (such as @@ -368,10 +379,9 @@ parameter in a single request; normally each arrayref would be a singleton.) The request path will be the path to the application. If a parameter -with name C<< '' >> is supplied, it is taken as the PATH_INFO to -supply - its value will be appended to the application path. (It -should normally start with C<< / >>, and only one value should be -supplied.) +with name C<< '' >> is supplied, it is taken as the PATH_INFO - its +value will be appended to the application path. (It should normally +start with C<< / >>, and only one value should be supplied.) =item C<< $authreq->chain_params() >> -- 2.30.2