- NAME
- SYNOPSIS
- INTRODUCTION
- PACKAGE CONTENTS
- HOW DO I CREATE A PACKAGE?
- WHAT'S IN A PACKAGE OBJECT?
- SEE ALSO
- AUTHORS

# 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

# SEE ALSO

`OpenInteract::Package`

`OpenInteract::PackageRepository`

# AUTHORS

Chris Winters <chris@cwinters.com>

Christian Lemburg <lemburg@aixonix.de>