OpenInteract2::Manual::Tutorial is a Perl module that will teach learn you how to create and modify a package.
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 we're 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 won't 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 we'll assume you want to read to learn, so on we go.
Generating the skeleton
OpenInteract comes with tools to create a skeleton package -- we don't 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. Here's 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 here's what you'll see:
PROGRESS: Starting task
PROGRESS: Task complete
ACTION: Create package book
OK: Package book created ok in /path/to/my/book
And now let's see what it created:
$ find book/
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 you'll 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()'
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 book/MANIFEST.SKIP file will not be included.