NAME

OpenInteract Packages - Managing and distributing applications

SYNOPSIS

This document describes the packaging system in OpenInteract.

INTRODUCTION

A package is all the code, SQL structures, configuration information and anything else necessary to implement functionality in OpenInteract.

In OpenInteract, packages implement the actual application functionality. OpenInteract 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.

Applications need to define objects, which is how an application handles its state. 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).

Obviously, OpenInteract 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 handler code, SPOPS object code and installation code.
Configuration: Generally this includes two files in the conf/ directory: action.perl and spops.perl, both of which are discussed further below.
Templates and Components: 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.
Package data structures and data: These are used by the SQL installation class to install tables and any initial data needed by the package. These data can also be installed to other tables in OpenInteract.
Documentation: The 'create_skeleton' command of oi_manage will create a preliminary POD file for you which documents your package. 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 oi_manage script included with OpenInteract will create a basic package skeleton for you. Here's an example:

 oi_manage --package=mypackage --base_dir=/tmp/OpenInteract \
           create_skeleton

Will create the following 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.perl      # Persistent object(s) configuration
 mypackage/conf/action.perl     # Action(s) configuration
 mypackage/data                 # Package data/security directory
 mypackage/doc                  # Documentation directory
 mypackage/doc/mypackage.pod    # Starter documentation
 mypackage/doc/titles           # Map documentation name to subject
 mypackage/struct               # Package table definition directory
 mypackage/template             # Template directory
 mypackage/script               # Tools program directory
 mypackage/html                 # Static html directory
 mypackage/html/images          # Image directory
 mypackage/OpenInteract         # Object hierarchy directory
 mypackage/OpenInteract/Handler # Package handler directory

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.perl      # Describe the objects your package uses
 mypackage/conf/action.perl     # 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/OpenInteract         # Optional Perl modules defining object behavior
 mypackage/OpenInteract/Handler # Manipulate objects for desired functionality
 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 OpenInteract::Package object -- a normal SPOPS object.

OpenInteract maintains a registry of installed packages in a central location. (To find the file, go to the conf/ directory of your base OpenInteract installation. The package_install.gdbm holds the information.)

This registry includes meta information about all currently installed packages -- author, install date, version, etc. You can browse the information using a command-line tool (named oi_manage) to see what is currently installed, along with querying the information to find dependencies, authors, etc.

Properties of the OpenInteract::Package object:

name ($)

Name of package

version ($)

Version of package

author (\@)

Author(s) of package, full name and email address is used for each entry; the list should be sorted in order of importance

url ($)

Web address with more information about the package

description ($)

Two or three paragraphs about the package

notes ($)

Notes about this particular installation of a package.

sql_installer ($)

Name of class which will get called by OpenInteract::SQLInstall to install the SQL structures, data and security necessary for this package.

last_updated_on ($)

Date this package was last updated

last_updated_by ($)

User who updated this package

installed_on ($)

Date this package was installed

installed_by ($)

User who installed this package

AUTHORS

Chris Winters <chris@cwinters.com>

Christian Lemburg <lemburg@aixonix.de>

Home | Wiki | OI 1.x Docs | OI 2.x Docs