OpenInteract2::Manual::Tutorial 1.99_06

OpenInteract2::Manual::Tutorial is a Perl module that will teach learn you how to create and modify a package.

SYNOPSIS

This tutorial will show you the different methods for creating a package and how to maintain them.

CREATING THE PACKAGE

A word on the example

For our example were going to create a book package. This will keep track of all our books and allow us to search our library, add new books, update existing ones and remove old ones. It wont be the backbone for a massive e-commerce website to make you lots of money. It does not attempt to best model the relationships for all the data about a book.

Looking for shortcuts?

If you want to get something running in the fastest manner possible we can generate a simple CRUDS application for you. (CRUDS: CReate Update Delete Search) Just run something like the following:

$ oi2_manage easy_app --package=book --table=book
--dsn=DBI:Pg:dbname=mylibrary --username=foo --password=bar

This will create a simple application built off a table book with templates and objects for searching, creating, updating and removing objects. (More at OpenInteract2::Manage::Package::CreatePackageFromTable.)
Since this is a tutorial well assume you want to read to learn, so on we go.

Generating the skeleton

OpenInteract comes with tools to create a skeleton package -- we dont want to do all this from scratch! The skeleton package has the directory structure, metadata and a number of files to get you going on your new package. Heres how to create one -- be sure to first go to the directory under which the package will be created:

$ oi2_manage create_package --package=book

And heres what youll see:

PROGRESS: Starting task
PROGRESS: Task complete
ACTION: Create package book
OK: Package book created ok in /path/to/my/book

And now lets see what it created:

$ find book/
book/
book/conf
book/conf/spops.ini
book/conf/action.ini
book/data
book/doc
book/doc/book.pod
book/struct
book/template
book/template/sample.tmpl
book/script
book/html
book/html/images
book/OpenInteract2
book/OpenInteract2/Action
book/OpenInteract2/Action/Book.pm
book/OpenInteract2/SQLInstall
book/OpenInteract2/SQLInstall/Book.pm
book/package.ini
book/MANIFEST.SKIP
book/Changes
book/MANIFEST

These files and directories are explained in OpenInteract2::Manual::Packages.

You will normally need to edit/add the following:

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

Short sidebar: Creating a MANIFEST

Notice that we create a MANIFEST file for you when the package is created. As you add more files to your package youll need to add them to your book/MANIFEST. Fortunately, it can be created automatically:

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

Thats 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 book/MANIFEST.SKIP file will not be included.