update text dump of documentation

[perl/plp/.git] / PLP / HowTo.pod

diff --git a/PLP/HowTo.pod b/PLP/HowTo.pod
index e6b0354eb70656ecbdcafdce6e1a55660e3f5129..e86e68f3f2e8b38152bf750de6da2e7638a01b8e 100644 (file)
--- a/PLP/HowTo.pod
+++ b/PLP/HowTo.pod
@@ -1,72 +1,102 @@
-=head1 Name
+=head1 NAME

 
 PLP::HowTo - Some examples of commong web things in PLP.
 
 
 PLP::HowTo - Some examples of commong web things in PLP.
 

-=head1 How to...
+=head1 HOW TO...

 
 Additional Perl functionality is often available in modules. All of the modules
 used in this document are available (for free) at CPAN: http://search.cpan.org/
 
 
 Additional Perl functionality is often available in modules. All of the modules
 used in this document are available (for free) at CPAN: http://search.cpan.org/
 

-=over 10
+=head2 send a cookie

 
 

-=item send a cookie
+ <: 
+     BEGIN {
+        use CGI::Cookie;
+        AddCookie(
+            CGI::Cookie->new(
+                -name => 'ID',
+                -value => 123456,
+                -domain => 'foo.com',
+                -path => '/'
+            )->as_string
+        );
+     }
+ :>

 
 

-    <: 
-       BEGIN {
-           use CGI::Cookie;
-           AddCookie( CGI::Cookie->new(
-               -name => 'ID',
-               -value => 123456,
-               -domain => 'foo.com',
-               -path => '/'
-           )->as_string );
-       }
-    :>
+=head2 get a cookie

 
 

-=item get a cookie
+ Your user ID is <:= $cookie{ID} :>

 
 

-    Your user ID is <:= $cookie{ID} :>
+=head2 set a header

 
 

-=item set a header
+ <:
+     BEGIN {
+         $header{Content_Type} = 'text/plain';
+     }
+ :>

 
 

-    <:
-       BEGIN {
-           $header{Content_Type} = 'text/plain';
-       }
-    :>
-
-=item use a database
+=head2 use a database

 
 Use DBI, and alternatively, one of the many simplifying modules. Drivers for
 DBI are in the DBD:: namespace. DBI loads the driver automatically, but it has
 
 Use DBI, and alternatively, one of the many simplifying modules. Drivers for
 DBI are in the DBD:: namespace. DBI loads the driver automatically, but it has

-to be available.
+to be available. If you need a fast full-featured file-base database, use
+DBD::SQLite, it's the instant database :).

 
 

-    <:
-       use DBIx::Simple; # and read its documentation for examples.
-    :>
+ <:
+     use DBIx::Simple; # and read its documentation for examples.
+ :>

 
 

-=item allow a user to upload a file
+=head2 allow a user to upload a file

 
 Use CGI.pm, which can be used with CGI::Upload to make things easier
 
 
 Use CGI.pm, which can be used with CGI::Upload to make things easier
 

-    <:
-       use CGI;         # and don't use %post in your PLP document.
-       use CGI::Upload; # and read its documentation for examples.
-       my $cgi = CGI->new;
-       my $upload = CGI::Upload->new($cgi);
-       ...
-    :>
-=item download a file into a variable
+ <:
+     use CGI;         # and don't use %post in your PLP document.
+     use CGI::Upload; # and read its documentation for examples.
+     my $cgi = CGI->new;
+     my $upload = CGI::Upload->new($cgi);
+     ...
+ :>
+
+=head2 download a file into a variable
+
+ <:
+     use LWP::Simple;
+     my $page = get 'http://foo.com/bar.html';
+ :>
+
+=head2 implement basic authentication
+
+This only works with PLP under mod_perl. For CGI installations, it's useless.
+
+ <:
+     use MIME::Base64;
+
+     BEGIN {
+         my $r = Apache->request;
+
+         my ($type, $login) = split / /, $r->header_in('Authorization');
+         my ($user, $pass) = split /:/, decode_base64 $login, 2;
+
+         unless ($user eq 'foo' and $pass eq 'bar') {
+             $header{Status} = '401 Authorization Required';
+             $header{WWW_Authenticate} = 'Basic realm="Top secret :)"';
+             print '<h1>Authorization Required</h1>';
+             exit;
+         }
+     }
+ :>

 
 

-    <:
-       use LWP::Simple;
-       my $page = get("http://foo.com/bar.html");
-    :>
+(It is possible to use something similar with CGI, but it's not easy. Headers
+are communicated to your script via C<%ENV>, and having credentials in there
+would be insecure, so Apache removes them. To get C<$ENV{HTTP_AUTHORIZATION}>,
+you need to recompile Apache with -DSECURITY_HOLE_PASS_AUTHORIZATION, or use
+mod_rewrite to set the environment variable. Short answer: just use mod_perl.)

 
 

-=back
+=head1 FEEDBACK

 
 If you have good, simple examples of how to do common things with PLP, please
 
 If you have good, simple examples of how to do common things with PLP, please

-send them! (juerd@cpan.org)
+send them! <perl@shiar.org>

 
 =cut
 
 
 =cut