NAME

RoboButton - generic Perl module for use within RoboButton


SYNOPSIS

 use RoboButton;


DESCRIPTION

Module for creating buttons --gif images with text for user to click on-- using a modperl handler. The module also provides method for preparing text for use in the button url.


ORIGINAL CODE

This module is based on the original buttonizer code by Robbert Wethmar (robbert@xxlink.nl) The name RoboButton is derived as follows: 'Robbert's button script', became Robbert-button, became RobbieButton, became RoboButton...


INSTALLATION PROCEDURE

NOTE

 You'll need root access to do this. If you don't know what that means, 
 you should not be doing this ;-)
Module install

 First of all, the module needs to be installed on the server which is supposed to serve the buttons.

  cd /export/home/local/www/liz/
  installpm RoboButton.pm
Inclusion in modperl configuration

 The module needs to be included in the modperl configuration of the server.
 To do this, add the following:

  # Use the RoboButton module
 
  use RoboButton ();
Creating directories / symlinks

 'Go' to the base directory (not root dir) of the client's virtual server, eg.:

    cd /export/home/local/www/theclient

 Copy or create a symlink to the robobutton image gifs directory:

    ln -s /export/home/local/www/intranet/robobuttons . 

 Now, create the cache directory for the buttons in the root directory:

    cd root
    mkdir buttons
    chmod 766 buttons
    chown www:WWW buttons
Altering the virtual server configuration

 To enable the robobutton handler on the virtual server, a number of directives
 (mod_proxy/mod_rewrite stuff) need to be added. 
 Since the required directives are already present in the 'RoboButtons' file 
 (in the ..../configdb -dir), one need only do the following:

    cd /export/home/local/apache/conf/configdb
    open file www.<theclient>.nl

    Add: 
      RewriteEngine   On
      <INCLUDE RoboButtons>   

    Save the configuration file and reconfigure and restart the server:

    ./configure -r

   now, the robobuttons should be enabled.
Check if it works

 In a browser location field, type:

    <servername>/buttons/h/maintain/_Emy_20first_20button!.gif

 You should now see your first button... 

 Check the cache directory to see if the buttons are cached, if they 
 are not, you'd be wasting processor power on the server, so please 
 check this.

    cd /export/home/local/www/<theclient>/root/buttons
    ls

 If now you see an 'h'-directory, you're in business because that is where
 the 'h'orizontal buttons are cached. If not, then likely there is a problem
 with the rights settings on that directory.


PROBLEMS?

 If you have a problem, if no one else can help, and if you can find them, 
 maybe you can hire the A-Team!

 Alternatively, you may ask Sjoerd (sjoerd@xxlink.nl) for help ;-) 


MODPERL HANDLERS


handler

This is the handler that processes image requests to produce the binary gif-data that is send to the browser and stored on the filesystem for subsequent requests.

NOTE: This handler should/need not be called directly.


UTILITY METHODS


Text2Filename

Converts a string to a valid filename for use as in an IMG-tag.

Input Parameters

 1 Text to convert to filename
 2 Extension to add after the text 
   OPTIONAL
Output Parameters

 1 valid url encoded string 
Examples

 In Liz::Perl:

 <PERL>
  $text = 'Bla bla button <^&gt; % $ # @!' unless $text;
  $button = RoboButton::Text2Filename( $text,'gif' );
 </PERL>            

 As a form button:

 <FORM><BUTTON my_action /buttons/h/maintain/$button HEIGHT=17></FORM><BR>

 or simply:

 <IMG SRC=/buttons/h/maintain/$button HEIGHT=17 BORDER=0>


SRC

Converts a string to the almost complete HTML for use in an IMG or INPUT-tags.

Input Parameters

 1 Orientation ('h' or 'v' for horizontal and vertical respectively)
   (default: 'h')
 2 Type (e.g. which button image to use)
   (default: 'std')

 3 Mode, currently there are three possible modes:
   1. no mode
   2. _T for transparency
   3. _E for displaying the end caps 

 3 Text to convert to filename
 4 Extension to add after the text (default: 'gif' )
 5 Alt text (default = text)
 6 Height to use
 7 Border (default=0)
Output Parameters

 1 HTML to display button with
Example

 <PERL>
  $src = RoboButton::SRC( 'h','',_T,$text,'','',17 );
 </PERL>
  
 <IMG $src>


BUTTON

Create the complete HTML for a INPUT TYPE=IMAGE form-element.

Input Parameters

 1 Name of the element
OTHER INPUT PARAMETERS

 This method makes use of method SRC to create most of the HTML,
 please refer to that method for the rest of the  parameters.
 (parameter 2 for BUTTON is parameter 1 for SRC, etc.).
Output Parameters

 1 HTML to display button with


AUTHORS

THIS MODULE

 Sjoerd Lawende ( sjoerd@xxlink.nl )
ORIGINAL BUTTONIZER CODE

 Robbert Wethmar ( robbert@xxlink.nl )


COPYRIGHT

(C) 2000 Integra Nederland BV


HISTORY

Version 0.12, August 28, 2000

Finished documentation, including installation protocol.

Version 0.11, June 25, 2000

Added methods Text2Filename, SRC and BUTTON.

Version 0.1, June 24, 2000

First version of this module.