• Home
• About

Displaying a Button in Joomla 1.5: A Module Tutorial

Have you ever wanted to display a button - say, to your LinkedIn profile - in one of the navigation columns in Joomla?  This article provides both a tutorial on the basics of module creation in Joomla 1.5, as well as a working “button” module that you can install right now on your Joomla website.

Note:
Click here if you just want to download the “Display Any Button”
installation zip (which includes the source developed below).

Overview

In its simplest form, a module in Joomla consists of four
primary parts:

1. A .php file that contains the
functionality you want to implement.  This should be named mod_myname,
where ‘myname’ is the name of your module.

2. An empty ‘index.html‘ file should
be placed at the top of your
module directory, as well as in any subdirectories.  This is
just a precaution intended to prevent browsers from
being able to access your module directory directly, thereby listing
the contents; the web server will serve this empty page instead.

3. An .xml configuration file, which
basically describes the module
as an installable item to Joomla.  In particular, all files
that are
part of this module are defined here, along with any parameter
definitions that the module needs (the actual value of the parameters
are set inside the Joomla module configuration admin panel.)

4. A .zip file that bundles all of
the above into one file.  This is what you upload to
Joomla and install.

Now, more complex modules are typically broken up into
multiple
pieces.  The idea is to separate the main entry module (mod_myname.php)
from the grunt work (like database queries) and rendering of the actual
output.  If you look at the source for one of the Joomla
standard modules - mod_newsflash, for example - you will see a “helper.php”
file (which handles the grunt work) and a “tmpl”
subdirectory (which contains the rendering code).

But, for this article, we won’t worry about the complex case -
it
isn’t necessary to break a module up into pieces; that’s just a
practice
that is intended to make complex modules more readable and
maintainable.  Our simple module will be fine if we put
everything in
one .php file - our main module file (mod_anybutton.php).

Coding

On to our example.  We will develop a simple module
that will allow
you to place a button/badge/image in one of the navigation areas in
Joomla (i.e., the left-hand column, where the menus typically are
found.)  We’ll call this module ‘Display Any Button‘
(sorry, can’t
think of a better name at the moment), and it will be known to Joomla
as ‘mod_anybutton‘.

First, we need to create a development directory for our
module on
our local machine.  Don’t do this within your Joomla
installation; you
do your development in one place, then package everything up and
install it in Joomla separately.  Since our module will be
known to
Joomla as ‘mod_anybutton‘, we need to create a
directory called
‘mod_anybutton‘.

Next, change to that directory and we will create the
necessary
files for this module.  Let’s start with the easiest thing
first, the
empty ‘index.html‘ file.  Just open
your editor and save an empty text
file as ‘index.html‘ within the
‘mod_anybutton’ directory.  Remember,
if you create a more complex module later on, every subdirectory should
also contain an empty ‘index.html‘ file.

Now it’s time for the actual code!  Open your text
editor and create
a file called ‘mod_anybutton.php‘.
The following is a skeleton that
shows the bare minimum needed (and doesn’t actually do anything):

<?php
// Don't allow direct access (outside of Joomla)
to this file
defined( '_JEXEC' ) or die( 'Restricted access' );
?>

The
above code just makes sure that it is being called from within Joomla -
otherwise, it will generate an error saying ‘Restricted
access’.  The
idea is that we don’t want web browsers invoking our module code
directly, where malicious users might try to inject fake variables,
etc. to gain access to private data.

Okay, with that out of the way, let’s talk a bit about what
this
module should do.  Basically, we want it to display a
button in
one of the navigation bars.  To do this, we need for the
module to
display a snippet of HTML code.  For example, the following
code will
display a button that links to my LinkedIn profile
(http://www.linkedin.com/in/mikemillsconsulting):

<a
href="http://www.linkedin.com/in/mikemillsconsulting"
><img
src="http://www.linkedin.com/img/webpromo/btn_myprofile_160x33.gif"
width="160" height="33" border="0" alt="View Mike Mills's profile on
LinkedIn"></a>

The <a href=...>
provides the hyperlink, and the <img>
element provides the source for
the button image.  In this case, the button image is retrieved
from
LinkedIn’s servers.  It could just as easily be located on
your own
server, though.

Okay, so we know that we need our module to display an
arbitrary
snippet of HTML, like the above.  We could hard-code it, but
that
wouldn’t be a very nice way of doing things, would it?
Instead, we can
use a configuration parameter in which to store the HTML snippet.

The way configuration parameters work is that you define
them inside your module’s XML configuration file (in this case, mod_anybutton.xml).
But you don’t put the actual values there - you
use the Joomla module configuration admin panel to set
the actual values.  Again, to be clear, the XML file just
defines the parameter names and their type.

So, for mod_anybutton, we will
create a parameter called
‘button_src‘.  (I’ll show you how to
define it in the XML configuration
file further on down.)

With this in mind, we can retrieve the value of the ‘button_src‘
parameter from within our mod_anybutton.php
file with the following
code:

$params->def('button_src', ''); // Set
default to be empty string.
$button_src = $params->get('button_src');

The
first line above just sets the default value to be an empty string. ‘$params‘
is a Joomla-provided class, and ‘$params->def()‘
is a
method of that class, and its purpose is to set the default value of
the specified parameter (’button_src‘ in this
case) to the specified
value (the empty string ” here).

The second line uses the ‘$params->get()‘
method to retrieve the
value of the ‘button_src‘ parameter.
The value is stored in the
variable ‘$button_src‘.

At this point, $button_src contains
our HTML snippet, and so all we need to do is to render that snippet:

if($button_src != '')
echo $button_src;

We first test to make sure $button_src
is not empty, and if it is not, then we simply echo
its contents, which will get sent to the client’s web browser.

That’s really all there is to it.  However, we need
to make an
enhancement before we can consider the code complete:  What
happens if
a browser accesses our site using SSL (i.e., ‘https‘)?
Most web
browsers will complain if there is a mixture of secure and non-secure
(i.e., http and https)
content on a given page.  In the HTML snippet
(LinkedIn) I demonstrated above, note that the <img>
element refers
to a remote image on LinkedIn’s web servers, and a non-secure (’http‘)
URL is used.

What we need to do is to define a second parameter - button_src_ssl
- which contains an HTML snippet in which the button image URL is
specified using ‘https‘.
Furthermore, our mod_anybutton.php needs to
be able to automatically figure out whether our client has accessed our
site using ‘http‘ or ‘https‘,
and then render the appropriate HTML
snippet (button_src or button_src_ssl),
as required.

Fortunately, Joomla provides a method for retrieving the base
URL of the current page:

$RURL = JURI::base();

The above code will retrieve the current base URL, and store
it in a variable named $RURL.

To determine whether the client used ‘http’ or ‘https’ to
access the
current page, we simply need to look at the first five characters of
the base URL (which is now stored in the variable $RURL):

if(substr($RURL, 0, 5) == 'https')
$button_src =
$params->get('button_src_ssl');
else
$button_src =
$params->get('button_src');

In
the above, if $RURL starts with ‘https‘,
then we know the client is
using SSL to access our site, and so we set the variable $button_src
to
contain the value of the ‘button_src_ssl‘
parameter.  Otherwise, we set
$button_src to contain the value of the ‘button_src‘
parameter.

Again, as shown earlier, we just then need to render the
snippet:

if($button_src != '')
echo $button_src;

So now, the complete source (minus header comments) looks like
this:

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

$params->def('button_src', ''); // Set
default to be empty string.
$params->def('button_src_ssl', ''); // Set default to be empty
string.

$RURL = JURI::base();  //Get base URL -
we check if SSL is being used below.

$button_src = '';

if(substr($RURL, 0, 5) == 'https')
$button_src =
$params->get('button_src_ssl');
else
$button_src =
$params->get('button_src');

if($button_src != '')
echo $button_src;
?>

And that completes the coding
part of our module.  Now we just need to create the module’s
XML
configuration file, and then package the whole thing up into a zip file.

XML Config File

Every installable module (and components, too, for that
matter) must include an XML configuration file. The primary purposes of
this file are:

1. Provide information about the author of the module.
2. Inform Joomla about the files that are included with this module -
particularly, the main entry point.
3. Inform Joomla about any parameters (including their name and type)
that the module needs (Joomla provides an administration interface for
configuring such parameters in the backend.)

Following is the contents of the XML configuration file for
our “Display Any Button” module:

<?xml version="1.0"
encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>Display Any
Button</name>
<author>Mike Mills Consulting,
Inc.</author>
<creationDate>November 14,
2007</creationDate>
<copyright>(C) 2007 Mike Mills
Consulting, Inc.  All rights
reserved.</copyright>

<license>http://www.gnu.org/licenses/gpl-2.0.html
GNU/GPL</license>

<authorEmail>mike@MikeMillsConsulting.com</authorEmail>

<authorUrl>www.MikeMillsConsulting.com</authorUrl>

<version>1.0.0</version>
<description>A simple Joomla 1.5
module that displays a button (or really, anything) using the html
source you specify.  Includes separate parameters for ssl and
non-ssl source.  Configuration is performed inside the Joomla
module configuration admin panel.  For multiple buttons, just
use the Joomla ‘Copy’ function (again, inside the Joomla module
configuration admin panel.)</description>
<files>
<filename
module=”mod_anybutton”>mod_anybutton.php</filename>

<filename>index.html</filename>
</files>
<params>
<param
name=”button_src” type=”textarea” cols=”80″ rows=”8″ label=”Button
Source Code” description=”Source code for the button you wish to use
(examples for LinkedIn can be found on their website.)” />
<param
name=”button_src_ssl” type=”textarea” cols=”80″ rows=”8″ label=”Button
Source Code - SSL version” description=”Source code - using SSL for
remote images - for the button you wish to use (examples for LinkedIn
can be found on their website.)  Change all instances of
‘http’ to ‘https’ in the button source.” />
</params>
</install>

Of particular importance is the <install
type="module" version="1.5.0"> element.
This element contains the following attributes:

• The type attribute
  let’s Joomla know what type of installation package this is - in this
  case, a module.
• The version
  attribute let’s Joomla know what version
  of Joomla this module was
  created for.  It is not the
  version of the module itself (that comes later.)

Beneath the <install>
element, we have the following (I’ll skip the most self-explanatory
elements, like <author>, <license>,
etc.):

• <name> is the
  descriptive name for your module.  We’re calling ours “Display
  Any Button”.
• <version> is the
  version number of your module.
• <description>
  provides a long description of the purpose of your module.
• <files> This is
  where we describe the files that are part of this package.  It
  contains nested <filename>
  elements, one for each file.
  • At least one <filename>
    element is required - one that describes the main entry point for our
    module.  In our case, we have:
    <filename
module="mod_anybutton">mod_anybutton.php</filename>
    The module
    attribute let’s Joomla know that this file describes the main entry
    point.
  • Other <filename> definitions are
    optional.  In our case, we define a <filename>
    for our empty “index.html” file.
• <params> is where we
  define the parameters used by our module.  It contains a
  nested group of <param>
  elements, one for each parameter.  In our case, we have
  defined two parameters:  “button_src”
  and “button_src_ssl“.  Both are
  defined as text areas with 80 columns and 8 rows (scrollable if more
  space is needed.) label
  is the name we will see next to the input text areas, and description
  is more descriptive text that will pop up when hovering over the label
  in the admin panel.

And that’s pretty much it for the configuration file.

Packaging

The final step is to package up your module development
directory into a zip file.  In our case, our module directory
is called “mod_anybutton“, so we zip up that
entire directory into a file called “mod_anybutton.zip“.

Installation & Configuration

Now that your module has been packaged up, you just need to
install and configure it.  Hopefully you know how to install a
module, but to be clear, you do that under the “Extensions->Install/Uninstall”
menu, inside the Joomla administration panel.

Lastly, you just need to configure the module for your
needs.  Click “Extensions->Module Manager“,
and then find the “Display Any Button” module,
and click on it.

Change the title to be meaningful for the type of button (or
whatever) you are creating.  In my case, I created a LinkedIn
profile button, so I set the title to be “LinkedIn Profile”.

Next, paste your non-SSL button source into the “Button
Source Code” text area, and then paste your SSL button
source into the “Button Source Code - SSL Version”
text area.

Now, set “Show
Title” to “No“,
and set “Enabled”
to “Yes“.

Save your changes.  You may want to adjust the order
in which your new module appears - I have my LinkedIn button just after
the menus, but before the login form.

And that’s it!

Note that if you need more than one button, you just use
Joomla’s Module Manager to copy the module, and give the copy a
different title (and of course the button source should be
different.)  You do NOT need to install a separate copy of the
module for this - just install once, and copy the module as many times
as needed.

Hopefully this article has been helpful.
You can download the ready-to-install version of “Display Any Button”
by clicking here.

Also, feel free to contact me if you have any questions.

Did you enjoy this post? Why not leave a comment below and continue the conversation, or subscribe to my feed and get articles like this delivered automatically to your feed reader.

Copyright Mike’s IT Consulting Blog | Theme by DailyBlogTips