[Openinteract-commits] CVS: OpenInteract/pkg/base_page/doc base_page.pod,1.1,1.2

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract/pkg/base_page/doc
In directory usw-pr-cvs1:/tmp/cvs-serv25281/doc

Modified Files:
	base_page.pod 
Log Message:
copy over docs from static_page


Index: base_page.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract/pkg/base_page/doc/base_page.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** base_page.pod	2001/10/17 12:11:04	1.1
--- base_page.pod	2001/10/24 21:05:10	1.2
***************
*** 1,35 ****
  =head1 NAME
  
! base_page - This package will do everything!
  
  =head1 SYNOPSIS
  
  =head1 DESCRIPTION
  
! =head1 OBJECTS
  
! No objects created by this package.
  
! =head1 ACTIONS
  
! No actions defined in this package.
  
! =head1 RULESETS
  
! No rulesets defined in this package.
  
! =head1 ERRORS
  
! No custom error handlers defined in this package.
  
! =head1 BUGS 
  
! None known.
  
  =head1 TO DO
  
  =head1 SEE ALSO
  
  =head1 AUTHORS
  
! Who AmI <me...@wh...>
--- 1,193 ----
+ =pod
+ 
  =head1 NAME
  
! base_page - Package for displaying and editing 'static' web pages in OpenInteract
  
  =head1 SYNOPSIS
  
+  # Too many actions to list, since by default this module picks up all
+  # requests not found in the action table
+ 
  =head1 DESCRIPTION
  
! This module displays pages. 
  
! Well, ok, it does more than that. Each page is a template in its own
! right and you can store the pages in the database or the filesystem,
! or both. A configuration option in your 'conf/action.perl' controls
! which option you want to use.
  
! So a request like:
  
!  http://www.mysite.com/reports/q1/sales
  
! Can be mapped to a database object which displays the report. But your
! users never know the difference.
  
! =head2 Non-HTML pages
  
! This module can also deal with other types of files, although its main
! purpose is to impose security on them. After security is checked it
! generally hands the filename to OpenInteract so the file contents can
! be sent to the user further along in the process.
  
! =head2 Handling all unspecified requests
  
! How does this module handle all unspecified requests? In the
! OpenInteract server configuration file, toward the bottom, there's a
! section that looks something like this:
  
!   [action_info none]
!   redir = page
! 
!   [action_info not_found]
!   redir = page
! 
! 
! This means if no action is found (an 'empty request') it will be
! serviced by the 'page' action, which is defined in this module's
! 'conf/action.perl' file. The empty request is typically
! 'http://www.mysite.com/', or your home page. (Want to see all the
! actions defined for your site?  Try:
! 
!   'oi_manage list_actions --website_dir=/path/to/my/site'
! 
! from the command-line.)
! 
! Similarly, the 'not_found' action definition will automatically get
! picked up by the same 'page' action. This means any request
! OpenInteract can't match up to an action will get sent to the 'page'
! action unless rquested not to do so.
! 
! =head1 RECORDS USED
! 
! Static pages used to be only displayed from the database using the
! 'basic_page' SPOPS object. No longer. You can now display HTML pages
! from the filesystem as well as objects from the database, and refer to
! them in the exact same way.
! 
! There are a few differences. Objects
! 
! For instance, say you have database records representing HTML pages
! identified by the following locations:
! 
!  /mytest/test1
!  /mytest/test2
! 
! And HTML pages in the filesystem at the following locations:
! 
!  $SITE_HOME/html/mytest/test3.html
!  $SITE_HOME/html/mytest/test4.html
! 
! Then the following applies:
! 
!  Request              Result
!  ===============      =========================
!  /mytest/test1        Served by SPOPS object from database
!  /mytest/test3.html   Served by filesystem
!  /mytest/test4        File not found!
!  /mytest/test2.html   Served by SPOPS object from database 
! 
! The first three are pretty easy to understand, but the fourth is
! odd. When searching for files in the database, we take the requests
! and, if a file extension exists, chop it off as another name to
! check. This could lead to a nasty 'error' where you have a file in the
! filesystem '$SITE_HOME/html/mytest/test2.html' and a database object
! '/mytest/test2' -- if the database is being checked first, then the
! filesystem file will B<never be displayed>.
! 
! =head1 SECURITY
! 
! Pages are different from other objects in how their security is
! treated. Typically, you want to set security for a directory and have
! that security setting be inherited by all files in that directory, all
! directories in that directory and files within each of those
! directories, and so on. This is how Apache does file-based security.
! 
! OpenInteract implements security the same way, but using a slightly
! more generic mechanism. Using the L<SPOPS::Secure::Hierarchy>
! module, we simply split up each URL using the directory separator
! ('/') and apply security at each level under that. Here's an example
! from the L<SPOPS::Secure::Hierarchy> documentation:
! 
!  -------------------------
! 
! To accomplish this, every record needs to have an identifier that can
! be manipulated into a parent identifier. With filesystems (or URLs)
! this is simple. Given the pseudo-file:
! 
!  /docs/release/devel-only/v1.3/mydoc.html
! 
! You have the following parents:
! 
!  /docs/release/devel-only/v1.3
!  /docs/release/devel-only
!  /docs/release/
!  /docs/
!  <ROOT OBJECT> (explained below)
  
+  -------------------------
+ 
+ So setting security for '/docs/release' when it's protected by
+ hierarchical security will also protect '/docs/release/devel-only' and
+ on down the line, as long as the child doesn't have security defined
+ of its own.
+ 
+ One additional note: since security is typically set by directory,
+ B<any> file in that directory is protected by the security, HTML and
+ non-HTML alike. This allows you to put graphics, PDF documents, Excel
+ spreadsheets or what have you into a filesystem directory, protect the
+ directory and let OpenInteract deal with the rest. Cool.
+ 
+ =head1 BUGS
+ 
+ =over 4
+ 
+ =item *
+ 
+ Documentation: ensure we have all the action and SPOPS items in the
+ docs.
+ 
+ =item *
+ 
+ See that we handle file extensions (or lack thereof) consistently no
+ matter whether we're requesting an object from the database or a file
+ from the filesystem.
+ 
+ =back 
+ 
  =head1 TO DO
  
+ B<Map multiple URLs to one 'file'>
+ 
+ Sometimes you might accidentally give out the wrong URL, or you might
+ find that people constantly misspell the correct URL. It should be
+ pretty simple to have a separate table of URL -> real URL mappings
+ which we consult if we don't find a page.
+ 
+ B<Map requests to URL fetches from other sites>
+ 
+ It would be kind of interesting to map certain URLs to grab pages (or
+ sections of pages) from other sites. (Probably illegal, but whatever.)
+ 
  =head1 SEE ALSO
  
+ B<base_security> package
+ 
+ L<SPOPS::Secure::Hierarchy|SPOPS::Secure::Hierarchy>
+ 
  =head1 AUTHORS
  
! Chris Winters <ch...@cw...>
! 
! =head1 COPYRIGHT
! 
! Copyright (c) 2001 intes.net, inc.. All rights reserved.
! 
! This library is free software; you can redistribute it and/or modify
! it under the same terms as Perl itself.
! 
! $Id$
! 
! =cut
\ No newline at end of file