installClass.pl - How to create install scripts for your WebGUI plugins

The 7.6 dev cycle brought a lot of improvements, both to the content management and app framework side of WebGUI, some of which may have gone unnoticed by the people that would enjoy them the most.

Prior to 7.6, WebGUI had no single method of installing plugins (besides the Wobject skeleton which had an "install" sub that required the programmer to fill in a bunch of information). Now, with the new utility script installClass.pl, there is a common way to build installers for your plugins. In addition, an Installable AssetAspect makes building asset installers automatic!

Using installClass.pl

If you're building a plugin, you're going to have to install it. Instead of making a separate install script, increasing the number of files in your distribution, you can use the installClass.pl interface.

To use this interface with your own class, there are three methods you must have: install, isInstalled, and uninstall.

sub install {
    my ( $class, $session ) = @_;
    # Install my class on the site
    # Add configuration file entries
    # Add database tables
    # Import packages
    # Add settings
}

sub isInstalled {
    my ( $class, $session ) = @_;
    # Return true if my class is already installed
    return 0;
}

sub uninstall {
    my ( $class, $session ) = @_;
    # Remove my class from the site
}

Once you have these three methods, using "perl installClass.pl MyClass --configFile=mysite.conf" will install MyClass in the mysite.conf site. Easy as sneezing!

Using the Installable AssetAspect

If you're making an asset, using installClass.pl is even easier! Once you've written your definition, you can just import the Installable aspect like any other.

use base 'WebGUI::AssetAspect::Installable', 'WebGUI::Asset';

Now you have the subroutines you need. What's more, the install routine just works! It will pull your definition and install your asset, no code or SQL required!

If you need to install other things along with your asset, you can override the install sub like so:

sub install {
    my ( $class, $session ) = @_;
   
    # Install the base asset table and add the asset to the config file
    $class->next::method( $session );
   
    # Install my other necessary stuff!
    # ...
}

I know what you're asking yourself. How did you ever get along without this?

Using installClass.pl for upgrades

There's one other function that installClass.pl can provide: upgrading existing installs. When installClass.pl sees that a class is already installed, it will call the "upgrade" sub. With a bit of external version detection we can perform only those upgrades we need to perform:

sub upgrade {
    my ( $class, $session ) = @_;
    my $previousVersion    = $session->setting->get("MyClass_version");
    if ( $previousVersion < qv(1.2) ) {
        # Upgrade to version 1.2
    }
    if ( $previousVersion < qv(1.5) ) {
        # Upgrade to version 1.5
    }
    if ( $previousVersion < qv(2.0) ) {
        # Upgrade to version 2.0
    }
    $session->setting->set( "MyClass_version", $VERSION );
}

With these tools at your disposal, you can create easy-to-install plugins for WebGUI. Look for even more features like this one in the future!

For more information, see "installClass.pl --man", "perldoc WebGUI::AssetAspect::Installable", or ask on the dev forums.