Alternative Layout Not Working for Your Custom Joomla Module? Read This!

While working on making a very large website responsive over the past few days, we were faced by a small blip. A small, but interesting (and annoying) blip… We wanted to show a different layout for a custom made module (we’re not talking here about Joomla’s Custom HTML module [which is now called just the Custom module]; we’re talking about a module that was specifically created for that website), and so we just created the appropriate folder under the html folder of the template being used, and then we copied the layout file of that module (default.php) to the folder that we have just created. After doing so, we did the modifications that we needed to do on the copied file (we called it mobile.php), and then we went to the Joomla backend and tried to select the new layout that we have created from the module’s settings. But, the field for selecting a layout was just not there.

No problem, we thought, as we knew the exact cause of this issue: the Alternative Layout field did not exist in the XML manifest file of the custom module. So we opened the XML manifest file of a standard Joomla module, and we copied this line…


…to the manifest file of the custom module (just before the closing fields tag). After doing this, we went back to the module, and confidently chose mobile, and then we went to the website, and checked to see whether our changes to the layout of the module have taken effects, but they didn’t. Easily fixed, we thought… We went back to the backend and cleared the Joomla cache, but still, the website still showed the default layout for that module.

We went back to the module, and we tripled checked that it was that module being loaded, and that the layout change was saved, and everything checked. Naturally, clearing the cache a few dozens time more didn’t fix the problem – it just wasn’t a cache problem!

We finally decided to check the module’s main PHP file, which is module_name.php under the module’s folder, and its last line (responsible for calling the file that does the actual display) consisted of the following:


But, in order for the module, any module, to benefit from the Joomla alternative layout functionality, it must have this line at the end (instead of the one above):

require JModuleHelper::getLayoutPath('mod_modulename', $params->get('layout', 'default'));

So we switched the last line of the custom module with the line above, and this time, the layout override worked! It worked! It was a great relief mixed with some irritation, because we knew that the root cause of this problem was a bad Joomla developer. In any case, we were exalted because the problem was solved.

So, if your alternate layout is not displaying on your Joomla website, make sure that your module supports alternative layouts both in its XML manifest file and in its main PHP file. If it doesn’t, then you can resolve this by following the tips in this post. If you need help with the implementation, then please contact us. We will help you address this in no time and for a very affordable fee!

No comments yet.

Leave a comment