NAME

OpenInteract2 Packages

SYNOPSIS

This document describes the packaging system in OpenInteract2.

INTRODUCTION

A package is all the code, SQL structures, configuration information, initial data and security settings, documentation and anything else necessary to define an OpenInteract2 application. A single application may actually comprise multiple packages, but each package generally defines some feature scope.

In OpenInteract2, packages implement the actual application functionality while the core framework handles the storage interface (e.g., putting your objects in a database), dispatches URL requests to your objects (this is called handling an action), security, authentication and authorization, and session management.

An application usually defines persistent objects that keep state from request to request and server shutdown to server shutdown. It also needs to define how the objects are to be manipulated, which users can access them and how functionality is exposed to the user (by way of a URL-to-action mapping).

OpenInteract2 comes with tools to install, uninstall and query currently installed packages. This greatly simplifies the task of creating, testing and distributing your application.

PACKAGE CONTENTS

What goes into a package? In general, you will find:

• Perl module code: This can include action code (normally found under OpenInteract2::Action), SPOPS object code (OpenInteract2) and installation code (OpenInteract2::SQLInstall), along with normal Perl routines and objects used to support these activities.

• Configuration: Files in the conf/ directory: action.ini configures the package's actions and one or more spops*.ini files define persistent objects. Both of these files are discussed further below.

• Templates: Graphical interface to package functionality. Normally these are HTML files interspersed with template processing commands which makes the data the package manages visible to the user.

• Installation information: This includes the package.conf file along with the SQL installation class, normally found under OpenInteract2::SQLInstall.

• Package data structures and data: These are used by the SQL installation class to install tables (found in struct/ and any initial and security data data/ needed by the package.

• Documentation: The 'create_skeleton' command of oi2_manage will create a preliminary POD file for you which documents your package in doc/. You are strongly encouraged to fill in the blanks and add meaningful detail along with any other necessary files to let people know what functionality your package provides.

HOW DO I CREATE A PACKAGE?

The oi2_manage script included with OpenInteract2 will create a basic package skeleton for you. Here's an example:

 $ oi2_manage create_package \
       --package=mypackage \
       --source_dir=/path/to/OI2-source

which creates the following directories and files:

 mypackage                                       # Main directory
 mypackage/package.conf                          # Basic package configuration (name, ...)
 mypackage/MANIFEST                              # List of files in package
 mypackage/MANIFEST.SKIP                         # Regexes to skip when creating MANIFEST
 mypackage/conf                                  # Configuration directory
 mypackage/conf/spops.ini                        # Persistent object(s) configuration
 mypackage/conf/action.ini                       # Action(s) configuration
 mypackage/data                                  # Package data/security directory
 mypackage/doc                                   # Documentation directory
 mypackage/doc/mypackage.pod                     # Starter documentation
 mypackage/struct                                # Package table definition directory
 mypackage/template                              # Template directory
 mypackage/template/sample.tmpl                  # Sample Template Toolkit template
 mypackage/script                                # Tools program directory
 mypackage/html                                  # Static html directory
 mypackage/html/images                           # Image directory
 mypackage/OpenInteract2                         # Object hierarchy directory
 mypackage/OpenInteract2/Action                  # Action implementation directory
 mypackage/OpenInteract2/Action/Mypackage.pm     # Sample action with 'hello' and 'list' tasks
 mypackage/OpenInteract2/SQLInstall              # Structure/data installation directory
 mypackage/OpenInteract2/SQLInstall/Mypackage.pm # Sample structure/data installation

You will normally need to edit/add the following:

 mypackage/package.conf                          # Add name, version, author information
 mypackage/MANIFEST                              # Add names of distribution files
 mypackage/conf/spops.ini                        # Describe the objects your package uses
 mypackage/conf/action.ini                       # Map URLs to handlers in your package
 mypackage/data                                  # Specify the initial data and security
 mypackage/struct                                # Describe the tables used to store your objects
 mypackage/template                              # HTML to display and manipulate your objects
 mypackage/OpenInteract2                         # Optional Perl modules defining object behavior
 mypackage/OpenInteract2/Action                  # Manipulate objects for desired functionality
 mypackage/OpenInteract2/SQLInstall              # Change the tables, sequences, security, etc.
 mypackage/doc/mypackage.pod                     # Last but not least, tell the world about it

By the way, the MANIFEST file can be created automatically. (Perl is great.) Here's how:

 $ cd /path/to/mypackage
 $ perl -MExtUtils::Manifest -e 'ExtUtils::Manifest::mkmanifest()'

That's it! If you have an old 'MANIFEST' file in the directory it will be copied to 'MANIFEST.bak'. Also note that files matching patterns in the 'MANIFEST.SKIP' file will not be included.

WHAT'S IN A PACKAGE OBJECT?

Now that you've created a package already, you've seen most of its contents. (The ones you care about, anyway.) However, each package is a Openinteract2::Package object -- a simple Perl object that's able to lookup files, create itself, install itself to a website and more

Here are some sample usages, cribbed from the OpenInteract2::Package documentation:

 # Read information about a package distribution
 
 my $package = OpenInteract2::Package->new({
                    package_file => '/home/cwinters/pkg/mynewpackage-1.02.zip' });
 my $config = $package->config;
 print "Package ", $package->name, " ", $package->version, "\n",
       "Author ", join( ", ", @{ $config->author } ), "\n";
 my $files = $package->get_files;
 foreach my $filename ( @{ $files } ) {
     print "   File - $filename\n";
 }

For each website OpenInteract2 maintains a file with the installed packages. This is a simple INI file located in $WEBSITE_DIR/conf/respository.ini. Each package should only be listed once, and the repository only maintains name, version, directory and installation date information. The rest is stored in the package itself.

You can see what packages are installed to a website using the oi2_manage tool:

 $ oi2_manage list_packages --website_dir=$WEBSITE_DIR

Which will give you output like this:

 PROGRESS: Starting task
 PROGRESS: Task complete
 ACTION: 
     OK:     Package base-2.02 in site
     OK:     Package base_box-2.01 in site
     OK:     Package base_error-2.02 in site
     OK:     Package base_group-2.01 in site
     OK:     Package base_page-2.04 in site
     OK:     Package base_security-2.01 in site
     OK:     Package base_template-3.00 in site
     OK:     Package base_theme-2.01 in site
     OK:     Package base_user-2.03 in site
     OK:     Package full_text-2.01 in site
     OK:     Package news-2.01 in site
     OK:     Package lookup-2.00 in site
     OK:     Package object_activity-2.02 in site
     OK:     Package system_doc-2.00 in site

COPYRIGHT

Copyright (c) 2002-2003 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL