Modules layout

JEM Module Layouts

Applies to: JEM 4.5 beta 5 and JEM 5.0 beta 3, depending on the Joomla version used by the site.

This article explains how JEM modules use their own layout selector, how the available layouts are detected, and how administrators or template developers can create additional layouts.

Purpose

JEM modules have their own layout level. This is separate from the global JEM frontend layout style used by component views.

Each module can expose several PHP layouts in its tmpl folder. Joomla displays these layouts in the module Advanced tab under the standard Layout field. JEM also loads a matching CSS file when one exists.

Where to Configure a Module Layout

Go to System > Site Modules.
Open the JEM module instance.
Open the Advanced tab.
Find the Layout field.
Select the desired layout.
Save the module.

Important: Changing the global JEM layout style does not automatically change the selected module layout. Modules must be configured individually.

Available Layouts by Module

Module	Available PHP Layouts	Default Layout
`mod_jem` - JEM Basic Module	`default`, `responsive`, `table`, `table-style`, `table-advanced`, `acymailing`	`default`
`mod_jem_banner` - JEM Banner Module	`default`, `responsive`, `cards`, `table-advanced`	`default`
`mod_jem_cal` - JEM Calendar Module	`default`, `darkblue`, `grid`	`default`
`mod_jem_jubilee` - JEM Jubilee Module	`default`, `responsive`	`default`
`mod_jem_map` - JEM Venues Map Module	`default`	`default`
`mod_jem_teaser` - JEM Teaser Module	`default`, `responsive`	`default`
`mod_jem_types` - JEM Types Module	`default`	`default`
`mod_jem_wide` - JEM Wide Module	`default`, `responsive`, `default_jem_eventslist`, `default_jem_eventslist_small`	`default`

Layout CSS Files

For many JEM modules, the selected layout name is also used to load a CSS file with the same name. For example, if the selected layout is responsive, JEM tries to load responsive.css.

Module	Layout CSS Examples	Additional Style CSS
`mod_jem`	`default.css`, `responsive.css`, `table.css`, `table-style.css`, `table-advanced.css`, `acymailing.css`	None
`mod_jem_banner`	`default.css`, `responsive.css`, `cards.css`, `table-advanced.css`	`alpha.css`, `blue.css`, `green.css`, `orange.css`, `red.css`, `category.css`, `iconfont.css`, `iconimg.css`
`mod_jem_cal`	`default.css`, `darkblue.css`, `grid.css`	Calendar-specific styling is tied closely to the selected calendar layout.
`mod_jem_jubilee`	`default.css`, `responsive.css`	`alpha.css`, `blue.css`, `green.css`, `orange.css`, `red.css`, `iconfont.css`, `iconimg.css`
`mod_jem_map`	`default.css`	`mod_jem_map.css` is used for map-specific styling.
`mod_jem_teaser`	`default.css`, `responsive.css`	`alpha.css`, `blue.css`, `green.css`, `orange.css`, `red.css`, `category.css`, `venue.css`, `iconfont.css`, `iconimg.css`
`mod_jem_types`	No dedicated CSS file in the module layout folder by default.	Styling normally comes from the template or module output classes.
`mod_jem_wide`	`default.css`, `responsive.css`	`iconfont.css`, `iconimg.css`

How JEM Finds Module CSS

When a module layout or style CSS is requested, JEM searches in this order:

templates/YOUR_TEMPLATE/css/MODULE_NAME/LAYOUT_NAME.css
templates/YOUR_TEMPLATE/html/MODULE_NAME/LAYOUT_NAME.css
media/MODULE_NAME/css/LAYOUT_NAME.css
modules/MODULE_NAME/tmpl/LAYOUT_NAME.css

This means a template can override the CSS without editing the module core files.

Creating a New Module Layout

The easiest way to create a new module layout is to duplicate an existing PHP layout and its matching CSS file, then rename both files with the same base name.

Example: Create a Custom Layout for `mod_jem`

Open modules/mod_jem/tmpl/.
Duplicate responsive.php.
Rename the copy to mycustom.php.
Duplicate responsive.css.
Rename the copy to mycustom.css.
Edit the PHP and CSS files as needed.
Open the module in Joomla.
Go to the Advanced tab.
Select the new layout in the Layout field.
Save the module.

Joomla recognises the new PHP layout because it exists in the module layout folder. JEM can then load the CSS file with the same layout name.

Production recommendation: For a live website, use a Joomla template override instead of editing files directly inside modules/MODULE_NAME/tmpl/. Direct module changes can be overwritten during updates.

Creating a Template Override Layout

For site-specific customisation, place the custom layout in the active Joomla template:

templates/YOUR_TEMPLATE/html/mod_jem/mycustom.php
templates/YOUR_TEMPLATE/html/mod_jem/mycustom.css

If the CSS is stored separately, JEM also supports:

templates/YOUR_TEMPLATE/css/mod_jem/mycustom.css

This keeps custom layout work separate from the JEM package and makes upgrades safer.

Choosing the Right Layout

Need	Recommended Layout Type
Simple upcoming events list	`default` or `responsive`
Compact table-like event output	`table`, `table-style`, or `table-advanced` where available
Newsletter or email-friendly output	`acymailing` in `mod_jem`
Visual event promotion block	`mod_jem_banner` with `default`, `cards`, or `responsive`
Calendar grid	`grid` in `mod_jem_cal`
Map-based venue discovery	`default` in `mod_jem_map`

Layout and Style Combinations

Some modules separate the structural layout from visual style options. For example, a module may use responsive.php as the layout while also loading a colour CSS file such as blue.css or an icon style such as iconfont.css.

This allows combinations such as:

Responsive structure with blue visual style.
Default structure with category-based colour styling.
Card layout with image icons.
Table layout with icon font styling.

Troubleshooting

Symptom	Check
The new layout does not appear in the module Advanced tab.	Check that the PHP file is inside the correct module `tmpl` folder or template override folder, and that the filename is valid.
The layout appears, but the CSS is not loaded.	Check that the CSS file uses the same base name as the selected layout, for example `mycustom.php` and `mycustom.css`.
The module still looks like the old layout.	Clear Joomla cache and browser cache. Also verify that the correct module instance was edited.
The layout breaks after an update.	Move custom work to a Joomla template override instead of editing files directly inside the module folder.
A warning says that a CSS file could not be found.	The selected layout or style requested a CSS file that does not exist in the template, media, or module CSS paths.

Related Development Notes

Reference	Documentation Value
#1882 - Other JEM module overrides with core ModuleHelper	Important background for module override behaviour and layout discovery.
#2073 - Warning: responsive module CSS file could not be found	Useful for understanding how JEM expects layout CSS files to be named and located.
#2095 - mod_jem_teaser responsive layout error	Relevant to responsive module layouts and compatibility checks.
#2107 - mod_jem basic module: adding venue when event title is used	Shows how module layout output depends on selected display fields and links.
#2014 - Load more button in Legacy and Responsive layout	Useful when documenting behaviour differences between compact, table-like, and responsive outputs.