NAME

oi_manage - Manage OpenInteract websites and packages

SYNOPSIS

oi_manage [options] [command]

Administration commands:

install, upgrade, install_package

Package development commands:

create_skeleton, export_package, check_package

Website creator commands:

create_website, apply_package, upgrade_package,
remove_package, install_sql, install_template,
dump_template, remove_template, refresh_doc,
test_db, test_ldap, change_spops_driver

Other commands:

initial_packages, list_packages, list_actions, list_objects

For more information, run 'oi_manage --man'

COMMON COMMANDS

Commands by the Administrator:

install             - Install OpenInteract to base directory
upgrade             - Upgrade core OpenInteract packages
install_package     - Install package to the base

Commands by the Package Developer:

create_skeleton     - Create a skeleton package for development
export_package      - Export package(s) to distribution file(s)
check_package       - Ensure that package passes initial inspection

Commands by the Website Creator:

create_website      - Create a new website
apply_package       - Install a package from base to website
upgrade_package     - Upgrade a website package
remove_package      - Remove a package from a website
install_sql         - Install the SQL for packages
install_template    - Install package templates to the database
dump_template       - Dump package templates to the filesystem
remove_template     - Remove package templates from the database
refresh_doc         - Sync website docs to base installation docs
update_object       - Re-save all objects in a given class
test_db             - Test database settings in 'server.perl'
test_ldap           - Test LDAP settings in 'server.perl'
change_spops_driver - Change the SPOPS driver for your objects

Other commands:

initial_packages    - List packages marked as 'initial'
list_packages       - List packages installed to app or base
list_actions        - List actions currently implemented in website
list_objects        - List object classes currently implemented in website

COMMON OPTIONS

Summary of common options:

--base_dir           OpenInteract install directory
--website_dir        Website install directory
--website_name       Website name
--package_dir        Directory with package subdirectories (usually devel)
--package_file       Distribution file containing an OpenInteract package
--package            List packages to operate on
--package_list_file  File specifying packages to operate on
--dump_dir           Directory to dump stuff into
--driver             A generic driver (DBI, SPOPS, etc.)
--object             An SPOPS object tag
--help               Display brief help
--man                Display full help

Details:

--base_dir=/path/to/OpenInteract

   Name the directory where OpenInteract is installed. You can set
   the environment variable 'OPENINTERACT' instead of passing the
   value on the command-line, We recommend you set this environment
   variable for all OpenInteract users and developers.

--website_dir=/path/to/OpenInteract/website

   Name the directory where an OpenInteract website is
   installed. This directory will have the website package database
   in the 'conf/' directory. You can set the environment variable
   'OIWEBSITE' instead of passing the value on the command
   line. However, setting this permanently will cause you problems,
   so it is best to set on a temporary basis.

--website_name=MyAppName

   Name of your website. Must be all one word (no underscores or
   anything), and StudlyCaps are A-OK (in fact, recommended). Note
   that this name becomes your perl namespace, so all your packages
   become 'MyAppName::News' and 'MyAppName::WebLink::Handler', etc.

--package_dir=/path/to/my/devel/packages

   Name the directory where you do your OpenInteract
   development. This is used by the 'export_package' and the
   'check_package' commands. This directory can also be where a
   single package is -- we also look at the 'package' parameter to
   discern which way to use 'package_dir'.

--package_file=an-oi-package-x.xx.tar.gz

   OpenInteract packages are distributed in common tarballs, which
   can be created by the 'export_package' command and installed by
   the 'install_package' command.

--package=a,b,c,d  OR --package=a --package=b --package=d

--package_list_file=/path/to/package_list

   File containing package names, one per line, without version
   numbers or anything else. Blank lines and lines beginning with a
   '#' are skipped. You can substitute this wherever you see
   '--package' specified as a parameter in the discussions below.

--dump_dir=/path/to/dump/stuff

   Specify a directory where you would like to dump something -- such
   as the SQL for a package or the templates belonging to a
   package. Dumping routines typically have a designated place for
   this (usually the 'dump/' directory in the area pertaining to what
   is being dumped), but sometimes you might want to put the data
   elsewhere.

--driver=SPOPS::DBI::Pg

   Specify some sort of driver -- this can be used to name an SPOPS
   driver (such as 'SPOPS::DBI::Pg') or a DBD driver ('DBD::mysql')
   when necessary.

--object=SPOPS-object-tag

   Specify the name of an SPOPS object tag. This is not an object
   class but rather the 'alias' by which OpenInteract can refer to an
   object. For instance, the alias for the template objects is
   'site_template' and the alias for the page objects stored in the
   database is 'basic_page'.

--sql_action=(all|structure|data|security|all_data)

   Specify an action to take with the 'install_sql' command. The
   action 'all' is the default if not specified. You should not need
   this often, if at all.

Other options depend on the command you choose and are listed under that command below.

DESCRIPTION

oi_manage is the command-line interface for managing packages within OpenInteract and installing new OpenInteract websites. It is also useful for developers so they can export their work into a tar.gz file for distribution, or install it into the OpenInteract package database.

SHORTCUTS

A few shortcuts that can make your life much simpler.

Environment Variables

Set the 'OPENINTERACT' environment variable and never type '--base_dir=/blah' again.
Set the 'OIWEBSITE' environment variable and never type '--website_dir=/blah' again.

How to do this? If you are on a Linux machine using the bash shell, just do:

export OPENINTERACT=/path/to/base/installation

and

export OIWEBSITE=/path/to/my/website

If you do not wish to type these in everytime you login, just put them in your '.bashrc' or equivalent. (If you do not know what '.bashrc' is, ask your friendly sysadmin.)

Package Names: INITIAL

If you are working with the core set of packages necessary to make OpenInteract function, you should know about the 'INITIAL' keyword.

The 'INITIAL' keyword can be used in place of a package name when you use the '--package' parameter specification. For instance, running:

oi_manage export_package --package_dir=/my/devel/oi/pkg --package=INITIAL

First replaces 'INITIAL' with the list of initial packages, then runs the operation.

You can see the list of initial packages by running:

$ oi_manage initial_packages

Package Names: External File

If you commonly perform an operation on a number of different packages at once, you can store the package names in an external file and refer to it when you run 'oi_manage'.

The file format is simple: one package name per line, blank lines and lines beginning with a comment ('#') are skipped. The following would be a valid file:

BEGIN---------------
# Packages I contribute to
news

# Packages I own and work on
photo_album
recipe_box
bicycle_trip
---------------END

Specify the file to 'oi_manage' using the '--package_list_file' parameter specification.

COMMANDS

The following tools and actions are available from oi_manage:

INSTALL

Command: install

Required options:

--base_dir=/path/to/OpenInteract

Install OpenInteract. Note that you must be in the OpenInteract source directory to run this command. For instance, a typical installation might look like the following sequence:

>> tar -zxvf OpenInteract-1.01.tar.gz
>> cd OpenInteract-1.01
>> perl Makefile.PL
>> make
>> make test
>> make install
(file 'oi_manage' is now in /usr/local/bin)
>> /usr/local/bin/oi_manage --base_dir=/opt/OpenInteract install

You should only ever need to do this once. But just in case, it might be a good idea to keep the initial source directory around.

UPGRADE

Command: upgrade

--base_dir=/path/to/OpenInteract

Upgrade OpenInteract packages. Note that you must be in the OpenInteract source directory to run this command. For instance, a typical upgrademight look like the following sequence:

>> tar -zxvf OpenInteract-1.52.tar.gz
>> cd OpenInteract-1.52
>> perl Makefile.PL
>> make
>> make test
>> make install
(file 'oi_manage' is now in /usr/bin)
>> /usr/local/bin/oi_manage --base_dir=/opt/OpenInteract upgrade

While you run the 'install' command only once, you can run the 'upgrade' command for every new release of OpenInteract that comes out. All old documentation files and configuration samples are saved with an .old suffix, but they will be overwritten (with the new old file) if you run the 'upgrade' command again.

INITIAL PACKAGES

Command: initial_packages

Just lists the initial package oi_manage is currently configured to install when given a 'create_website' command.

LIST PACKAGES

Command: list_packages

Required options -- one of the following:

--base_dir=/path/to/OpenInteract
--website_dir=/path/to/my_website

List the packages currently installed in a website or in the base OI installation.

LIST ACTIONS

Command: list_actions

Required options:

--website_dir=/path/to/my_website

Bootstrap an OpenInteract environment from the command line and inspect it to see what actions are created in the action table.

Output includes the action name, the package the action is found in, and either the class and method used to call it or the template which implements it.

This can be extremely useful if you are unsure what actions your website currently implements, and for ensuring that you do not chose an action for your new package that is already in use elsewhere.

LIST OBJECTS

Command: list_objects

Required options:

--website_dir=/path/to/my_website

Bootstrap an OpenInteract environment from the command line and inspect it to see what SPOPS objects can be created in the environment.

Output is simply the aliases by which the object class are known (frequently just one) and the class implementing the object.

CREATE SKELETON

Command: create_skeleton

Required options:

--package=mypackagename
--base_dir=/path/to/OpenInteract

Creates skeleton package(s) in your current directory for development.

This includes:

The necessary directories
An initial package.conf file
A documentation template and index
Commented sample conf/spops.perl and conf/action.perl, configuration files
Commented sample OpenInteract/SQLInstall file
Commented sample template files in template/dummy.meta, and template/dummy.tmpl
A starter changelog (Changes) and
A working MANIFEST file along with MANIFEST.SKIP with common patterns for files not to include in the MANIFEST.

If you specify multiple packages, multiple directories will be created in your current directory.

EXPORT PACKAGE

Command: export_package

You can run this one of two ways:

Export a single package by changing to its directory and running this command without any parameters.
Specify the following parameters for multiple packages:
```
--package_dir=/path/to/my/packages
--package=x (at least one)
```
All packages you specify that the command can find in the 'package_dir' directory will get distributions created.

This is a utility for people developing new packages for OpenInteract. Some might consider it a Bad Idea to develop packages under the base OpenInteract/pkg directory -- for new uninstalled packages it is not a problem, but once you start doing that you start working on packages in-place, and before you know it everything it out of whack. Best not go there.

So what this utility does is peek into a directory for a 'package.conf' file. This is a simple file with information about your package in a simple format. Here is an example:

name           MyKillerApp
version        1.14
dependency     YourKillerApp 1.20
dependency     TheirLameApp  0.89
author         Zippy Doodad (zippy@doodad.com)
author         Bolt (bolt@uno.com)
url            http://mykillerapp.com/
sql_installer  OpenInteract::SQLInstall::MyKillerApp
description
This package implements what everybody -- especially the town of
Ottumwa, Iowa -- thinks is a KillerApp. You will too.

So we read in configuration and ensure you have the required fields. (Currently, the fields 'name', 'version' and 'author' are required, although no validation is performed on them.)

If the configuration file passes muster, we then check out the MANIFEST that accompanies your package. MANIFEST lists the files that should be distributed with your package.

If 'export_package' finds any files in MANIFEST not in the directory or if it finds files in the directory not specified in MANIFEST, it will give you a warning but still create the distribution. You then have the option of distributing your package as-is (probably a bad idea, but you might have your reasons) or fixing the problem and re-creating the distribution. You can go through this process as many times as necessary since the 'export_package' command does not change any information in your package.

You may also specify a MANIFEST.SKIP file that determines which files should not be compared to the MANIFEST to ensure that you do not have any extra files floating around. Each line in the MANIFEST.SKIP file is a regular expression matching files that should not be included in MANIFEST. For example, if you specify in MANIFEST.SKIP:

\bCVS\b

Then when this command finds files matching this pattern (all your CVS directories) in your package directory, it will not complain and tell you there are extra files in the directory.

(Since we use ExtUtils::Manifest to manipulate the MANIFEST file, including the MANIFEST.SKIP file, you might find it helpful to read more about it.)

The command 'create_skeleton' creates a default MANIFEST and MANIFEST.SKIP for you, although it is your responsibility to add your files to MANIFEST and your exclusion patterns to MANIFEST.SKIP after that.

Once we get this file and directory listing, we use them to create a distribution file -- just a '.tar.gz' file conforming to certain standards -- suitable for installation in another OpenInteract installation with the 'install_package' command.

CHECK PACKAGE

Command: check_package

Required options:

One of the following:

None (check the package in the current directory)
Check the package in a particular directory:
```
--package_dir=/path/to/my/devel/package
```

Check one or more packages in a particular website:

--website_dir=/path/to/my_website
--package=x (at least one)

Check one or more packages in the installation directory.

--base_dir=/path/to/OpenInteract
--package=x (at least one)

This command checks that a package has the bare necessities and that the files at least pass some basic sanity checks.

Files we check:

Changes
package.conf
conf/*.perl
*.pm
<website-name>/*.pm (if this is a website)

We also ensure that the files found in MANIFEST are all there give you a warning if there are extra files in the directory not found in MANIFEST.

It is probably a good idea to always run this before you send a package to someone else. (Commands like this usually spring from the embarrassment of someone else, so learn the lesson :)

This leads to the common idiom of:

> ... work on package ...

> cd /my/package/devel/dir

> oi_manage check_package
(all is ok)

> oi_manage export_package

> scp mypkg-1.21.tar.gz me@mywebste:/home/httpd/pkg

> ...

INSTALL PACKAGE

Command: install_package

Required options:

--base_dir=/path/to/OpenInteract
--package_file=/path/to/package-x.xx.tar.gz

Installs a package from a distribution file, which are just tar.gz files with the package information in them. The steps to install the package include:

Unpack the distribution and determine the package name and version
See if that package and version are already installed
Copy the files to the base OpenInteract directory
Install the package information to the OpenInteract package database

CREATE WEBSITE

Command: create_website

Required options:

--website_name=MyAppName
--website_dir=/path/to/my_website
--base_dir=/path/to/OpenInteract

Creates a new directory for your website and all the necessary subdirectories, so ensure that 'website_dir' does not exist yet.

This command also copies over configuration files and replaces various keys with ones specific to your website. The program creates a simple stash class for you as well as installs the base packages necessary for OpenInteract to function.

After running this command, you typically have to only edit some configuration files and your website can be up and running! See the file INSTALL.website distributed with 0penInteract for more information.

TEST DB

Command: test_db

Required options:

--website_dir=/path/to/my_website

Tests whether you can establish a connection to all the databases for which you have specified parameters in the conf/server.perl configuration file. Also test whether the user specified in each configuration can create a table. This is generally a good indicator of whether the user will have sufficient permissions to run OpenInteract, since a user who can create tables typically has full read/write privileges to the tables created by the account.

***NOTE***

Just because your database connection works from the command line does NOT mean that it will automatically work from your web server. Hopefully (for security purposes), your web server runs under a user with minimal permissions. This can affect shared library and other types of access. In addition, your command-line environment might be set up properly to connect to your database while the web server environment is not. More is in the entry: When I run a perl script from the command line, it works, but, when I run it under the httpd, it fails! Why? in DBI::FAQ.

TEST LDAP

Command: test_ldap

Required options:

--website_dir=/path/to/my_website

Test whether you can establish a connection and bind to all the LDAP directories for which you have specified parameters in the conf/server.perl configuration file.

REFRESH DOC

Command: refresh_doc

Required options:

--website_dir=/path/to/my_website

Refreshes documentation to match that in the base installation directory. Run this if your sysadmin has installed a new OpenInteract version or has downloaded updated documentation for you to use.

The newly refreshed documentation should be immediately available on your website at the URL:

http://mysite.com/oi_docs/

You can also get to it through the 'System Documentation' link found in the 'Admin Tools' box.

Command: refresh_widget

Required options:

--website_dir=/path/to/my_website

Refreshes the template widgets in your website to match the ones in the base installation. Note that your old widgets will be renamed to '$NAME.old'.

Run this if your sysadmin has installed a new OpenInteract version or has downloaded updated widgets for you to use.

The newly refreshed widgets will be available to you immediately on the next mod_perl restart, or if the server is not restarted then whenever the template cache expires.

You will probably not need this as often as 'refresh_doc' since widgets tend to get customized quite heavily.

APPLY PACKAGE

Command: apply_package

Required options:

--website_dir=/path/to/my_website
--package=x (at least one)

Applies a package from the installed base of packages in OpenInteract to your website. (The package must have first been installed with 'install_package', although future versions of OpenInteract may allow you to install a package to a website only.) This includes localizing all the files (changing the namespace from 'OpenInteract::' to 'MyApp::') and copying all the templates, SQL structures and default data/security to your website directory.

APPLYING THE PACKAGE DOES **NOT** INSTALL THE SQL FOR YOU. SEE "INSTALL SQL".

This option will by default apply the latest version of the available package for you. Applying earlier versions is not yet supported.

REMOVE PACKAGE

Command: remove_package

Required options:

--website_dir=/path/to/my_website
--package=x (at least one)

Removes the package from the website. Note that we do not currently support removing the files associated with the package, or the templates in the database that belong to the package. If you want to truly eradicate your package, you should do the following:

>> oi_manage --package=mypackage \
             --website_dir=/path/to/my_website \
             remove_template
>> oi_manage --package=mypackage \
             --website_dir=/path/to/my_website \
             remove_package
>> cd /path/to/my_website/pkg
>> rm -rf mypackage-x.xx

UPGRADE PACKAGE

Command: upgrade_package

Required options:

--website_dir=/path/to/my_website
--package=x (at least one)

Upgrades a package from the base installation to a website. For instance, if your website has the package 'classified-1.04' and the base installation has the package 'classified-1.11', then you can simply do:

>> oi_manage --website_dir=/path/to/my_website --package=classified \
             upgrade_package

Note that the files from the older version of your package are kept intact, but they are no longer used. This program does not currently support the more complicated task of trying to find the differences between your files and the new files -- you are left to your own devices.

NOTE: As of OpenInteract 1.41, you can place your templates in a subdirectory of the site-wide template directory and maintain them throughout package upgrades. For instance, if you are editing templates in the package 'recipe_box', you can place your templates in:

$WEBSITE_DIR/template/recipe_box/recipe_listing.tmpl
$WEBSITE_DIR/template/recipe_box/recipe_detail.tmpl
$WEBSITE_DIR/template/recipe_box/recipe_form.tmpl
...

And when you run an 'upgrade_package' these templates will not be overwritten and will continue to be used by the new package.

CHANGE SPOPS DRIVER

Command: change_spops_driver

Required options:

--website_dir=/path/to/my_website
--driver=SPOPS::Driver::To::Use

Modifies the SPOPS driver used for all the objects in your website. OpenInteract ships with all objects configured for the MySQL database. You can see this in the 'isa' configuration for the object, like this configuration from the User object class:

...,
'object_name' => 'User',
'isa' => [
  'OpenInteract::SPOPS',
  'SPOPS::Utility',
  'SPOPS::Secure',
  'SPOPS::DBI::MySQL',
  'SPOPS::DBI'
],
...,

For this, we would replace SPOPS::DBI::MySQL with the appropriate SPOPS driver. This will normally take the form SPOPS::DBI::xxxx. For example: SPOPS::DBI::Sybase or SPOPS::DBI::Pg.

NOTE: You can accomplish this same task in a more permanent way by editing the global override options file for SPOPS. See OpenInteract::Config::GlobalOverride for details.

UPDATE OBJECTS

Command: update_object

Required options:

--website_dir=/path/to/my_website
--object=SPOPS-object-tag

This action fetches all instances of a particular object class and saves them. This is useful if you have implemented a schema change that needs a save() to activate a trigger which fills data.

For instance, a 'last_update' field gets triggered by a save -- by running this action you automatically set all objects to a known value. Another example would be if your objects use the indexing feature of the full_text package -- just run this action and the index will be automatically updated.

Output is the number of objects touched, saved successfully and any errors encountered.

SQL COMMANDS

One of the difficulties in any website framework is getting data into the framework from somewhere else and getting data out of the framework to somewhere else.

OpenInteract provides a flexible framework for the first and the seedlings of something for the second. Exporting data into the format used by OpenInteract is on the list of things to do and has a relatively high priority, although your help could push it over the top!

INSTALL SQL

Command: install_sql

Required options:

--package=x (at least one)
--website_dir=/path/to/my_website

Other options:

--sql_action=(all|structure|data|security|all_data)

This command goes through a list of packages and installs the initial tables and data for each one. It is also empowered to run perl scripts that set initial security or do other tasks.

Generally, this works by each package creating an Installer Class that is used by OpenInteract::SQLInstall. The dispatching class provides a number of tools for the implementing class so that each package does not need to do terribly much. However, if the package needs to do quite a bit of customization, it can.

Please see the OpenInteract::SQLInstall module for more information on how this whole process works.

Also, note that experts -- people who know what they are doing -- can specify only parts of the process to run. Again, you should do this only if you have a good reason. As an example, you can only run the security installation for a particular package like this:

$ oi_manage install_sql --package=mypkg --sql_action=security

The options for the --sql_action parameter are:

all: Run all three steps. This is the default, and most people will never need to specify an action.
structure: Only install the tables, no data or security.
data: Only install the data, no tables or security. Note that this may leave your setup in an inconsistent state, since you may have data not accessible due to lack of security settings.
security: Only install the security for the data.
all_data: Run both the 'data' and 'security' steps, but do not install the tables.

DUMP SQL

Command: dump_sql

Required options:

--package=x (at least one)
--website_dir=/path/to/my_website

Useful option:

--dump_dir=/path/to/dump/sql

Dumps data from the tables and security used by the website into a number of files. If 'dump_dir' is specified the files will go there; if not, they will go into the 'data/dump/' directory under the package specified in the 'website_dir'.

This is still under development. How this will work:

You define parameters in the SQLInstall class for your package that determines how you want to dump certain data.
After running the command in this script, you will have a set of files in the dump/ subdirectory of one or both of the data/ and struct/ package subdirectories. (Or in the 'dump_dir' that you choose) These files can be distributed with the package and used to install data on other OpenInteract installations.

TEMPLATE COMMANDS

This script should help with the whole template editing process. Editing templates via the browser interface can be tedious. HTML interfaces are, shall we say, not very robust for dealing with most data. (Now, if we can only get XEmacs embedded as a Mozilla widget for the TEXTAREA item...)

Anyway, most people will naturally prefer editing templates in their favorite editor -- say, XEmacs -- and we would like to encourage such productive behavior. We support this in two ways:

Calling Templates

This is covered elsewhere, but worth mentioning here. When you call a template with a last parameter like the following:

{ db => 'my_template_name', package => 'my_pkg' }

The system first looks in the database for a template with the given name. If it is not found, it then looks to the filesystem in the specified package. If it is not found there, the system raises an error which is displayed onscreen.

What this means is that you can start creating your templates using files -- test them, go through umpteen iterations of input-view-debug until everything is stable, then add the template to the database for performance reasons. You can still update the template from there, but the editing cycle once the template is in the database is stretched out. (At least for now it is.)

There are two commands to let you transfer templates between the filesystem and the database, and one to remove them from the database altogether.

INSTALL TEMPLATE

Command: install_template

Required options:

--package=x (at least one)
--website_dir=/path/to/my_website

Each package has its own directory for templates, and you can choose to transfer these files into the database at any time. You can even do so once the templates are already in the database -- the system will first check to see if a template exists and update its information before creating an entirely new one.

Note that all templates require a 'tmpl' file and a 'meta' file. A typical 'tmpl' file might be:

Typical Template File
==============================
[% IF user %]

[%- label = 'User Info'  IF not label -%]

<table border="0" cellpadding="1" bgcolor="[% th.box_border_color %]"
       cellspacing="0" width="[% th.box_width %]">
<tr><td><font size="+1" color="[% th.box_label_font_color %]">
    <b>[% label %]</b>
</font></td></tr>
<tr><td>

  <table border="0" width="100%" cellpadding="4"
         bgcolor="[% th.box_bgcolor %]" cellspacing="0">
  <tr><td align="left">
    <font size="-1" color="[% tg.box_font_color %]">
     <b>[% user.first_name %] [% user.last_name %]</b> ([% user.login_name %])<br>
    </font>
  </td></tr>
  <tr><td align="right"><font size="-1">
    <a href="/User/show/?user_id=[% user.user_id %]">Edit my info</a> |
    <a href="/NoTmpl/Logout/?return=[% return_url %]">Logout</a>
  </font></td></tr>
  </table>

</td></tr>
</table>

[% END %]
==============================

And its accompanying 'meta' file might be:

Typical Meta File
==============================
name: user_info_box
title: Box that shows login user information
package: base_component
Parameters for this component:
--user: the user object (returns nothing if it does not exist)
--return_url: URL of the current page, which we will come back to if
the user logs out
--label: What is the label for the box? (default: 'User Info')
==============================

We use the information in the 'meta' file to name or location template object when we install the templates.

DUMP TEMPLATE

Command: dump_template

Required options:

--package=x (at least one)
--website_dir=/path/to/my_website

Useful option:

--dump_dir=/path/to/dump/stuff

Dumps the templates for a package from the database to the filesystem. If you do not specify a 'dump_dir', all dumped templates are stored in the directory within a package 'template/dump/' rather than just 'template/'. (What you do with the templates after that is your business.)

REMOVE TEMPLATE

Command: remove_template

Required options:

--package=x (at least one)
--website_dir=/path/to/my_website

Removes all templates in the specified package(s) from the database used by 'website_dir'.

OTHER METHODS

If you are adding functionality to this script, these methods can be useful.

initialize_db_actions( $website_dir, $action )

This method initializes OpenInteract without mod_perl, reading in the configuration, creating an OpenInteract::Request object and connecting the database specified in the configuration.

Note that this creates the whole environment -- SPOPS classes are created and everything.

Return value is an OpenInteract::Request object ($R).

print_status_line

Display information from a 'status' record. Each status record is a hashref which can have the following keys:

ok
  True if status is ok, undef/0 otherwise

name
  Name of the package

version
  Version of the package

msg
  Message to accompany status (gets displayed whether status is 'ok'
  or not)

EXAMPLES

Some quick examples:

Installing OpenInteract for the first time, to the directory '/opt/OpenInteract':

>> tar -zxvf OpenInteract-1.01.tar.gz
>> cd OpenInteract-1.01
>> perl Makefile.PL
>> make
>> make test
>> make install
>> /usr/local/bin/oi_manage --base_dir=/opt/OpenInteract install

Create a new website:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --website_name=MyOIApp \
      --base_dir=/opt/OpenInteract create_website

Install a package to the OpenInteract installation directory with a file you have downloaded:

>> /usr/local/bin/oi_manage --base_dir=/opt_OpenInteract \
      --package_file=/tmp/downloadedpackage-1.41.tar.gz \
      install_package

Then apply the new package to your website:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --package=downloadedpackage apply_package

Create a new skeleton directory for a package you will develop:

>> cd ~/OpenInteract
>> /usr/local/bin/oi_manage --package=mydevelpackage \
      create_skeleton

After you have worked on your new package, you want to create a distribution file. First, run a check on the package:

>> /usr/local/bin/oi_manage \
      --package_dir=~/OpenInteract/mydevelpackage \
      check_package

If everything looks ok, then export it to a .tar.gz

>> cd ~/OpenInteract/mydevelpackage
>> /usr/local/bin/oi_manage export_package

Install it to the main OpenInteract installation:

>> /usr/local/bin/oi_manage --base_dir=/opt_OpenInteract \
      --package_file=~/OpenInteract/mydevelpackage/mydevelpackage-0.01.tar.gz \
      install_package

And then apply it to your website:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --package=mydevelpackage apply_package

List the website packages to make sure it is there:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp list_packages

You might want to bring its templates into the website database:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --package=mydevelpackage install_template

And then create the SQL structures:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --package=mydevelpackage install_sql

Moving to a new database -- change the SPOPS classes:

>> /usr/local/bin/oi_manage --website_dir=~/OIApp \
      --driver=SPOPS::DBI::Pg change_spops_driver

TO DO

Put this into a module

The functionality in oi_manage needs to be put into a module (likely 'OpenInteract::Manage') and oi_manage modified to simply call the methods of that module. This would make it fairly simple to create a web front-end to the functions as well. This would make Nate happy and would save people from reading this huge (but relatively well-organized) script.

Progress Indicator

When you are doing actions on multiple packages -- installing OpenInteract, creating a website, etc. -- you do not get feedback as the action is happening but rather everything at the end. (See Term::ProgressBar for a possible implementation...)

Friendly Dependency Finder

At install_package time, inspect the modules used by the package -- list_module.dat, ISA, etc. If we find one that is not installed, ask the user if he/she would like to install it and use CPAN to do so.

File Verification

Integrate MD5 checksum verification into the system for each file as well as for the package distribution on the whole.

SQL: Create an Equivalent Dumper

It would be nice to have a database-independent data dumping program that put the data into the format used by OpenInteract::SQLInstall. This actually should not be too hard, since the format is pretty simple. We might need to add information to the object (in spops.perl) so that it can tell which fields are 'class' fields or other fields that need to be transformed.

BUGS

None known.

COPYRIGHT

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

Christian Lemburg <lemburg@aixonix.de> suffered through early versions of this installer and package management system and offered insightful feedback.

Nate Haas <nateh@intes.net> and Marcus Baker <mbaker@intes.net> also worked with early versions of this installer and provided many helpful usability, documentation and functionality comments.

REVISION

Revision: $Revision: 1.68 $

To install OpenInteract, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenInteract

CPAN shell

perl -MCPAN -e shell
install OpenInteract

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

COMMON COMMANDS

COMMON OPTIONS

DESCRIPTION

SHORTCUTS

COMMANDS

INSTALL

UPGRADE

INITIAL PACKAGES

LIST PACKAGES

LIST ACTIONS

LIST OBJECTS

CREATE SKELETON

EXPORT PACKAGE

CHECK PACKAGE

INSTALL PACKAGE

CREATE WEBSITE

TEST DB

TEST LDAP

REFRESH DOC

REFRESH WIDGET

APPLY PACKAGE

REMOVE PACKAGE

UPGRADE PACKAGE

CHANGE SPOPS DRIVER

UPDATE OBJECTS

SQL COMMANDS

INSTALL SQL

DUMP SQL

TEMPLATE COMMANDS

INSTALL TEMPLATE

DUMP TEMPLATE

REMOVE TEMPLATE

OTHER METHODS

EXAMPLES

TO DO

BUGS

SEE ALSO

COPYRIGHT

AUTHORS

REVISION

Module Install Instructions