Frequently Asked Questions (FAQ)

…and the frequently answered descriptions to it:

Header Image allows to be used more than once. This is called 'multiple instancing'.

When the requirement is to have 2 (or more) Header Image instances in the index-page where:

  • (1) - is showing a logo in relation to the current menu item selected and
  • (2) - is showing some images (random or whatever) as slideshow

then I will explain here how I would do it to achieve above described:

  • a) First start with the first instance of the Header Image in the “Site Module” configuration of the Administrator and configure it such that it shows the relevant images at the desired module position.
  • b) Test it to see if that works and modify configuration until satisfactory.
  • c) Copy the first Header Image instance in the “Site Module” page, this creates a second instance of it with the same settings as before.
  • d) as in (a) now configure the second instance to your liking. Note: Change the modules name to whatever different from the first instance.
  • e) Test to see if the second instance now works as intended and modify its configuration until satisfactory.

Every instance of the module is independent from each other, meaning that this enables use of independent settings and files.

For how to bind a single module to a specific menu location, see below.

If the requirement is to have Header Image be active (or any instance of it - see above) for a selected menu only, than here is what I would do:

Let's assume you have one Header Image module and a following module main menu structure:


The module configuration page in the Administrator allows binding the module to the main menus structure by selecting the relating menu entry in the “Pages / Items” list that is part of the module configuration page. And this applies to any module in Joomla.

Lets further assume the following:

  • I want to have the module active for all pages of the site: I will choose Menu Item Link All
  • I want to have the module active for the NEWS menu only: I will choose Menu Item Link mainmenu | News

This is now for a single module, for multiple modules its the same, one example:

Lets assume I want to have the following 2 Header Image instances and the above menu tree:

  • Headers 1 shall be shown on all pages
  • Headers 2 shall be shown on the login page only

I would then simply set the Menu Item Link in the each modules configuration as followed:

  • For Headers 1 to Menu Item Link All
  • For Headers 2 to Menu Item Link mainmenu | News

For using Flash-Files with the module, the required object integration needs to be places into the HTML Code window and the modules Operation Mode must be in “Use HTML Code”.

Flash files must be named just as any static image file according to the Naming Conventions and the corresponding file extensions are required to get set as with any static image.

Together with the option “Use HTML Code”, the HTML Code panel at lower end of the settings is now the place where you put your code that shall be sent to the browser by the module and that represents the flash file integration.

This is the same code package as required to be in any HTML File that requires to have a Flash File displayed, for example:

Typical embedding block for Marcomedia Flash file

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="" width="510" height="400">
  <param name="movie" value="images/stories/movies/PISC_FlashIntro_EN.swf"/>
  <param name="quality" value="high" />
  <param name="wmode" value="transparent" />
  <embed src="images/stories/movies/SomeFlashFile.swf" quality="high" pluginspage="" type="application/x-shockwave-flash" width="510" height="400" wmode="transparent">

Now wherever we use the SomeFlashFile.swf file name, we need to replace it with Module Specific Tags such that the module is able to insert the current selected filename there as replacement for the actual file name that is generated by the module based on your previous settings.

Header Image uses module specific tags for representing module runtime information for use in HTML Code parts or the respective property files for image extending HTML code.

The currently supported tags are:

For the Creative Commons License

#__image       ... represents the URL of current image the module has selected.

For the Commercial Unlimited License

#__image       ... represents the URL of current image the module has selected or the complete <IMG> Tag dependant on settings.
                   When using the Slideshow Feature, this tag will be replaced by the Slideshow Image Code.

#__width       ... represents the width of the selected static image or the calculated width as per the Size of Slideshow Area setting.
#__height      ... represents the height of the selected static image or the calculated height as per the Size of Slideshow Area setting.

{content}      ... represents the full Content of the Content Item which TITLE ALIAS is the same as the current selected Images Filename.
{introtext}    ... represents the Intro-Text of the Content Item which TITLE ALIAS is the same as the current selected Images Filename.
{fulltext}     ... represents the Full-Text of the Content Item which TITLE ALIAS is the same as the current selected Images Filename.

{content=##}   ... represents the full Content of the Content Item with ID ##.
{introtext=##} ... represents the Intro-Text of the Content Item with ID ##.
{fulltext=##}  ... represents the Full-Text of the Content Item with ID ##.

Content Items included by the respective tags are being processed with the Content Mambots (Joomla 1.0) or Content Plugins (Joomla 1.5) before being displayed.

To automatically relate a Content Item to the currently selected image, place the images filename without extension into the “Title Alias” (Joomla 1.0) / “Alias” (Joomla 1.5) field of that Content Item.

Example: himg-c1

Due to character filtering in the Title Alias within Joomla 1.5.x only the hyphen as possible character for the filename prefix is supported.

So above code modified for use in the Header Image module would read as (and is copy-paste-able):

Embedding block for Macromedia Flash when using with Header Image in its HTML Code

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="" width="510" height="400">
  <param name="movie" value="#__image"/>
  <param name="quality" value="high" />
  <param name="wmode" value="transparent" />
  <embed src="#__image" quality="high" pluginspage="" type="application/x-shockwave-flash" width="510" height="400" wmode="transparent">

Make sure the width=“…” and height=“…” tags do math your actual Flash objects dimension.

All other settings are as to anyones liking.

Hyperlinks will only work outside the flash object. The Flash object itself is a event consumer, so if there is the need to have a hyperlink inside the Flash object that needs to go into the Flash object. The Header Image Hyperlink feature does not function with a event consuming object like Flash.
Due to Joomla in previous times adding line break tags to the content of the HTML Code area for every line of code, the module does remove all tags from the HTML Code entered into this textarea before sending it to the browser. If you wish to use a line break, use the <br> instead.

The files for the Slideshow feature of the module need to have following hierarchy, otherwise it might be highly probable the the slideshow will not work as intended:

The module requires a entry image, and that is the same image it would select as if for static images.

Lets assume we have a Item 1 and all set such (eg. via Smart mode) that the modules looks for it then this is the file selected as static image for our Item 1:


Now I want to add more files to this entry image to form the slideshow. So together with the settings I will create more files to the above one, each carrying a unique number in the style of:


and more if so…

Let's assume we want to show a different image set for holiday season than the ones used for normal days. For this prepare additional images, maybe stored in another folder and:

  • Copy the Header Image module in the administrator backend using the “Site Modules” list.
  • Change the parameters as well as the name of the copied module instance to your liking. As per our example to display the holiday season image set.
  • Set the date and time rules within this new module instance to the time period the holiday season instance shall be active
  • Control the multiplicity by setting the “Instance Activity Control” to “Only one active instance at a time on a page”. This tells the module to check with other instances so that there is only one display.
  • Save your settings and set the module order in the “Site Modules” list. Be aware that the modules are called in a top-to-bottom order, so first comes first. So I suggest that any instance that has a date/time rule defined will be in higher order than the standard instance.
  • Try it.

Header Image uses a default image file that is used whenever there are no content context related image files found in the defined directory. To make a slideshow for all content, regardless of the currently displayed contents context, simply add as many slideshow images to the default image as wished.

A good approach to setup this is the following:

1. Setup your Header Image module such that the display of static images works

Use the choosen Name of Default File for the following steps, let's assume that is himg_default.png for now.

2. Add the slideshow files with correct name

Any additional file to the Default File that shall become part of a slideshow has to carry the same filename as its static parent file, plus a counting slide index number whereas that index number is separated by underscore ('_') from the filename's head. That rule also applies to any other, context related slideshow.


himg_default.png      ... is the Default File
himg_default_001.png  ... adds the first slideshow image (the slideshow now contains 2 files starting with the Default File)
himg_default_002.png  ... adds the second slideshow image (the slideshow now contains 3 files starting with the Default File)
himg_default_NNN.png  ... adds the NNN'th slideshow image (the slideshow now contains NNN+1 files starting with the Default File)

The module always is searching for a static image first, and then if there are any slideshow images available for the selected static image it has selected previously. So it is easy to mix static images with slideshow images and setup the slideshow parameters. Once Header Image is seeing only a static image, that static image is shown. And once it sees slideshow images added to a single static image, it will display a slideshow of those.


himg_default.png     ... the single default image
himg_default_01.png  ... the default image shall have another one for a slideshow

himg_s1.png          ... one single image for Section 1 only

himg_s2.png          ... the single image for Section 2
himg_s2_01.png       ... one image added for a slideshow on Section 2
himg_s2_02.png       ... another image added for a slideshow on Section 2 (now we have 3 images in a slideshow on Section 2 only)

himg_s3.png          ... one single image for Section 3 only

When mixing embedded objects (as Macromedia Flash files) with static images or slideshows then these must be setup in 2 (or more) instances of the module. On how to use embedded objects with Header Image, see the Documentation and the FAQ above for more on that.

To again mix static images and slideshow within one instance of the module, see in the FAQ above how to set the module and filenames to allow that.

This is the best way to mix embedded objects and images on one site:

1) Setup the first instance of the Module for the embedded object

Set this instance of the module to the corresponding menu item(s) where this module setup shall be used:

2) Make a copy of the module and setup that one for your static images or slideshows

Set this new instance of the Module to the other menu item(s) where this particular module setup shall be used:

Embedded objects as Macromedia Flash are event consumers. Meaning by it that any mouse event, such as clicking, is consumed by the object itself and will never reach the browsers event handling. That is the cause that when using links or anchors around embedded objects will never receive any mouse event and seem to be 'dead'.

Always include any links or anchors in your embedded object when using with Header Image

When using the module to embed HTML code that is a JavaScript which itself requires the current filename that the module selects at runtime, that requires to get passed to the called JavaScript as variable. Here is some code to use in the modules HTML code area that passes the current image file name to the JavaScript it loads:

HTML Code in Module Parameters

<script type="text/javascript">
* Setting a global JavaScript variable with the current image filename
var himg_current_file = '#__image';
<!-- Now calling the actual script that shall use above vars -->
<script type="text/javascript" src="http://<your server>/somescript.js"></script>


document.write('<param name="movie" value="'+himg_current_file+'">');

Many undesired results may surface when using Header Image are caused by unrelated filenames, incorrect paths or misunderstood documentation. Best thing to start with is to use the modules Debug Mode set to ON (in one of its active options) to receive additional information on content context ID's, paths and files.

Here check if the filenames match the current contents context, if your paths are accessible and filled with files and if the module is showing any NOTICE or WARNING that requires further attention. The Module will also show how the current displayed file has been selected, so by observing the selection process additional information may get retrieved to solve your own issue.

When using HTML Code with this module, open the pages source code in your browser and see if the HTML Code is actually delivered to the browser and in which form. Many undesired results may result out of some incorrectness in the HTML Code itself.

As per our experience in 99% of all cases settings, files, paths or the HTML Code require attention as the module is of high quality source code, so source code malfunctioning is made improbable.

Header Image allows to include PHP scripts instead of image files. These files may carry the extension .htm,.html for static HTML files or .php for PHP Scripts (if supported by your web server).

When using PHP scripts the Joomla! global variables are fully available to the scripts when defined as usual with the following example:

global database;

The module itself requires some settings to use external HTML or PHP Scripts instead of images and these are:

  • Output Mode“Insert Code of HTML or PHP Script”
  • Slideshow Images with Smart Selection“No, show selected static image”
  • Default Folder → The folder where your scripts are located, same as with images
  • Filename Prefix → Your prefix that will get used on all scripts, example: himg_
  • Extension of Files → Set to your script extension, example: .php - or as wildcard .* where the module selects files of extension .htm,.html,.php. When using the wildcard extension, make sure only such files exist in the Default Folder.
  • Name of Default File → Name of your default HTML or PHP Script, example: himg_default.php
  • Naming Convention of the HTML or PHP scripts is the same as for images…
  • Any additional settings as if when using images…

Another frequent question is how the Header Image is to be activated in a Template, often in conjuction with templates downloaded or purchased from some Joomla! Template Factory.

So here some steps for Joomla! Beginners to activate Header Image in your template:

Publish the Module to a Module Position

Every template has Positions where Modules are able to get published. These are shown in the Position setting of each module as that applies to any module. If it is difficult to know where a particular position is located in your template, open your templates index.php file and look for mosLoadModules where the name of the position is to be found in the commencing brackets. Also Publish the Module with PublishedYes so that Joomla! knows that this module shall be active in your template.

Identify the Modules current Position

When setting Show TitleYes Joomla! will show the Modules Title in the template. That may help to identify the current position of the Module in your template. Also setting Debug ModeOn maight help as that will show information from the Module that helps to find correct settings for your site.

Modifying your template for a custom module position

If none of the preconfigured module positions of your template fit your needs, then modifying the template for a new Module position is easy:

  • Open your templates index.php file
  • Find a location where to put the new Module Position within the pages source code
  • Insert the mosLoadModules command to form a new Module Position. The Module Position Name goes into the command, in the following examples it is header.
  • Go into your Joomla! Sites Administrator and define this new Module Position in SiteTemplate ManagerModule Positions, maybe adding a description of the Position too:

  • Your new position is now ready for Header Image (and any other module) to get assigned to as already described above.
Usefull Sites for Joomla! Beginners

Here are some usefull sites for Joomla! Beginners to learn more on the Basics, as assigning a Module to a Template Position is basic to using Joomla!:

When your site template stops loading at the Header Image module position, than this is related to insufficient memory resources configured on your Server for the PHP Scripting Engine. The current resource limits defined for PHP are too tight to support your Joomla installation with your current set of extensions loaded, therefore the PHP Scripting Engine stops processing the current script due to insufficient memory resources.

When having access to your Servers PHP.INI, then the following settings may help:


; Resource Limits ;

max_execution_time = 120     ; Maximum execution time of each script, in seconds
max_input_time = 60     ; Maximum amount of time each script may spend parsing request data
memory_limit = 64M      ; Maximum amount of memory a script may consume

In a shared hosting environment, or to only increase the Memory for only the Joomla Site and when using the Apache HTTPd Webserver, you may make use a local .htaccess file in your Joomla sites home directory:

Alternatively you may add the following PHP command into your index.php file located in your Joomla sites home directory:

'index.php' located in your Joomla Home Directory

* @version	  $Id: index.php 11407 2009-01-09 17:23:42Z willebil $
* @package	  Joomla
* @copyright	Copyright (C) 2005 - 2009 Open Source Matters. All rights reserved.
* @license	  GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
// Ask for more execution memory
// Set flag that this is a parent file
define( '_JEXEC', 1 );

The current or default setting for memory_limit may be too less to support the processing of your current Joomla environment. We suggest to allow at least 32M of memory for script execution (or even better 64M.

Also check your PHP Error Log for error messages that might prevent full execution of the extension or your Joomla site. All our extensions are thoroughly tested, however errors might occur on individual basis on different systems.

To make images, which participate in a slideshow, have a link to another pages URL please follow to Using Hyperlink Anchors with the Slideshow.

(Commercial Unlimited License required for this solution)

Header Image allows to just display a related Content Item with optional HTML or PHP code, instead of delivering a Image. For that use the HTML Code area:

Set the Output Mode to this "Use HTML Code below (insert code of HTML or PHP file)"

Use .html or .php as the file extension, depending on including a static HTML page or a PHP script file

In this example we are using the following HTML file with only a remark to replace the Image placeholder:

This is required to create the relation for the Content Item as described here. That file is to be duplicated and named according to the Naming Convention to create a context relation and to allow Header Image to find the related Content Item. When removing this file, the relation is unlinked too. Such allowing to control the context relation by these files, as it would be done with standard Image files.

Use a .html or .php file for the Default File

Use the HTML Code Area for creating the output

Use the following Header Image Tags to create the Content Displayed by the module. As for example this will include the Dummy HTML File and a related Content Item (if existing):

Using transparent .PNG or .GIF files in slideshows will render unintended effects. As the image transitions use z-Index Layers for the images, the transparent parts of the images will blend through, always. That is simple due to the way the image transitions are rendered in the browser.

To avoid this effect, refrain from using transparent images with slideshows.

When your debug output, or the pages HTML source code, show that for a image the correlated slideshow images are loaded and the slideshow itself is not starting in the browser - then the most observed causes for this are:

  • Conflict of the MooTools JavaScript framework with other JavaScript frameworks on your page: See Correct use of MooTools on your Site for more on this.
  • Another JavaScript is throwing a error and processing of JavaScript on your page is being stopped by the browser: Best use Firefox and the Firebug Extension to debug the JavaScript's used on your site.

This is for the following scenario:

  1. You have Header Image working in a module position where it is displaying images
  2. You have another position in your template where you want Header Image to create image locations for use as Background Image, and that only for some of your Categories or Sections

To setup Header Image to deliver the background images for the selected Categories or Sections, follow this path:

  • Create another instance of Header Image by creating a copy of your first instance of Header Image, we now continue to work with this new instance…
  • Rename it, and see here how to publish Header Image and prepare your template file for it…
  • Use the Output Mode Use for Table Background
  • Create another directory in your Joomla site where to put the files only for the backgrounds, and set this directory as the Default Folder
  • Set Use a Default File to No, suppress output on missing relation, so that Header Image will only send output on files found to match the current context
  • Set your Filename Prefix and Extension of Files to fit your image filenames used
  • Altough we do not use a default file, keep or put a default filename into Name of Default File to have complete settings
  • Name your files according to the File Naming Convention for the Sections/Categories where these shall be the background for and put the images into the Default Folder

Now these images should only be delivered when the Section or Categories where image files are present for, are displayed.