plainblack.com
Username Password
search
Bookmark and Share

The WebGUI API

All software needs documentation, and WebGUI is no exception. WebGUI has excellent API documentation available. The point of this chapter isn't to describe how to do things with the WebGUI API, but rather to describe where to find its documentation, how to access that documentation, and how to install Perl modules via CPAN to facilitate custom development work. If you'd prefer browsing the API docs in a web browser, you can access the documentation online or generate the HTML documentation yourself.

 

The API Docs in HTML

There are two ways to access the WebGUI API docs via HTML, and thus via a web browser. The first is to use the site which Plain Black has set up for this. You can get to the documentation for the version of WebGUI you're using by pointing your browser at http://www.plainblack.com/downloads/builds/major.minor.patch-releaseType/api/ . major.minor.patch corresponds to your WebGUI version. For example, if you're running version 7.4.22-stable, you'd browse to http://www.plainblack.com/downloads/builds/7.4.22-stable/api/ . Conversely, if you're running 7.5.3-beta, you'd go to http://www.plainblack.com/downloads/builds/7.5.3-beta/api/ .

 

If you'd rather generate the documentation for local / offline viewing, you can do that too. The following Perl program will recurse through the /data/WebGUI directory and create the API docs at /data/docs.

 

#!/usr/bin/Perl



#-------------------------------------------------------------------

# WebGUI is Copyright 2001-2008 Plain Black Corporation.

#-------------------------------------------------------------------

# Please read the legal notices (docs/legal.txt) and the license

# (docs/license.txt) that came with this distribution before using

# this software.

#-------------------------------------------------------------------

# http://www.plainblack.com info@plainblack.com

#-------------------------------------------------------------------



# strict and warnings are obligatory

use strict;

use warnings;



# pull in modules that we use

use Getopt::Long;

use File::Path;

use Pod::Html;



# set defaults that the user can override

my $webGUIRoot = '/data/WebGUI';

my $pod2html = '/usr/bin/pod2html';

my $rootDirectory = '/data/docs';

my $filterContent;



# get those overrides

GetOptions(

'pod2html=s' => \$pod2html,

'webGUIRoot=s' => \$webGUIRoot,

'filterContent' => \$filterContent,

'rootDirectory' => \$rootDirectory

);



my $basedir = "$webGUIRoot/lib/WebGUI";



# start recursing

buildFromDir();



sub buildFromDir {



# get our current directory. default to nothing on the first call.

my $dir = shift || "";



# grab all the files in this directory

opendir my $currentDirectory, "$basedir/$dir";

my @files = readdir $currentDirectory;

closedir $currentDirectory;

@files = sort @files;



# need to make the directory in the docs tree if this is the first one

my $first = 1;

foreach my $file (@files) {

if ($file =~ /(.*?)\.pm$/) {

# first one; make that directory

if ($first) {

print "Making API docs directory: $rootDirectory/api/$dir\n";

mkpath(["$rootDirectory/api/$dir"]);

$first = 0;

}

# finally, generate the output

my $outfile = "$rootDirectory/api/$dir/$1.html";

print "Generating docs for $basedir/$dir/$file\n";

pod2html('--quiet', '--noindex', "--outfile=$outfile",

"$basedir/$dir/$file");

 

# filter it if told to

filterContent($outfile) if $filterContent;

}



# looks like we got a directory, recurse into it

elsif ($file ne "." && $file ne "..") {

buildFromDir($dir."/".$file);

}

}

}



sub filterContent {



# get the current file

my $file = shift;

print "Filtering content for $file\n";



# slurp in its contents

my $content = do {

open my $fh, '<', $file;

local $/;

<$fh>;

};



# prettify it

$content =~ s/NOTE:/<b>NOTE:<\/b>/ig;

$content =~ s/TIP:/<b>TIP:<\/b>/ig;

$content =~ s/<a .*?>//ig;

$content =~ s/<\/a>//ig;

$content =~ s/<hr>//ig;

$content =~ s/<head>(.*?)<\/head>//ixsg;

$content =~ s/INDEX BEGIN.*?INDEX END//isg;

$content =~ s/SYNOPSIS/Synopsis/g;

$content =~ s/DESCRIPTION/Description/g;

$content =~ s/METHODS/Methods/g;

$content =~ s/ <DT>

<STRONG>(.*?)<\/STRONG><BR>/

<dt><span style="font-family:

Arial;font-style: italic;">$1<\/span>/igx;

$content =~ s/ <pre>/<pre style="font-family:

courier,courier new,fixed;">/igx;

$content =~ s/<\!-- -->//gi;



# write the new contents

open my $fh, '>', $file;

print $fh $content;

close $fh;

}



Using Perldoc to Read the Documentation

If you're on a Unix-like system, you're probably familiar, and possibly even comfortable, with the manpages system, and the man(1) command. Perl comes with a similar tool for accessing its documentation called perldoc. Perldoc functions somewhat similar to manpages, although there are some Perl specific options. Run the perldoc command on itself for more information: perldoc perldoc. Windows© users can use perldoc as well, though they may find the HTML documentation more accessible.

 

Before accessing the perldoc documentation for WebGUI, you must tell the perldoc command where to find it. Users using the WRE have it easy: sourcing the setenvironment.sh script does all the work. However, if you're not using the WRE, it's not all that difficult: just set the Perl5LIB directory to the top level directory of your WebGUI Perl modules. For example, if you've installed WebGUI in /data/WebGUI, this will be /data/WebGUI/lib.

 

Installing Third-Party Modules via CPAN

The best part about being a Perl programmer is that you have CPAN©, the largest repository of reusable software ready for you to pick and choose what you need to accomplish your task. That said, how do you get all of those modules ready for WebGUI to use?

 

The first step is to find the module that you want. The easiest way to do this is to use one of the several web sites set up to search the enormous collection of modules on CPAN (some 13,000 at this writing, undoubtedly more by the time you read this). The two most common sites for browsing what's available on CPAN are http://search.cpan.org and http://kobesearch.cpan.org . Type in a module name, or even a general task description, and take a look at what's available.

 

Once you find the module that you need, you'll need to install it so that WebGUI knows where to find it. The most common, and simplest, way to do this is using the CPAN command line utility that ships with Perl. WRE users will need to use the CPAN utility that's part of the WRE; non-WRE users will need to ensure that the CPAN command they use installs modules in a place that will function properly.

Keywords: API CPAN module perl perldoc wre

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved