Creating a template override for the Newsletter module

A Joomla! extension's default layout may not be suitable for everyone's needs. Depending on the degree of flexibility the extension offers, you might need to perform some source code modifications in order to get a different layout or even extended functionality.

The greatest concern when implementing such modifications is brought by the fact that they will be lost when the extension gets updated. Joomla! overcomes this setback through its template overrides feature, which allows loading a modified copy of the original view file that requires adjustments. This way, when the extension gets updated, the modifications will be kept although the original view file gets overwritten.

General implementation

Since the layout modifications that you want to implement need to fit your template's look and feel, naturally, the modified view files have to be correlated with the template. Each Joomla! template includes a folder specially destined for this purpose, called html, found under the following path:

/templates/template_name/html

This is where the modified layout files need to be placed. However, simply copying them in this folder will not work, as the template needs to "know" what view they are destined for. This is why you must re-create a part of their originating folder structure, as in the following example:

Let's assume that you wish to change how the Joomla! Content's Single Article menu item is displayed on Joomla! 2.5's Beez_20 template. The file that controls this view is found under the following path:

/components/com_content/views/article/tmpl/default.php

Its copy (that will be later modified) will need to be placed under the following folder structure:

/templates/beez_20/html/com_content/article/default.php

Note that the highlighted folders from the original structure must not be replicated in the template's html folder.

Overriding the Newsletter module's layout

Having this information at hand, all you need now is to know the location of the module's layout file:

/modules/mod_rsmail/tmpl/default.php

To safely modify it (for the Beez_20 template), first copy it in the following location:

/templates/beez_20/html/mod_rsmail/default.php

Example

The Newsletter module does not include a feature that would enable you to only display the built-in CAPTCHA / reCAPTCHA to guests, it will be displayed regardless of the fact that the user is logged-in or not. This can be implemented with a few source code modifications:

Edit the copied file, look for the following code (around lines 40-55):

      <?php if ($captcha_enable != 0) { ?>
        <div id="rsmail_captcha">
          <label for="submit_captcha<?php echo $module->id;?>"><?php echo JText::_('RSM_CAPTCHA_LABEL'); ?></label>
          <?php if ($captcha_enable == 1) { ?>
            <img src="<?php echo JRoute::_('index.php?option=com_rsmail&task=captcha&id='.$module->id.'&sid='.mt_rand()); ?>" id="submit_captcha_image<?php echo $module->id;?>" alt="Antispam" />
            <a href="javascript: void(0)" onclick="return rsm_refresh_captcha(<?php echo $module->id;?>);">
              <img src="<?php echo JURI::root(); ?>components/com_rsmail/images/refresh.gif" alt="" border="0" align="top" />
            </a>
            <input type="text" name="captcha<?php echo $module->id;?>" id="submit_captcha<?php echo $module->id;?>" size="35" value="" class="inputbox required" />
          <?php } elseif ($captcha_enable == 2) { ?>
            <?php echo RSMReCAPTCHA::getHTML(null,false,$recaptcha_public_key,$recaptcha_theme); ?>
          <?php } ?>
        </div> <!-- rsmail_captcha -->
      <?php } ?>

and replace it with this one:

      <?php if ($captcha_enable != 0) { $user=JFactory::getUser(); if ($user->id <= 0) { ?>
        <div id="rsmail_captcha">
          <label for="submit_captcha<?php echo $module->id;?>"><?php echo JText::_('RSM_CAPTCHA_LABEL'); ?></label>
          <?php if ($captcha_enable == 1) { ?>
            <img src="<?php echo JRoute::_('index.php?option=com_rsmail&task=captcha&id='.$module->id.'&sid='.mt_rand()); ?>" id="submit_captcha_image<?php echo $module->id;?>" alt="Antispam" />
            <a href="javascript: void(0)" onclick="return rsm_refresh_captcha(<?php echo $module->id;?>);">
            <img src="<?php echo JURI::root(); ?>components/com_rsmail/images/refresh.gif" alt="" border="0" align="top" />
            </a>
            <input type="text" name="captcha<?php echo $module->id;?>" id="submit_captcha<?php echo $module->id;?>" size="35" value="" class="inputbox required" />
          <?php } elseif ($captcha_enable == 2) { ?>
            <?php echo RSMReCAPTCHA::getHTML(null,false,$recaptcha_public_key,$recaptcha_theme); ?>
          <?php } ?>
        </div> <!-- rsmail_captcha -->
      <?php }} ?>

After replacing the code, before displaying the anti-spam functionality, the module will first check if the user is logged-in or a guest, and will only display the anti-spam to guests.