added howto documentation

diff --git a/MANIFEST b/MANIFEST
index 84c9d83c05768edd425569590d0d10e0f73ba8e2..849bb729ff90d43f88a8f56f05c9b122fb99af55 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -9,6 +9,7 @@ test.pl
 PLP/FAQ.pod
 PLP/Fields.pm
 PLP/Functions.pm
+PLP/HowTo.pod
 PLP/Tie/Delay.pm
 PLP/Tie/Headers.pm
 PLP/Tie/Print.pm

diff --git a/PLP.pm b/PLP.pm
index a75b42ab02ef42e375c6c16b388be83a294192ab..36951ac95a9d5d16201db6f62fddd89da6095b95 100644 (file)
--- a/PLP.pm
+++ b/PLP.pm
@@ -502,10 +502,10 @@ The special hashes are tied hashes and do not always behave the way you expect,
 especially when mixed with modules that expect normal CGI environments, like
 CGI.pm. Read L<PLP::Fields> for information more about this.
 
-=head1 FAQ
+=head1 FAQ and HowTo
 
 A lot of questions are asked often, so before asking yours, please read the 
-FAQ at L<PLP::FAQ>.
+FAQ at L<PLP::FAQ>. Some examples can be found at L<PLP::HowTo>.
 
 =head1 NO WARRANTY
 
@@ -518,7 +518,7 @@ Juerd Waalboer <juerd@juerd.nl>
 
 =head1 SEE ALSO
 
-L<PLP::Functions>, L<PLP::Fields>, L<PLP::FAQ>
+L<PLP::Functions>, L<PLP::Fields>, L<PLP::FAQ>, L<PLP::HowTo>
 
 =cut
 

diff --git a/PLP/HowTo.pod b/PLP/HowTo.pod
new file mode 100644 (file)
index 0000000..e6b0354
--- /dev/null
+++ b/PLP/HowTo.pod
@@ -0,0 +1,72 @@
+=head1 Name
+
+PLP::HowTo - Some examples of commong web things in PLP.
+
+=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/
+
+=over 10
+
+=item send a cookie
+
+    <: 
+       BEGIN {
+           use CGI::Cookie;
+           AddCookie( CGI::Cookie->new(
+               -name => 'ID',
+               -value => 123456,
+               -domain => 'foo.com',
+               -path => '/'
+           )->as_string );
+       }
+    :>
+
+=item get a cookie
+
+    Your user ID is <:= $cookie{ID} :>
+
+=item set a header
+
+    <:
+       BEGIN {
+           $header{Content_Type} = 'text/plain';
+       }
+    :>
+
+=item 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
+to be available.
+
+    <:
+       use DBIx::Simple; # and read its documentation for examples.
+    :>
+
+=item allow a user to upload a file
+
+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 LWP::Simple;
+       my $page = get("http://foo.com/bar.html");
+    :>
+
+=back
+
+If you have good, simple examples of how to do common things with PLP, please
+send them! (juerd@cpan.org)
+
+=cut
+