IX - a web framework for Perl, pronounced 'nine'
use IX::IX;
Using IX, the main portion of your custom application is reduced to:
our $cgi;
our $arm;
IX::IX::run();
The rest of your application will consist of subroutines.
IX is a web framework; it is an attempt to abstract away the more repetitive aspects of developing a web application.
It is in production use at the University of New Hampshire, but is not considered ready for wider distribution at this time.
IX::ARM and IX::Guest require an ARM data source (XML-RPC web service). IX will not currently run without an ARM data source.
IX is written to run on the Apache webserver.
IX is written to use a MySQL database.
IX depends on many fine modules from CPAN, as well as SVN to remain current with the latest development. This module shows the beginning of that dependency tree within the IX:: namespace. Perl will tell you if you are missing modules needed by IX.
IX is developed on a Linux operating system, and has not been tested elsewhere.
IX is not intentionally stodgy about choice of technologies, it just hasn't been ported for use on all systems yet.
Check out the project to a temporary directory from SVN:
svn co svn+ssh://abby.unh.edu/marcus/trunk/IX ~/IX_temp
Change into the installation directory:
cd ~/IX_temp/install
Run the installer and respond to the prompts:
./install.pl
build()When developing a custom application on IX, if you are using SVN to manage it, the developer may run this function at the command line in lieu of svn ci:
./custom_app -IX::IX::build
This command will dump the full database schema of the current environment as well as the navigation table data, both of which get committed to the repository for later use by update(). Use only to commit a full, stable working directory.
run()This function handles all non-AJAX web requests, and should be the only called in the main of your custom application executable. It is called like this:
IX::IX::run();
runAjax()This function handles all AJAX web requests, and should only be called in the main of your custom application AJAX executable. It is called like this:
IX::IX::runAjax()
This differs from run() in looking at an AJAX-specific dispatch table and taking different evasive action for illegal actions, invalid sessions, and the like... since you can't reject an AJAX call by sending them directly to a login page.
update()If using SVN to deploy new code from your repository to test or production environments, this command should be used for a global updtae of the custom app's working directory at the command line:
./custom_app -IX::IX::update
This will check for missing framework-level or local Config variables, adding them when necessary, refresh the navigation table with any new data, and show you the diff output between the committed database schema and the one in your environment that needs to be updated.
Here is a style guide and a set of best (or, at least, established) practices for coding custom applications atop the IX framework.
It is recommended to run your web application with taint turned ON, as in:
#!/usr/bin/perl -T
If you do so, also clear out environment variables which may contain values exposing attack pathways and whatnot to bad guys:
# make taint real happy
delete @ENV{qw(IFS CDPATH ENV BASH_ENV PATH)};
See http://perldoc.perl.org/perlsec.html#Taint-mode for more gories on taint.
run() and runAjax() call their own dispatch tables to allow direct calls from the web (in $cgi->param('action')) while preventing the call of arbitrary subroutines. See http://mindmined.com/IX/Dispatch.pm.html.
IX handles session management with cookies, which, for applications needing to maintain state between http requests, must be enabled in the browser. If a user is authenticated, IX will instruct that user to enable cookies in the browser if they are disabled.
The system names, usernames, passwords or other 'secret' items you use to allow your custom application to access external systems are called 'secrets' in IX. Store these in a file called .secrets in Local/ and confirm that your version control is ignoring this file so it is not committed. These files may very well differ across your development, test and production environments, if there are different corresponding external systems to connect to.
The .secrets file can be modified to support additional secrets for your application.
When committing custom application code with SVN, it is preferable to do so using the following build(). This is for commits that are safe to do globally on the working directory. If you are only committing a specific file or files because other files are in an unstable state, do not use build().
If using SVN to deploy an entire working directory's changes to environments, see update(). To update on specific file(s), such as in sleected bug fixing, stick to svn up [filename].
In the future we plan to support a distributed version control system (DVCS) such as git or mercurial. The build() and update() commands will support at least one of these in addition to Subversion (SVN).
In general, try to follow the advise in Perl Best Practices. There are surely violations of PBP in the IX framework and the custom apps built on it. In the future we would like to use Perl::Critic as part of the build() routine.
IX and custom apps thus far have been using the K&R bracketing style, see PBP on that as well.
Calling subroutines across packages (modules/files) must be done using their fully qualified names, as in Local::Template::process(). Although all subroutines are available across packages likes this, only the ones we intend to be called in this manner should start with a letter, to keep us organized.
Subroutines prefixed by an underscore (_) are intended to be internal to that package.
To keep organized we try to remember also to split these subroutines into different sections in each file, and alphabetize them within their sections:
########################
# available subroutines
########################
sub processA {
}
sub processB {
} # etc.
########################
# 'private' subroutines
########################
sub _preProcessA {
}
sub _preProcessB {
} # etc.
The IX web framework is written and maintained by Marcus Del Greco (marcus@mindmined.com) .
FatalsToEmail.pm is written by Randal L. Schwartz; adapted with modifications by Bill.Costa@unh.edu and yet more minor mods by marcus@mindmined.com for use with IX.
Prospective contributors to the IX framework are welcome.