This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Apache/XPP, Next: Apache/XPP/Cache, Prev: Apache/WebSNMP, Up: Module List SYNOPSIS ======== use Apache::XPP; my $xpp = Apache::XPP->new( Apache->request ); $xpml->run; REQUIRES ======== Apache Apache::Constants File::stat FileHandle HTTP::Request HTTP::Date LWP::UserAgent EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP is an HTML parser which on run time compiles and runs embedded perl code. CLASS VARIABLES =============== `$Apache::XPP::main_class' XPP sub-classes must set $Apache::XPP::main_class to the name of the sub-class. This will allow xinclude/include to work properly. $debug Activates debugging output. All debugging output is sent to STDERR. At present there are only 4 levels of debugging : 0 - no debugging (default) 1 - some debugging 2 - verbose debugging 3 - adds some Data::Dumper calls `$debuglines' Optionally, you can activate the $debuglines, which will cause all debugging output to include the line numbers (in this file) of the debugging. METHODS ======= handler ( $r ) The Apache handler hook. This is the entry point for the Apache module. It takes the Apache request object ($r) as its parameter and builds a new XPP object to handle the request. In order to support the procedural nature of include() and xinclude() a global is defined. If you subclass Apache::XPP replace the value of the global `"$Apache::XPP::main_class"' in this node with your class name. new ( \%params | $filename ) Creates a new XPP object. Valid parameter keys are: * source - A block of xpp code to be parsed * filename - A filename/url specifying a code block All other parameters will be stashed in the xpp object. `preparse' ( ) Pre-Parses the object's code, converting TAGS to text and xpp code. This method passes a reference to the xpp source to each preparser returned by the preparse class's `parses' method. (The preparse class is returned by the `preparseclass' method). parse ( ) Parses the object's xpp source code, populating the object's code attribute with a subroutine reference which when run (with the run method), will result in the printing of the xpp page. run ( @arguments ) Runs the XPP code (set by the parse method), passing any arguments supplied to the code. This should have the effect of printing the xpp page to STDOUT. `returnrun' ( @arguments ) Calls run with @arguments as specified, catching all output destined for STDOUT, and returning the results as a string. load ( $filename ) Returns the code specified by $filename. If $filename begins with a url specifier (e.g. http://), LWP::UserAgent will be used to retrieve the file. If $filename begins with a '/', it will be treated as a rooted filename. Otherwise the filename will be as a file relative to XPPIncludeDir qualify ( $filename ) Qualifies the passed name to a fully rooted filename by using either `incdir' or `docroot'. `incdir' ( ) Returns the include directory from which include and `xinclude' will retrieve source from by default. See include, `xinclude', and load for more documentation on this process. `docroot' ( ) Returns the document root directory from which all rooted filenames will be retrieved in include, and `xinclude'. r ( ) Returns the Apache request object include ( $filename ) Static, unbuffered, unparsed content include. It can be used within an xpml script by simply saying include $filename; See the load method for more information `xinclude' ( $filename, @options ) Dynamic, parsed, buffered content include. It can be used within an xpml script by simply saying xinclude $filename; debug ( $debuglevel [, $debuglines ] Manipulates debug level. See $debug above. N.B. - at present these flags are global, not per object. Method works as static or dynamic. include( $inc_location ) Returns the plaintext of the include file $inc_location. xinclude( $inc_location, @ARGS ) Returns the XPP parsed text of the include file $inc_location, passing @ARGS to the page as arguments. REVISION HISTORY ================ $Log: XPP.pm,v $ Revision 1.23 2000/09/08 22:26:44 david added, changed, revised, and otherwise cleaned up a lot of POD cleaned up new() - removed dependence on MD5 (uses conventional checksum) - folded nearly duplicate header and footer code into a loop incdir() - now uses Apache->server_root_relative() instead of $ENV{SERVER_ROOT} debug() - new method to manipulate $debug and $debuglines globals Apache::XPP::Tie class now uses $debug settings of Apache::XPP class "This would go great with gwack-a-mole!" - Z.B. Revision 1.22 2000/09/08 00:42:45 dougw Took out rscope stuff. Revision 1.21 2000/09/07 23:42:23 greg fixed POD Revision 1.20 2000/09/07 23:30:40 dougw Fixed over. Revision 1.19 2000/09/07 20:15:54 david new(), r() - makes previous bug fix less agressive, yet more thorough. Revision 1.18 2000/09/07 19:49:01 david r() - fixed peculiar (and elusive) bug where DirectoryIndex accessed pages (and potentially any page using a subrequest) caused a segmentation fault with cached pages. Revision 1.17 2000/09/07 18:48:11 dougw Small update Revision 1.16 2000/09/07 18:45:14 dougw Version update Revision 1.15 2000/09/06 23:42:50 dougw Modified POD to be consistent with BingoX SEE ALSO ======== perl(1). KNOWN BUGS ========== None TODO ==== precompile COPYRIGHT ========= Copyright (c) 2000, Cnation Inc. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the GNU Lesser General Public License as published by the Free Software Foundation. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA AUTHORS ======= Greg Williams Doug Weimer THANKS TO ========= Chris Nandor for his help on the regex core.  File: pm.info, Node: Apache/XPP/Cache, Next: Apache/XPP/Cache/Expiry, Prev: Apache/XPP, Up: Module List XPP Cache manegment module ************************** NAME ==== Apache::XPP::Cache - XPP Cache manegment module SYNOPSIS ======== use Apache::XPP::Cache; $cache = Apache::XPP::Cache->new( %options ); $cache = Apache::XPP::Cache->is_cached( %options ); REQUIRES ======== Apache::XPP EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::Cache is an interface to both Store and Expire caching modules. METHODS ======= new( $name, $group, \%instance_data, [ $storetype, @store_options ], [ $expiretype, @expire_options ] ) Creates a new Cache object using the specified Store and Expire types. `install_module' ( ('Store'|'Expiry'), $name ) Installs the $name store or expiry module, and returns the associated class name. is_expired ( ) Returns a true value if the current cache has expired, otherwise returns false. content ( ) Returns the content of the current cache. r ( ) Returns the Apache request object AUTOLOAD ( ) Calling $obj->meth() returns $obj->{'meth'}. Calling $obj->meth($val) sets $obj->{'meth'} = $val. REVISION HISTORY ================ $Log: Cache.pm,v $ Revision 1.8 2000/09/15 22:02:37 dougw Took out $AUTOLOAD Revision 1.7 2000/09/15 21:35:22 dougw Autoload changed to use Apache::XPP's autoload. This didn't make it into the previous check in. Revision 1.6 2000/09/13 21:02:11 dougw David cleaned up the loop in new() so it isn't 2 identical loops. r() and AUTOLOAD() are now just forwarders to Apache::XPP::r and Apache::XPP::AUTOLOAD Revision 1.5 2000/09/07 19:03:19 dougw over fix Revision 1.4 2000/09/07 18:40:38 dougw Pod updates. AUTHORS ======= Doug Weimer Greg Williams SEE ALSO ======== l. l  File: pm.info, Node: Apache/XPP/Cache/Expiry, Next: Apache/XPP/Cache/Expiry/Duration, Prev: Apache/XPP/Cache, Up: Module List Cache expiry superclass *********************** NAME ==== Apache::XPP::Cache::Expiry - Cache expiry superclass SYNOPSIS ======== ... REQUIRES ======== Nothing EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::Cache::Expiry provides a barebones AUTOLOAD for XPP's Cache-Expiry classes. METHDOS ======= r ( ) Returns the Apache request object REVISION HISTORY ================ $Log: Expiry.pm,v $ Revision 1.6 2000/09/11 20:12:23 david Various minor code efficiency improvements. Revision 1.5 2000/09/07 19:02:41 dougw Pod, over fix Revision 1.4 2000/09/07 18:50:01 dougw Fixed pod error Revision 1.3 2000/09/07 18:44:52 dougw POD updates. AUTHORS ======= Greg Williams SEE ALSO ======== perl(1). Apache::XPP Apache::XPP::Cache  File: pm.info, Node: Apache/XPP/Cache/Expiry/Duration, Next: Apache/XPP/Cache/Store, Prev: Apache/XPP/Cache/Expiry, Up: Module List Duration based cache expiry. **************************** NAME ==== Apache::XPP::Cache::Expiry::Duration - Duration based cache expiry. SYNOPSIS ======== ... REQUIRES ======== Apache::XPP::Cache::Expiry EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::Cache::Expiry::Duration handles the expiring of caches based on a duration of time on behalf of Apache::XPP::Cache. METHODS ======= new ( $name, $group, \%instance_data, $duration ) Creates a new Duration expiry object. The contents of %instance_data will be placed in the object as instance data (for Apache request object, etc.). is_expired ( $store_object ) Returns TRUE if the cache (whose store is passed as an argument) has expired, FALSE otherwise. REVISION HISTORY ================ $Log: Duration.pm,v $ Revision 1.5 2000/09/11 20:12:23 david Various minor code efficiency improvements. Revision 1.4 2000/09/07 19:02:56 dougw over fix Revision 1.3 2000/09/07 18:53:13 dougw Added VERSION/REVISION, pod changes. AUTHORS ======= Greg Williams SEE ALSO ======== perl(1).  File: pm.info, Node: Apache/XPP/Cache/Store, Next: Apache/XPP/Cache/Store/File, Prev: Apache/XPP/Cache/Expiry/Duration, Up: Module List Cache store superclass ********************** NAME ==== Apache::XPP::Cache::Store - Cache store superclass SYNOPSIS ======== ... REQUIRES ======== Carp EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::Cache::Store provides a barebones AUTOLOAD for XPP's Cache-Store classes. METHDOS ======= r ( ) Returns the Apache request object REVISION HISTORY ================ $Log: Store.pm,v $ Revision 1.5 2000/09/11 20:12:23 david Various minor code efficiency improvements. Revision 1.4 2000/09/07 19:02:14 dougw Pod, over fix. Revision 1.3 2000/09/07 18:50:52 dougw Pod fixes AUTHORS ======= Greg Williams SEE ALSO ======== perl(1). Apache::XPP Apache::XPP::Cache  File: pm.info, Node: Apache/XPP/Cache/Store/File, Next: Apache/XPP/PreParse, Prev: Apache/XPP/Cache/Store, Up: Module List flatfile cache store ******************** NAME ==== Apache::XPP::Cache::Store::File - flatfile cache store SYNOPSIS ======== ... REQUIRES ======== Apache::XPP::Cache::Store FileHandle File::stat EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::Cache::Store::File handles the storing of data in flat file form on behalf of Apache::XPP::Cache. METHODS ======= new ( $name, $group, \%instance_data, \$content ) Creates a new File store object. The contents of %instance_data will be placed in the object as instance data (for Apache request object, etc.). location ( $name, $group ) Returns the fully qualified filename to the store file for the specified name/group pair. Files are stored by their $name in the directory $group. If the directory $group does not exist, it will be created with permissions of 0777 (use the umask function to change these permissions to more desirable ones). `cachedir' ( ) Returns the directory in which file caches are stored. content ( [ \$content ] ) Sets the store object's content to $content and returns TRUE. If $content is omitted, returns the content of the store object. is_expired ( ) Removes the store file. mtime ( ) mtime ( $name, $group ) Returns the modification time of the specified store. REVISION HISTORY ================ $Log: File.pm,v $ Revision 1.7 2000/09/13 21:00:52 dougw Small change to line 165. Revision 1.6 2000/09/11 20:12:23 david Various minor code efficiency improvements. Revision 1.5 2000/09/07 19:01:57 dougw Pod fixin's AUTHORS ======= Greg Williams SEE ALSO ======== perl(1). Apache::XPP Apache::XPP:Cache  File: pm.info, Node: Apache/XPP/PreParse, Next: Apache/httpd_conf, Prev: Apache/XPP/Cache/Store/File, Up: Module List XPP TAG Parser ************** NAME ==== Apache::XPP::PreParse - XPP TAG Parser SYNOPSIS ======== use Apache::XPP::PreParse; $preparsers = Apache::XPP::PreParse->parsers; foreach (@{ $preparsers }) { $preparsers->( \$text ); } REQUIRES ======== Nothing EXPORTS ======= Nothing DESCRIPTION =========== Apache::XPP::PreParse handles pre parsing of an xpp page to convert 'tags' into valid XPML. Tags are meant as a shortcut for code that might otherwise be burdensome or confusing for and xpml author, such as ref checking before calling a method: might be converted to: cities_popup_menu; } ?>. METHODS ======= `parsers' ( ) Returns a new parser object `add_parser' ( \&parser ) Adds a parser to the list of registered pre-parsers. `parse_tag' ( $tag ) Given an xpp TAG $tag, will return an array with two elements. The first element is an array reference of the order of keys in the tag. The second element is a hash reference to the key-value pairs. `dtag' ( \$text, $tag, $subref ) This is for processing tags with a start tag and seperate end tag. All the data in between is sent to $subref->( $params, $data) where $params is a hashref containing all the key value pairs in the start tag and $data is the data contained in between the opening and closing tag. `parse_stag' Called by stag to parse the matched tag with the supplied rules. `stag' ( \$text, $match, \@replace_rules ) Given a string to match, uses the replace rules to replace tags that contain the $match with it's equivalent. See examples below for syntax of replace rules. `parser_xppcomment' Used to comment out blocks of xpml code. Ex: <?= $obj->title() ?> `parser_xppcache' Cache a block of code using a specific expire/store module. Pass the caches name, group, expire, and store. See `xppcachetut.pod' in this node for more information. Ex: .... `parser_appmethod' Assign or print an object method. Ref checks the object before using it. Assigns the result to the value of the as tag parameter. If this param isn't present the result is printed. Ex: `parser_print' Prints the result of an object method. Ex: `parser_xppxinclude' Calls xinclude with the passed filename and options. Ex: `parser_xppforeach' Places the included block within a foreach loop. Assigning each element of the array to 'as.' If 'as' is not present it uses $_. Ex: REVISION HISTORY ================ $Log: PreParse.pm,v $ Revision 1.17 2000/09/14 23:01:30 dougw Fixed stag pod. Revision 1.16 2000/09/13 00:32:04 dougw Pod for tag methods. Revision 1.15 2000/09/11 20:15:33 david Sent AUTOLOAD to Apache::XPP::AUTOLOAD. Revision 1.14 2000/09/07 19:03:19 dougw over fix Revision 1.13 2000/09/07 18:48:36 dougw Took out some use vars Revision 1.12 2000/09/07 18:45:42 dougw Version Update. Revision 1.11 2000/09/07 00:05:38 dougw POD fixes. SEE ALSO ======== perl(1). tagtut KNOWN BUGS ========== None TODO ==== ... COPYRIGHT ========= Copyright (c) 2000, Cnation Inc. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the GNU Lesser General Public License as published by the Free Software Foundation. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA AUTHORS ======= Greg Williams Doug Weimer  File: pm.info, Node: Apache/httpd_conf, Next: Apache/iNcom, Prev: Apache/XPP/PreParse, Up: Module List Generate an httpd.conf file *************************** NAME ==== Apache::httpd_conf - Generate an httpd.conf file SYNOPSIS ======== use Apache::httpd_conf (); Apache::httpd_conf->write(Port => 8888); DESCRIPTION =========== The Apache::httpd_conf module will generate a tiny httpd.conf file, which pulls itself back in via a section. Any additional arguments passed to the write method will be added to the generated httpd.conf file, and will override those defaults set in the section. This module is handy mostly for starting httpd servers to test mod_perl scripts and modules. AUTHOR ====== Doug MacEachern SEE ALSO ======== mod_perl(3), Apache::PerlSections(3)  File: pm.info, Node: Apache/iNcom, Next: Apache/iNcom/CartManager, Prev: Apache/httpd_conf, Up: Module List An e-commerce framework. ************************ NAME ==== Apache::iNcom - An e-commerce framework. SYNOPSIS ======== - Configure Apache and mod_perl - Create databases - Install Apache::iNcom - Design your e-commerce site. - Wait for incomes. DESCRIPTION =========== Apache::iNcom is an e-commerce framework. It is not a ready-to-run merchant systems. It is an integration of different components needed for e-commerce into a coherent whole. The primary design goals of the framework are flexibility and security. Most merchant systems will make assumptions in the way your catalog's data, customer's data are structured or on how your order process works. Most also imposes severe restrictions on how the user will interface to your electronic catalog. This is precisely the kind of constraints that Apache::iNcom was designed to avoid. Apache::iNcom provides the following infrastructure : - Session Management - Cart Management - Input Validation - Order management - User management - << Easy >> database access - Internationalization - Error handling Most of the base functionalities of Apache::iNcom are realized by leveraging standard and well known modules like DBI(3) for generic SQL database access, HTML::Embperl(3) for dynamic page generation, Apache::Session(3) for session management, mod_perl(3) for Apache integration and Locale::Maketext(3) for localization. Here are its assumptions : - Data is in a SQL database which supports transactions. - Interface is in HTML. - Session is managed through cookies. REQUIREMENTS ============ - DBI 1.13 - mod_perl 1.21 - libapreq 0.31 - HTML::Embperl 1.2b10 - Apache::Session 1.03 + generate_id patch - MIME::Base64 - Locale::Maketext 0.17 + currency patch - apache 1.3.6 or later - Database which supports transactions. (tested with PostgreSQL 6.5.x) CONFIGURATION ============= Apache::iNcom is configured using standard the Apache directives PerlSetVar. Activating Apache::iNcom for a particular virtual host is a simple as PerlInitHandler Apache::iNcom PerlSetVar INCOM_URL_PREFIX /incom/ PerlSetVar INCOM_ROOT pages This will make all URL starting with `/incom/' served dynamically by Apache::iNcom. Additionnaly different modules used by Apache::iNcom will be configured by profile files. Consult the appropriate module documentation for details. GENERAL DIRECTIVES ------------------ INCOM_URL_PREFIX This is the prefix that must match for the URI to be serve by Apache::iNcom. THIS PREFIX MUST ENDS WITH A SLASH (/). To make all files Apache::iNcom page, use / as prefix. This wouldn't work well for images and other binary files though. Use only / as prefix, if binary files are served by another server. INCOM_ROOT This is the path to the directory where Apache::iNcom requests will be mapped. For example, if you have a INCOM_URL_PREFIX of `/incom/' and a INCOM_ROOT of `/home/incom/site/pages', the request `/incom/index.html' will be mapped to `/home/incom/site/pages/index.html'. Default is to use the server's document root. INCOM_INDEX This is page that will be used when accessing directory. Defaults to `index.html' INCOM_TEMPLATE_PATH Colon separated list of directory to search when using the `Include()' function. (See Apache::iNcom::Request(3) for more information). Non absolute paths are relative to the server's root. DATABASE DIRECTIVES ------------------- INCOM_DBI_DSN The DBI(3) URL to use to open a database connection. INCOM_DBI_USER Username to use for the database connection. INCOM_DBI_PASSWD Password to use for the database connection. INCOM_DBI_TRACE Sets the tracing level for the connection. INCOM_DBI_LOG File where the DBI(3) trace output will go. INCOM_SEARCH_PROFILE DBIx::SearchProfiles(3) profile file that will be used to configure the $DB object accessible in Apache:iNcom pages. If non-absolute, it is relative to the server's root. Defaults to `conf/search_profiles.pl' relative to the server's root. See DBIx::SearchProfiles(3) for details on the format of this file. To turn off the use of the search profiles set this directive to `NONE'. PROFILES DIRECTIVES ------------------- INCOM_INPUT_PROFILE Sets the input profile that will be used to initialize the $Validator object. Defaults to `conf/input_profiles.pl' relative to server's root. See HTML::FormValidator(3) for details on the format of this file. To turn off the creation of an input profile set this directive to `NONE'. INCOM_PRICING_PROFILE Sets the pricing profile that will be used to initialize the $Cart object. Defaults to `conf/pricing_profile.pl' relative to server's root. See Apache::iNcom::CartManager(3) for details on the format of this file. If you don't need the cart management feature, set this directive to `NONE'. INCOM_ORDER_PROFILE Sets the order profiles file that will be used to initialize the $Order object. Defaults to `conf/order_profiles.pl' relative to server's root. See Apache::iNcom::OrderManager(3) for details on the format of this file. If you don't need this feature, you can set this directive to `NONE'. USERDB DIRECTIVES ----------------- INCOM_USERDB_PROFILE Name of the profile to use for the user database. Defaults to `userdb'. See DBIx::UserDB(3) for more information. To disable the use of a DBIx::UserDB object, sets this directives to `NONE'. INCOM_GROUPDB_PROFILE Name of the profile to use for the group database access. Defaults to `groupdb'. See DBIx::UserDB(3) for more information. INCOM_SCRAMBLE_PASSWORD Turn on or off scrambling of user's password in the UserDB. LOCALIZATION DIRECTIVES ----------------------- INCOM_DEFAULT_LANGUAGE The language of the files without a language extension. Defaults to `en'. INCOM_LOCALE The package uses to create Locale::Maketext(3) instance. If this is set, an instance appropriate for the user's locale will be available through the $Locale object. SESSION DIRECTIVES ------------------ INCOM_SESSION_SERIALIZE_ACCESS Set this to 1 to serialize access through session. This will make sure that only one session's request is processed at a time. You should set this to 1 if your site uses frameset. INCOM_SESSION_SECURE Sets this to true if you want the cookie that contains the session id to be only transmitted over SSL connections. Be aware that setting this variable to true will require that all Apache::iNcom transactions be conducted over SSL. INCOM_SESSION_DOMAIN The domain to which the Apache::iNcom session's cookie will be transmitted. You can use this, if you are using a server farm for example. INCOM_SESSION_PATH The path under which the session id is valid. Defaults to INCOM_URL_PREFIX. INCOM_SESSION_EXPIRES The time for which the use session is valid. Defaults is for a browser session. (Once the user exists its browser session will become invalid). ERROR HANDLING DIRECTIVES ------------------------- INCOM_ERROR_PROFILE The error profile that will be used for displaying server error. INCOM_ERROR_ROOT The directory which contains error pages. If a non absolute path is specified, it is relative to the server's root. SESSION HANDLING ================ On the user's first request, a new session is created. Each and every other request will be part of a session which will used to track the user's cart and other such things. The session id is returned to the user in a cookie. COOKIES MUST BE ENABLED for Apache::iNcom to function. Fortunately, Apache::iNcom detects if the user has cookies turned off and will send the user an error. Cookies are used for security and confidentiality. The session id is a truly random 128bits number, which is make it very much unguessable. That means that you can't try to stomp into another user's session. That is a good thing since having access to the session id means having access to a whole bunch of informations. (What information is application specific.) IP address aren't used to restrict the session access because of the various problems with proxies and other Internet niceties. Now, what has this to do with cookies ? Well, using URL rewriting was originally considered, but then two big issues cralwed in : proxies and the Referer header. Having the session id embedded in the URL means that our precious session id will be stored in various log files across multiple server (web server, proxy server, etc) This is a bad thing. Also, must request contains a Referer header which means that the session id is likely to leak to third party sites which are linked from your site (or not, Netscape used to send the header even if the user only typed in the new URL while viewing your page). This is another bad thing, and this is why we are using cookies. APACHE::INCOM PAGES =================== Apache::iNcom pages are HTML::Embperl pages with some extra variables and functions available. See Apache::iNcom::Request(3) for details. You may also which to consult the HTML::Embperl documentation for syntax. Additionnaly, the normal $req_rec object in the page is an instance of Apache::Request(3) so that you can handle multipart upload. DATABASE CONNECTIVITY ===================== The database connection is opened once per request and shared by all modules that must use it. Database access is mediated through the use of the DBIx::SearchProfiles(3) module. Connections are opened in commit on request mode. The database connection is commit after the page is executed. If an error occurs, the transaction will be rolled back. The application may elect to commit part of the transaction earlier. CART MANAGEMENT =============== See Apache::iNcom::CartManager(3) for details. ORDER MANAGEMENT ================ See Apache::iNcom::OrderManager(3) for details. USER MANAGEMENT =============== User management is handled through the DBIx::UserDB(3) module. LOCALIZATION ============ Apache::iNcom is designed to make it easy to adapt your e-commerce application to multiple locale. The framework uses Locale::Maketext(3) for message formatting. All pages may have a localized version available. The localized should have an extension describing its language. (.en for English, .fr for French, .de for German, etc.) The user locale will be negotiated through the Accep-Language header which is part of the HTTP protocol. It can also be set explicitely by sending the user to a special link (since not many users took the time to configure their browser for language negotiation). The URL : I/incom_set_lang/I This will set the language to use in the user's session. SECURITY ======== Apache::iNcom has been with security has one of its primary design goal. 1. Session ID are 128bits truly random number. 2. Session ID are transmitted only by cookies to assure confidentiality. 3. There are no user transmitted magic variables. Form data doesn't act upon the framework. All actions are triggered by the application and not the user. All form data that should be used for action are determined by the application through the various profiles. This means that you won't be burned by a magic feature that sprung without you knowing it. 4. Regular access control of Apache can be used. Also see the ACLs mechanism offered by the DBIx::UserDB(3) for access control with finer resolution than URL or file based. 5. SSL can (and should) be used to assure confidentiality. 6. Executable content (pages) that shouldn't be directly accessible from the user (include file, error pages, etc) can be kept in separate directory which aren't accessible directly. The major (current) security limitations is that the application programmer is trusted. Apache::iNcom pages have complete control over the Apache server environment in which they run. Keep this in mind when running multiple sites. Future version will use the Safe(3) module to improve on this. MULTIPLE CATALOGS ================= Multiple e-commerce sites can easily be run by using the VirtualHost capability of apache. PERFORMANCE AND SCALABILITY =========================== No state is kept between requests which makes it easy to scale the load on Apache::iNcom across multiple server. mod_perl general tips for improving performance should be applied. See the mod_perl guide for details (http://perl.apache.org/guide/). ERROR HANDLING ============== Error are handled in a way similar to the ErrorDocument functionality. The error profile is an file which should eval to an hash reference. Keys are error number and values are the file that should be returned on error. The pages are assumed to be relative to the INCOM_ERROR_ROOT directory, or if unspecified the INCOM_ROOT. If a localized version of the page exists, that one will be use. The page will be executed as a normal Apache::iNcom pages. Error are keyed either by the HTTP response code (404,403,500, etc) or by an arbitrary key for application specific error. In order to return an arbitrary error, you set the pnote *INCOM_ERROR* in the page before returning an error. Example: $req_rec->pnotes( "INCOM_ERROR", "validation_failed" ); die "validation_failed"; The page linked to the "validation_failed" key in the error profile will be used. The "no_cookies" key is used to find the error page to return in case the user has turned off cookies. In the case of an error handler trigerred by an error in an HTML::Embperl page. The error page will received in the @param array the error messages emitted by HTML::Embperl. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom::Request(3) Apache::iNcom::CartManager(3) Apache::iNcom::OrderManager(3) DBIx::SearchProfiles(3) DBIx::UserDB(3) Locale::Maketext(3) HTML::Embperl  File: pm.info, Node: Apache/iNcom/CartManager, Next: Apache/iNcom/Localizer, Prev: Apache/iNcom, Up: Module List Object responsible for managing the user shopping cart. ******************************************************* NAME ==== Apache::iNcom::CartManager - Object responsible for managing the user shopping cart. SYNOPSIS ======== $Cart->order( \%item ); my $items = $Cart->items; $Cart->empty; DESCRIPTION =========== This is the part of the Apache::iNcom framework that is responsible for managing the user shopping cart. It keep tracks of the ordered items and is also responsible for the pricing of the order. It this is module that computes taxes, discount, price, shipping, etc. DESIGN RATIONALE ================ Well not completly since all these operations are delegated to user implemented functions implemented in a pricing profile. The idea behind it is to make policy external to the framework. One thing that varies considerably between different applications is the pricing, discount, taxes, etc. So this is left to the implementation of the application programmer. PRICING PROFILE =============== The pricing profile is a file which is C{eval}-ed at runtime. (It is also reloaded whenever it changes on disk. It should return an hash reference which may contains the following key : item_price The function should return the price of the item. The function is passed only one parameter : the item which we should compute the price. Ex: item_price => sub { my $item = shift; my $data = $DB->template_get( "product", $item->{code} ); return $data->{price}; } item_discount The function should return the discounts that apply for that particular item. It can return zero or more discounts. It returning more that one discount return a an array reference. Discount are substracted from the item price so don't return a percentage. Ex: item_discount => sub { my $item = shift; # Discount are relative to item and quantity my $data = $DB->template_get( "discount", $item->{code}, $item->{quantity} ); return unless $data; # No discount # Discount is proportional to the price return $item->{price} * $data->{discount}; } The subtotal of the cart is equal to the sum of ($item->{price} - $item->{discount}) * $item->{quantity} shipping This function determines the shipping charges that will be added to the subtotal. The function receives as arguments the subtotal of the cart and an array ref to the cart's items. It should return zero or more shipping charges that will be added to the subtotal. If returning more that one charges, return an array reference. Ex: shipping => sub { # Flat fee based shipping charges if ( $Session{shipping} eq "ONE_NIGHT" ) { return 45; } else { return 15; } } discount That function determines discount that will be substracted from the subtotal. Function is called with 3 arguments, the subtotal of the cart, the shipping charges and an array reference to the cart's items. Again the function may elect to return zero or more discounts and should return an array reference if returning more that one discounts. Ex: discount => sub { my $subtotal = shift; my $user = $Request->user; return unless $user->{discount}; return $subtotal * $user->{discount}; } taxes That functions determines the taxes charges that will be added to the order. It should return zero or more taxes. If the functions returns more that one taxes, it should return an array reference. The functions receives 4 arguments, the cart's subtotal, the shipping charges, the discount and the cart's items as an array reference. Ex: taxes => sub { my ( $sub, $ship, $disc ) = @_; # We only charges taxes to Quebec's resident. All our # items are taxable and is shipping. if ( ${$Request->user}->{province} eq "QC" ) { my $taxable = $sub + $ship - $disc; my $gst = $taxable * 0.07 my $gsp = ($taxable + $gst) * 0.075 return [ $gst, $gsp ]; } else { return undef; } } If one of these functions is left undefined. The framework will create one on the fly which will return 0. (No taxes, no discount, no shipping charges, item is free, etc). All those functions are defined and execute in the namespace of the pages which will use the $Cart object. This means that those functions have access to the standard Apache::iNcom globals ($Request, %Session, $Localizer, $Locale, etc ). DONT ABUSE IT. Also, don't call any methods on the $Cart object or you'll die of infinite recursion. WHAT IS AN ITEM =============== An item is simply an hash with some reserved key names. All other keys are ignored by the CartManager. Each item with the same (non reserved) key values is assumed to be identic in terms of price, discount, etc. This design was chosen to handle the infinite variety of item attributes (color, size, variant, ...). The framework doesn't need knowledge of those, only the application specific part. (The pricing functions.) These are reserved names and can't be used as item attributes : quantity, price, discount, subtotal INITIALIZATION ============== An object is automatically initialized on each request by the Apache::iNcom framework. It is accessible through the $Cart global variable in Apache::iNcom pages. METHODS ======= order ( \%item, ... ) --------------------- This method will add all the specified items (hash reference) to the Cart. The quantity ordered should be specified in the quantity attribute. (If unspecified, it is assumed to be one). If an identical item is already in the cart, the quantity will be added. Use a negative quantity to remove from the quantity ordered. If the new quantity is lower or equal to zero it will be removed. Use a quantity of 0 to remove an item. empty ----- Removes all items from the cart. is_empty -------- Return true if no items are in the cart. items ----- Return all the ordered items as an array. Each item have the following attribute set : quantity The quantity of the item ordered. price The price of that item. discount The discounts applied to this item. subtotal That item subtotal. subtotal -------- Returns the cart subtotal. (This is before global discount, shipping charges and taxes.) taxes ----- Returns the taxes that will be added to the order. total ----- Returns the order total. (subtotal + shipping charges - discounts + taxes ). discount -------- Returns the overall discount that applied to this order. shipping -------- Returns the shipping charges for this order. item_price ( \%item ) --------------------- Returns the price of the item specified. If no quantity is specified, a quantity of 1 is assumed. This method doesn't modify the cart. item_discount ( \%item ) ------------------------ Returns the discounts associated with the specified item. It no quantity is specified, a quantity of 1 is assumed. This method doesn't modify the cart. item_pricing ( \%item ) ----------------------- Returns the item as it would be added to the cart. quantity, price, discount and subtotal will be set in the returned item. This method doesn't modify the cart. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) Apache::iNcom::Request(3) Apache::iNcom::OrderManager(3)  File: pm.info, Node: Apache/iNcom/Localizer, Next: Apache/iNcom/OrderManager, Prev: Apache/iNcom/CartManager, Up: Module List Object responsible for the localization of the generated request. ***************************************************************** NAME ==== Apache::iNcom::Localizer - Object responsible for the localization of the generated request. SYNOPSIS ======== my $file = $Localizer->find_localized_file( $filename ); my $bundle = $Localizer->get_handle( "Site_L10N" ); DESCRIPTION =========== This module is used for localization in the Apache::iNcom framework. It should be used for operation which are locale sensitive. (Messages display, currency and date formatting, etc.) INITIALIZATION ============== An object is automatically initialized on each request by the Apache::iNcom framework. The list of preferred languages is determined by using the Accept-Language HHTP header. The default language is set to the one specified in the configuration. It is accessible through the $Localizer gobal variable in the Apache::iNcom pages. METHODS ======= default_lang ------------ Get or set the default language. preferred_lang -------------- Get or set the user's preferred language. preferred_langs --------------- Get or set the user's preferred languages in order of preferences. get_handle ( $base_package ) ---------------------------- This method will initialize a Locale::Maketext object of the $base_package using the user's list of preferred languages. This object should be used for localization of messages and such. See that module documentation for details (or the article about it The Perl Journal #8). find_localized_file ( $filename ) --------------------------------- This method will try to find a properly localized version of the $filename. Localized version of the file name should have the same name with the language extension appended. If the file without extension exists, it is assumed to be in the default language. Ex: file.txt -> English file.txt.fr -> French file.txt.es -> Spanish file.txt.fr-CA -> French Canadian AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Locale::Maketext(3) Apache::iNcom(3) Apache::iNcom::Request(3) I18N::LangTags(3)  File: pm.info, Node: Apache/iNcom/OrderManager, Next: Apache/iNcom/Request, Prev: Apache/iNcom/Localizer, Up: Module List Module responsible for order management. **************************************** NAME ==== Apache::iNcom::OrderManager - Module responsible for order management. SYNOPSIS ======== my $order = $Order->checkout( "order", $Cart, %fdat ); my $report $Order->order_report( $order ); DESCRIPTION =========== This is the part of the Apache::iNcom framework that is responsible for managing the order process. Once the user is ready to check out, the OrderManager rides in. This module enters the user's order in the database according to an order profile. It can also generate order reports and such. It is in that module that future development will place links with CyberCash (tm) and other online payment systems. DATABASE ======== The order should be entered in two tables. One table table contains the global order informations : order no, client's information, status, total, taxes, etc., and another table contains the ordered items. To make order customizable, the OrderManager uses DBIx::SearchProfiles to insert the information. That design is similar to DBIx::UserDB in that only a few fields are required by the framework and the schema can easily be adapted for application specific needs. The mandatory fields in the main table are the order_no field, which should be a primary key on the table, and the status field. The status field is used to track the order process. You may also want to add monetary fields for total, subtotal and for the taxes, shipping and discount informations since that will always be available in the order. The mandatory fields in the items table is order_no which links the items to the order table. What will be inserted in that table are the cart items, so you may want to use the following fields : price, subtotal, quantity and fields for the discount information. ORDER PROFILES ============== The order profiles is a file which is C{eval}-ed at runtime. (It is also reloaded whenever it changes on disk. It should return an hash reference which contains the name of a profile associated with an hash reference which may contains the following items : order_template The record template that will be used to insert the order informations. order_item_template The record template that will be used to insert order items. order_no The template query that will be used to generate order number. taxes_fields The field names that should be given to the order's taxes. This is an array reference which defaults to [taxes0, taxes1, taxes2...] if there is more than one taxes or [ taxes ] if there is only one taxes. shipping_fields The field names that should be given to the order's shipping charges. This is an array reference which defaults to [ shipping0, shipping1, shipping2...] if there more than one shipping charges or [ shipping ] if only one is present. discount_fields The field names that should be given to the order's discounts. This is an array reference which defaults to [discount0, discount1, discount2...] if there more than one discount or [ discount ] if only one is present. item_discount_fields The field names that should be given to the items' discounts. This is an array reference which defaults to [discount0, discount1, discount2...] if there more than one discount or [ discount ] if only one is present. Example of an order profile : { order => { order_template => "order", order_item_template => "order_items", order_no => "order_no", taxes_fields => [qw( gst gsp ) ], }, } INITIALIZATION ============== An object is automatically initialized on each request by the Apache::iNcom framework. It is accessible through the $Order global variable in Apache::iNcom pages. METHODS ======= checkout ( $name, $cart, $order_data ) -------------------------------------- This method enter the user order in the database. It takes the following parameters : $name The name of the order profile to use. $cart The cart that contains the user's order. $order_data An hash reference which contains other informations that should be stored with the order. (Like customer's name and address for example.) The cart is emptied if the checkout is successful. NOTE: This is the only method in the framework that will do an explicit commit to make sure that the order is correctly entered in the database. The method returns an hash references which contains the order informations. order_report ( $order, $template ) ---------------------------------- This method will generate an order report for a particular order. The first parameter is the order as returned by checkout, the second is the template file that should be used. This is a standard Apache::iNcom pages. The report will be generated in the namespace of the calling page, so standard Apache::iNcom globals will be accessible. DONT ABUSE IT. Also the order for which the report is generated will be accessible through the %order global hash. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) Apache::iNcom::Request(3) Apache::iNcom::CartManager(3)