Princess and the ClearOS Module - Part 3 of 4

In Part 2 of "Princess and the ClearOS", we managed to drink our way into oblivion after getting Philesight installed and displaying the disk usage graph for our ClearOS server.

Before we move on, let's make sure we give credit where credit is due and extend the customary "I'll buy you a beer if I'm ever in..." traditions.

Zevv...thank you for your contribution to ClearOS and OSS in general!

Today's goal is relatively straightforward...we're going to create all the necessary files to have Philesight update the summary database once per day and display as a menu item in ClearOS's webconfig interface.

First, let's create the admin pages...There will be three files that need generating and are common to all modules:

1. Menu file
2. PHP admin page
3. PHP admin language template

Menu File

File Location:  /var/webconfig/htdocs/menu/diskusage.en_US

Let's make life easier on ourselves and pick a module in the current navigation that we think the Philesight module would best fit in with.  Under "System --> Resources" there's the "[System] Processes" modules that looks like a good fit.  We'll copy the English version of that menu file and just make some required edits.

cp /var/webconfig/htdocs/menu/processes.en_US /var/webconfig/htdocs/menu/diskusage.en_US

We then edit the file, changing the menu title and filename so it looks like this:

System|Resources|Disk Usage|diskusage.php|configuration|5300

Note, the filename uses the "en_US" locale...if you are developing on webconfig where you use a different locale (i.e. fr_FR, pt_BR etc.), you would change the extension of the filename to match or set your system to English while developing the module.

Simple enough!  Let's move on to the admin page.

PHP admin page

File Location: /var/webconfig/htdocs/admin/diskusage.php

This page is going to be very simple, but, of course, would vary depending on the complexity of information it contains.  Here too, we can copy another page to use as the template.

cp /var/webconfig/htdocs/admin/hardware-report.php /var/webconfig/htdocs/admin/diskusage.php

Editing the new diskusage.php, we'll get rid of any non-relevant code and stick a single Iframe to pull in the CGI page that Philesight generates.

<?php

///////////////////////////////////////////////////////////////////////////////
//
// Copyright 2010 ClearFoundation.
//
///////////////////////////////////////////////////////////////////////////////
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
//
///////////////////////////////////////////////////////////////////////////////

require_once("../../gui/Webconfig.inc.php");
require_once("../../api/Locale.class.php");
require_once(GlobalGetLanguageTemplate(__FILE__));


///////////////////////////////////////////////////////////////////////////////
//
// Main
//
///////////////////////////////////////////////////////////////////////////////

WebAuthenticate();
WebHeader(WEB_LANG_PAGE_TITLE);
WebDialogIntro(WEB_LANG_PAGE_TITLE, "/images/icon-status.png", WEB_LANG_PAGE_INTRO);
DisplayUsage();
WebFooter();


///////////////////////////////////////////////////////////////////////////////
// F U N C T I O N S
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//
// DisplayUsage
//
function DisplayUsage()
{
        echo "<iframe style='border:none;' src ='https://" . getenv("SERVER_ADDR") . ":81/cgi/philesight.cgi' width='100%' height='800'>";
        echo "<p>" . WEB_LANG_IFRAME_NOT_SUPPORTED . "</p>";
        echo "</iframe>";
}

?>

A brief summary of the above, although it should be quite self-evident.  First, we have our copyright and licensing comments.

Next, we pull some required classes and the language template.

We then call a couple of functions to force authentication to access the page and to create webconfig's header.  The header abstracts away from the developer things like the menu, style etc.  We'll then add the standard bubble that describes what the module does and call a very simple function that creates the Iframe.

Calling a standard footer finishes things off.

PHP admin language template

File Location: /var/webconfig/htdocs/admin/lang/diskusage.en_US

Finally, we're going to create our webconfig language file (same note applies regarding locale settings for webconfig as discussed in the menu section above) for the few tags we've used.

<?php
// Generated by export.php.
define("WEB_LANG_PAGE_INTRO", "This page displays a snap shot of disk usage as of midnight on your system.  Click on the areas of the graph to zoom into folders for a more detailed analysis.  Click on 'cd..' to return to the previous folder (zoom out).");
define("WEB_LANG_PAGE_TITLE", "Disk Usage");
define("WEB_LANG_IFRAME_NOT_SUPPORTED", "Sorry...your browser does not support Iframes.");
// vi: syntax=php ts=4
?>

ClearOS currently uses a database submission utility which we'll use in part 4 of this series when we're packaging things up.  For now, having the one language file (and menu file), as long as it matches our webconfig locale setting should suffice.

If you've been playing along at home, at this point, you should be able to point your browser at the new page in webconfig and see the summary graph, as well as navigate through folders.

A couple of things have to be done to clean it up.

1.  Put an icon in place for the information bubble.  We'll just copy one from another page.

cd /var/webconfig/htdocs/images/icons/32x32
cp icon-hardware-report.png icon-diskusage.png

2.  Make some changes to the configuration settings in /var/webconfig/htdocs/cgi/philesight.cgi:

$path_db = "/usr/webconfig/tmp/ps.db"
$img_size = 650
$show_list = false

The first puts the database file in a more appropriate location than the /tmp directory.  The next scales down down the image to fit the real-estate limits within the webconfig template.  Finally, we hide the file/folder list for simplicity.

3.  Move the database file (ps.db) that we created in Part 2 when we originally installed and ran Philesight that creates the database:

mv /tmp/ps.db /usr/webconfig/tmp/

 4.  Remove the background color of the colorwheel so it becomes transparent.  Line 186 of /var/webconfig/htdocs/cgi/philesight.cgi becomes:

puts '          body {color:black;text-align:center;}'

5.  Copy the Philesight executable over to our script directory and create a symbolic link to the required ruby file.

cp /tmp/philesight-20091214/philesight /var/webconfig/scripts/
cd /var/webconfig/scripts
ln -s /var/webconfig/htdocs/cgi/philesight.rb .

6.Create a cron job that runs at midnight to update the disk usage database automatically.

echo '0 0 * * * root /var/webconfig/scripts/philesight >/dev/null 2>&1' > /etc/cron.d/app-diskusage
/etc/rc.d/init.d/crond reload

That ought to do it.  Next week, in Part 4 (the final installment), we'll package things up and add the new RPM's to ClearFoundation's repositories so you can simply install the module through webconfig or by running:

yum install app-diskusage

Anything is possible...I'm on a horse...

Ben

{jomcomment}