Shopping Basket


Cart empty

Log In

Find Us Elsewhere


Forum Search


window-small How to display selected content, such as an image, some extra text, or the results of a search, in a popup window rather than requiring the user to click through to another page? It is a question that developers are often faced with.

In a previous article, I explained how to create and use modal windows in Joomla! using the modal behaviour (JHTML::_('behaviour.modal')). This was the old method of doing things, for Joomla 1.5 and 2.5. Actually it still works in Joomla 3, so you are free to carry on using it. However eventually it will be phased out, presumably with Joomla 4, because it relies on the old mootools javascript library, which is now deprecated, and will eventually be removed.

So if you want modal (popup) windows for your Joomla templates and extensions then it makes sense to future-proof them by switching over to the newer Joomla 3 way of doing things. The new way uses the bootstrap framework which is a jquery extension, and which includes support for modal windows. Basic usage is similar, but not that similar, to the old modal behaviour.

Simple Example: Displaying an Image

This example displays an image in a popup window when you click a button.

<a href="#myModal" class="btn" data-toggle="modal"> Click here to see my image</a>

<?php echo JHTML::_('bootstrap.renderModal', 'myModal', array(), '<img src="" />'); ?> 

If you are familiar with the old Joomla modal behaviour note the differences in the way that you create it. Rather than giving the <a> element (which operates as the link button) a css class of 'modal', we use the custom attribute 'data-toggle="modal" to alert the bootstrap script that this must be interpreted as a link to a popup window. The popup itself is given an id (in this case "myModal") and the link button is linked to it by setting its href attribute to "#myModal". In order words it is a normal html anchor element which could be used to link to an element on the page, but in this case through the magic of bootstrap the element will open as a popup.

The html to be displayed in the popup as the modal body is passed as the 4th argument to the JHTML method, in this case it is a simple <img> tag, but it could be any html you wish. For example, it can be a div element containing both text and an image as in the example below.

Example 2: Displaying HTML With Options

   $modal_params = array(); 
	$modal_params['title'] = 'This is the title';
	$modal_params['backdrop'] = "false";
	$modal_params['footer'] = '<p>This is the footer.</p>';    
   $body = '<div><img src="" /><p>An image and some text.</p></div>'; 	
<a href="#myModal" class="btn" data-toggle="modal"> Click here to see my image with a caption.</a>

<?php echo JHTML::_('bootstrap.renderModal', 'myModal', $modal_params, $body); ?> 

In this example we have supplied some options, as the third params argument. Setting the "backdrop" option to false turns off the dark overlay which by default covers the underlying page when the popup is activated.

Available Options

  • title (string) The modal title
  • backdrop (mixed) A boolean select if a modal-backdrop element should be included (default = true). The string 'static' includes a backdrop which doesn't close the modal on click.
  • keyboard (boolean) Closes the modal when escape key is pressed (default = true)
  • closeButton (boolean) Display modal close button (default = true)
  • animation (boolean) Fade in from the top of the page (default = true)
  • footer (string) Optional markup for the modal footer
  • url (string) URL of a resource to be inserted as an <iframe> inside the modal body
  • height (string) height of the <iframe> containing the remote resource
  • width (string) width of the <iframe> containing the remote resource

A frequent use for a modal window is to show the output from another page in an iframe. This is easily accomplished by setting an 'url' parameter:-

Example 3: Displaying an URL with Options

    $modal_params = array(); 
	 $modal_params['height'] = "400px";
    $modal_params['width'] = "300px";	
    $modal_params['url'] = '';
    $body = '<div><img src="" /><p>An image and some text.</p></div>'; 	
<a href="#myModal" class="btn" data-toggle="modal"> Click here to see another page.</a>

<?php echo JHTML::_('bootstrap.renderModal', 'myModal', $modal_params, $body); ?> 

As this case shows, it is possible to supply both an 'url' parameter, and html for the modal body: if you do, the body will be displayed below the iframe content. However it is possible to make the modal body an empty string, or to leave out the modal body altogether if you just want to display an iframe:-

<?php echo JHTML::_('bootstrap.renderModal', 'myModal', $modal_params); ?> 

The width and height parameters are applied to the iframe which displays the url content. It cannot be guaranteed that it will actually display at those dimensions, because often the site template will contain styles which override the display (for example, the Joomla Protostar template does). However all is not lost if you really need specific dimensions for the iframe, because it is actually quite easy to customise the layout.

Customising the Modal Layout

Joomla modal windows are defined using layouts, making it very easy to override them, either in your template, or in a component if you are an extension developer. You can read about using Joomla layouts here. The modal layout is defined in joomla.modal.main, if you want to make your own modal layout, copy the modal files into an equivalent path in your own layouts folder, then edit them as you wish.

An interesting thing to notice is that any parameters that you set will be automatically passed directly to the layout, so that you can create your own custom parameters in addition to standard Joomla ones. For example, suppose that you would like to have the option for setting a css class for the iframe element, which you could then use to set custom width and height styles for the element. You could do this by passing your own 'css' parameter in the options array:-

Example 4: A Custom CSS Option

    $modal_params = array(); 
	 $modal_params['css'] = "customModal";
    $modal_params['url'] = '';
<a href="#myModal" class="btn" data-toggle="modal"> Click here to see another page.</a>

<?php echo JHTML::_('bootstrap.renderModal', 'myModal', $modal_params); ?> 

In the layout joomla.modal.iframe, notice that it includes this code:-

$iframeAttributes = array(
'class' => 'iframe',
'src' => $params['url']

Just replace it with this:-

$iframeAttributes = array(
'class' => $params['css'],
'src' => $params['url']

Now you have implemented your own custom option which you can use to set your choice of css class for the iframe when you create it. In your extension stylesheet you could create some custom styles for an iframe element with the css class of "customModal", for example:-

iframe.customModal{width: 500px}

Scripting With Modal Windows

If you want to do more complex stuff, then you can do this by scripting directly with the bootstrap framework. First of all you will need to include the bootstrap framework. In the examples above using JHTML::_('bootstrap.renderModal') the framework is automatically included so in those cases you don't need to do it, but this is how to include it yourself:-


This will automatically load both the jquery framework and the bootstrap framework.

A typical application is that you might want to submit a form ('myform') using Ajax, and then display the results in a div element with the id 'myresults' which will open in a modal popup. This can be accomplished with a very simple jquery script:-

Example 5: Displaying Ajax Form Results

             var $form = $(this), url = $form.attr( "action" ), data = $form.serialize();			 		
             var posting = $.post( url, data ); 	
             posting.done(function( data ) { 				


<div id="resultsModal" class="modal fade" role="dialog">
     <div id="myresults" class="modal-body"></div> 

You need to give the popup container a css class of "modal" in order to identify it as a modal to the bootstrap modal script, also giving it a class of "fade" allows the popup to fade in when it is opened (otherwise you might see its outline on the page before it is opened). In real usage you would probably want to create a more sophisticated layout for the modal dialog, for example giving it a header or a close button. Here is a nice explanation of how to create the layout for a bootstrap modal.


Author Profile