Sankuru

By searching the Joomla extension repository, I came across the RsMonials component. It is a native Joomla 1.5 component which allows site visitors to submit testimonials. Depending on how you set the configuration setting, the testimonial will either be published automatically or else after approval by the admin.

The very first thing I looked at, were the user reviews evaluating RsMonial. The user reviews are quite positive, without actually being really raving. The component is deemed to be well usable -- a nice effort -- but with scope for improvements.

No other extension in the "Testimonials & Suggestions" extension category was flagged as 'Popular' or 'Editor's pick' or any other telling indicator that would make the extension the obvious choice. So, I proceeded by downloading and installing RsMonials 1.5.1 in this very site.

I like the RsMonials component.  It is a commendable effort. For the component to truly fit my purposes, however, I identified the following changes to make to its source code:

1. The component should not switch on Php error reporting

Even though the component itself does not produce any warnings, other components may. For example, Joomfish in the version I installed, produces Php warnings, that end up littering the pages produced by RsMonials. Searching the joomla root for the offending instruction quickly revealed where to fix it:

$ grep -r display_errors * 

administrator/components/com_rsmonials/admin.rsmonials.php:14:ini_set('display_errors', 1);
components/com_rsmonials/rsmonials.php:14:ini_set('display_errors', 1);

The problem was quickly solved by commenting out the offending lines.

2. The testimonial record may contain a few too many fields

The testimonial record has the following fields:

1. First Name [REQUIRED]
2. Last Name [REQUIRED]   
3. Email Address [REQUIRED]
4. About You   
5. Location   
6. Website   
7. Security Code  [REQUIRED] 
8. Testimonial [REQUIRED]

The more fields the user has to fill out, the less likely he will end up submitting a testomonial. Therefore, reducing the number of fields to fill out, is a fruitful exercise.

First, I do not want to force the user to enter "First Name" and "Last Name" separately. One field "Name" should do. The user may fill out his full name or just his first name, if he likes. The object of the exercise is not to uniquely identify users, but to collect testimonials.

Further, I do not want to make filling out the email address mandatory. The user may suspect us from having plans to spam them.

The "About you" field should probably be "Company".

Note: I also changed the labels from their verbose version, such as "Your location",  to simply "Location".

By the way, RsMonials fortunately has configuration options in the back end to enable/disable the "About You", "Location", and "Website" fields. These fields should indeed not be mandatory.

Note: The RsMonial component runs natively in Joomla 1.5, but the source code looks more like the one of a typical 1.0 Joomla component.

2.1. Modifying the submission form (view)

• line 170:  comment out the html: <!--    <tr><td class="RSM_form_first_col"><span id="fname_d" class="RSM_form_text">Your First Name:</span><span class="RSM_form_star_color">*</span></td><td style="width:75%;"><input name="fname" id="fname" type="text" maxlength="50" class="RSM_form_input" value="<?php echo $postA['fname']; ?>" /></td></tr> -->
• line 171: Change "Your Last Name" to "Name"
• line 172: Take away to "*" (required) symbol after the "Email address:" label.
• line 173: Change "About you" to "Company"
• line 193: Change "Send us your comments below:" to "Testimonial"
• line 194: Change rows="" cols="" to rows="20" cols="60" (this will fix the size of the text area)

2.2. Modifying the submission form (process)

We can fix the processing of the form submission in function submit(), starting at line 324:

line 329: Comment out:

/*

    if(trim($_POST['fname']) == '') {
        $isfalse = true;
        $RSM_error[] = 'Please enter first name.';
    }
*/
 

line 339: Replace:

    if (!eregi("^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,3})$", trim($_POST['email']))) {
        $isfalse = true;
        $RSM_error[] = 'Please enter proper email address.';
    }

With:

if(trim($_POST['email'])!="")
{
    if (!eregi("^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,3})$", trim($_POST['email']))) {
        $isfalse = true;
        $RSM_error[] = 'Please enter proper email address.';
    }
}

2.3. Modifying the javascript validation

RsMonials validates the form in javascript before submitting it to the server in the function testimonialSubmit() around line 61.

Take out the part that validates the required First Name field:

/*
    if(trim(f.fname.value) == '') {
        document.getElementById('fname_d').style.color='#ff0000';
        document.getElementById('fname').style.borderColor='#ff0000';
        err++;
    }
    else {
        document.getElementById('fname_d').style.color='';
        document.getElementById('fname').style.borderColor='';
    }
*/

Make the email address optional, by fixing its validation:

/*
    if(trim(f.email.value) == '') {
        document.getElementById('email_d').style.color='#ff0000';
        document.getElementById('email').style.borderColor='#ff0000';
        err++;
    }
    else
*/

if(trim(f.email.value) != '') {
    if((/^[a-zA-Z0-9._-]+@([a-zA-Z0-9.-]+\.)+[a-zA-Z.]{2,5}$/).exec(f.email.value)==null) {
        document.getElementById('email_d').style.color='#ff0000';
        document.getElementById('email').style.borderColor='#ff0000';
        err++;
    }
    else {
        document.getElementById('email_d').style.color='';
        document.getElementById('email').style.borderColor='';
    }
}

else
 {
        document.getElementById('email_d').style.color='';
        document.getElementById('email').style.borderColor='';
    } 

3. Internationalizing (i18n) and localizing (L10n) RsMonial 1.5.1

 All natural language phrases in the RsMonials component are hardcoded in the sources themselves, instead of loaded from language files. The solution consists in:

• creating the English language file
• using the JText::_ method to replace the natural language phrases hardcoded in the source files, and load them from the language file
• creating the language files for the other languages supported (Dutch and French)

 This process has to be done for both front and back end.

For the front end, we need to create the file language/en-GB/en-GB.com_rsmonials.ini. For the back end, we need to create the file administrator/language/en-GB/en-GB.com_rsmonials.ini.

We will remove all English-language natural language phrases from the file components/com_rsmonials/rsmonials.php to this file.

We test if the file is being recognized and loaded by the JText::_ method, by adding a test phrase to the empty file:

TESTME=hello this is just a test

Note that all phrase keys must be in capitals. If they are not, the translation method JText::_ will not find them.

Add the following test instruction, for example, in line 143, just before the "Submit A Testimonial" heading:

<?php echo JText::_('TESTME'); ?>

This should print:

hello this is just a test

The core file in  the Joomla translation system is libraries/joomla/language/language.php. There you can look at how things work under the hood. If the translation fails to show up, you can dump the paths of the language files loaded with the statement:

print_r(JFactory::getLanguage()->getPaths());

You can dump all translation strings present in memory with the statement:

print_r(JFactory::getLanguage()->_strings);

The next task is to painstakingly replace each occurrence of a natural language phrase with a key/value pair in the language files.

The next step is to translate into a particular language. In order to create a translation file for the French language, for example, you can duplicate the two en-GB.com_rsmonials files to fr-FR.com_rsmonials, keep the phrase keys, but replace the values with the French translations.