Apache2::Reload is a CPAN module that causes new code to be implemented as soon as it is created without the coder having to re-load modperl manually. (See the CPAN web page for a more technical description of what it does.) This is very helpful for anyone who wants to get into developing in WebGUI, from simple projects such as modifying a macro or workflow to complex endeavors such as developing your own assets. Without it, each time you wish to check your code, you would have to restart modperl, which can quickly become annoying. With it, your changes are immediately implemented on your website, allowing you to test your changes with less effort.

Previously, Apache2::Reload was part of the WRE development environment, but as of 0.8.3 it was no longer included. Setting up this module on your own development site is now a manual process.

The goal of this page is to walk novice users through the process of setting up Apache2::Reload on a development system. Users are not encouraged to use Apache2::Reload on production websites.

Apache2::Reload example

This example uses the 7.6.20 WebGUI VM, available from SourceForge with WRE version 0.9.2.

1. Download and install the Virtual Machine on your own computer. This requires the free VMware Player software. If you are new to Linux, a few hints to get you started:
   • typing "ifconfig" on the command line will tell you what IP address your VM has been assigned on your system. Look for "inet addr:" in the "eth0" block. It will likely start out with 192.168.XXX.XXX
   • Once you have the VM running, copy this IP address into a web browser on your desktop to view your newly-installed website.
   • The VMware Player window is small. If you'd like to see more code at once, you can use the PuTTy program to make an SSH connection and open another shell to your VM. Enter the IP address you got from ifconfig, the user "root', password "123qwe" and make sure the SSH option is selected.
     
     
2. For the sake of consistency with this example, accept all defaults on the initial site setup. (The company email address you give is not important.)
   
   
3. You will use CPAN to install the Apache2::Reload module, but it is not yet configured to use any particular mirrors for downloading. Experience shows that if you try to use CPAN with the VM out of the box, you will likely experience long waits while it tries to find and access a ftp site. So it is better to set up mirrors ahead of time:
   • Go to the list of CPAN mirror sites and select 2-3 that are geographically near-by. If http is an option, select that over ftp. (Some people have reported problems with ftp downloads for CPAN.)
   • fire up cpan by typing "cpan" on the command line, giving you the "cpan>" prompt.
   • At the prompt, type "o conf urllist" to confirm that no mirrors have been configured. (You should see none listed.)
   • The mirror list is basically an array, so you use the same "push", "pop", and "shift" methods to add and remove sites from the list. For example, to add the U of MN CPAN mirror, you'd type "o conf urllist push http://cpan.msi.umn.edu/". Repeat the "push" command for each mirror you wish to include. You can confirm your list of mirrors by typing the "o conf urllist" command again.
     
   • CPAN also suggests you commit your changes with "o conf commit" when done.
     
     
4. Now you should be able to install the Apache2::Reload module more quickly. At the "cpan>" prompt, simply type "install Apache2::Reload" and CPAN will install the module on your VM for you. You may see some warning messages in the output; they appear to not be significant for this exercise. Exit CPAN by typing "exit".
   
   
5. To tell modperl to use the new module, you have to add directives to your site's modperl configuration file. In this example, the file is /data/wre/etc/www.example.com.modperl. We will use the simplest configuration here, in which Perl modules for the entire site are reloaded as necessary, if they are changed. (You can configure Apache2::Reload to only reload certain modules or directories; this will improve performance if you know exactly which modules you will be editing. For more information, see the CPAN documentation.)
   • The two lines you want to add to the configuration file are "PerlModule Apache2::Reload" and "PerlInitHandler Apache2::Reload". Where you insert them into the configuration file is important! Putting them last, before the </VirtualHost> closing tag is fine.
   • Your www.example.com.modperl file should now look like:
     <VirtualHost *:8081>
             ServerName www.example.com
             ServerAlias example.com
             DocumentRoot /data/domains/www.example.com/public
         SetEnvIf SSLPROXY "1" \
             SSLPROXY
         SetHandler perl-script
         PerlInitHandler WebGUI
         PerlSetVar WebguiConfig www.example.com.conf
         PerlModule Apache2::Reload
         PerlInitHandler Apache2::Reload
     </VirtualHost>
     
     
6. Now you just need to reload modperl to apply the changes:
   • /data/wre/sbin/wreservice.pl --restart web
   • If all goes well, modperl and modproxy will restart with happy little "OK" output for both!
     

But how do you tell that Apache2::Reload is working? You'll have to go change some code and see if you see results without having to reload modperl. Here's a quick test:

1. cd to /data/WebGUI/lib/WebGUI/Macro/ and edit L_loginBox.pm
   
   
2. Look for where "username.label" is set. (If you're new to vi, the slash "/" is used to search, and you have to escape the period, so type "/ username\.label" to search for this phrase.
   
   
3. Duplicate the line of code and comment out the copy so you can revert back in the future. We wish to replace the default username field label with some other text. The "$i18n->get(50, 'WebGUI')" is used to find "Username" in whatever language the site is configured to use. (English is default.) Delete this code and replace it with some other text, placed in quotes.
   
   
4. Save your change
   
   
5. Now go back to your website and reload the page without restarting modperl. Before adding Apache2::Reload, nothing would have changed on the page because your edits wouldn't have been loaded into memory. But with Apache2::Reload, your replacement text should immediately appear below the first login box, in place of the "Username" text that was there before.
   
   
6. To revert back, comment out your edited line and un-comment the original, save your changes, reload the page, and you should see the return of "Username" without reloading modperl!