Joomla Modules and Module Positions — Module Manager and Layout Control

In this tutorial, you'll learn how Joomla modules work — the Module Manager, module positions defined by your template, assigning modules to pages, ordering modules within positions, module permissions, and custom module chrome for styling.

What You'll Learn

• The Module Manager interface and types of modules
• Module positions defined in templateDetails.xml
• Assigning modules to pages: all, selected, or except-selected
• Ordering modules within a position
• Module permissions per user group
• Advanced module settings: class suffix, style, chrome, Caching
• Module chrome styles: table, horizontal, rounded, outline
• Adding custom module class suffixes for CSS styling
• Adding custom module positions to a template

Why It Matters

Modules are how Joomla displays content outside the main article area — menus in the header, login forms in the sidebar, banners in the footer, and latest news in a secondary column. Where modules appear (position), on which pages (assignment), and in what order are three decisions you make for every module. Getting these right creates a clean, usable layout. Getting them wrong creates a cluttered, confusing page.

Real-World Use

A business website has a header with the main menu (position-0), a sidebar with a login form and latest news (position-7), a content area with articles, and a footer with contact info and social links (position-9). The sidebar modules only appear on inner pages (not the homepage). The login form only shows to non-logged-in users. The latest news module shows 5 headlines. Each module is assigned to specific pages, ordered correctly within the position, and has a custom CSS class for styling.

Learning Path

flowchart LR
  A["Menu Item Types"] --> B["Modules & Positions
You are here"]:::current
  B --> C["Custom HTML Modules"]
  C --> D["Next: Template Basics"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

The Module Manager

The Module Manager is accessed through Extensions > Modules. By default, it shows Site modules (front-end modules). You can switch to Administrator modules to manage admin dashboard modules.

Module Manager Interface

The Module Manager displays a table with:

• Checkbox: Select modules for batch operations
• Title: Module name (click to edit)
• Status: Published, Unpublished, or Trashed
• Type: Module type (Menu, Latest News, Custom HTML, etc.)
• Position: Where the module appears on the page
• Access: View level (Public, Registered, Special)
• ID: Internal ID

You can filter by position, type, status, and access level.

Default Modules

A fresh Joomla installation creates several default modules:

• Main Menu: Displays the Main Menu in position-1
• Login Form: Login form in position-7
• Popular Tags: Tag cloud in position-7
• Latest News: Recent articles in position-7
• Who's Online: Shows active users in position-7
• Footer: Copyright notice in position-9

Module Positions

Module positions are locations in your template where modules can display. The available positions are defined in your template's templateDetails.xml file.

Common Positions

The default Cassiopeia template defines these positions:

Finding Available Positions

To see all available positions for your template:

1. Go to Extensions > Templates > Styles.
2. Open your active template style.
3. The positions are listed in the Layout section.

Or add ?tp=1 to your site URL to display position outlines (requires template debug enabled in Global Configuration).

Module Assignment to Menu Items

Each module can be assigned to specific pages. This determines where the module appears.

Assignment Options

• On all pages: Module appears on every page of the site
• No pages: Module is hidden but published (useful for reference)
• Only on the pages selected: Module appears only on chosen menu items
• On all pages except those selected: Module appears everywhere except chosen items

Menu Item Selection

When you choose "Only on the pages selected" or the except variant, a list of all menu items appears. Check the items where the module should appear or be excluded.

Assignment Strategy Examples

Module Ordering

Within a module position, modules appear in a specific order. The order is set in the Module Manager.

Setting Order

1. In Extensions > Modules, filter by a position (e.g., position-7).
2. The Order column shows the current sequence.
3. Drag modules up or down, or edit the order number directly.

Duplicate Order Values

If two modules have the same order number, Joomla sorts alphabetically by title as a tiebreaker. Set order values in increments of 5 or 10 to leave room for later insertions.

Module Permissions

Each module has permission settings that control who can interact with it.

View Level

Same as articles — Public, Registered, Special, or custom. Sets who can see the module on the front end.

Action Permissions

• Delete: Who can delete this module
• Edit: Who can edit this module
• Edit State: Who can publish/unpublish this module

These permissions are usually left at default for site modules.

Advanced Module Settings

The Advanced tab in each module contains options that control appearance and behavior.

Module Class Suffix

Enter a CSS class name to add to the module's container div. The class is appended to the default module classes.

For example, a suffix of my-highlight produces:

<div class="moduletable my-highlight">
  ...
</div>

Use this to style specific modules differently from others in the same position.

Style

Controls how the module is rendered. Options depend on the template:

• Out: No wrapper — raw output
• HTML: Standard module wrapper with heading
• Table: Wrapped in a table container
• Horizontal: Horizontal layout (for menus)
• Rounded: Rounded corners wrapper
• None: No chrome at all

Module Chrome

Module chrome is the HTML wrapper that surrounds a module's content. It includes the module title, container div, and CSS classes.

Chrome styles defined in your template's templateDetails.xml:

<fields name="chrome">
  <field name="modulechrome"
    type="list"
    label="Module Chrome"
    default="0"
  >
    <option value="0">Default</option>
    <option value="1">No Wrapper</option>
    <option value="2">Outline</option>
  </field>
</fields>

Caching

• Use Global: Follow the global caching settings
• No Caching: Never cache this module (use for dynamic content like Who's Online)
• Conservative: Cache module output (safe for most modules)

Module Tag

Override the HTML tag for the module container. Default is div. You can use section, aside, nav, article, or header.

Bootstrap Size

If your template uses Bootstrap, set the column width for the module using Bootstrap classes like col-md-3, col-sm-6, or col-12.

Module Class Suffix Examples

Module class suffixes are a powerful way to style individual modules without creating custom module chrome.

Example 1: Blue Background

Suffix: blue-bg

Produces: <div class="moduletable blue-bg">

CSS to add to user.css:

.blue-bg {
    background-color: #e3f2fd;
    padding: 15px;
    border-radius: 8px;
}

Example 2: No Border

Suffix: no-border

Produces: <div class="moduletable no-border">

CSS:

.no-border {
    border: none;
    box-shadow: none;
}

Example 3: Icon Before Title

Suffix: news-icon

CSS:

.news-icon .module-title:before {
    content: "\f1ea";
    font-family: FontAwesome;
    margin-right: 8px;
}

Adding Custom Module Positions

If your template does not have the position you need, you can add custom positions by editing the template's templateDetails.xml.

Locate templateDetails.xml

Go to Extensions > Templates > Templates. Click on your template. In the Files list, find templateDetails.xml.

Add Positions

Find the <positions> section and add new position names:

<positions>
    <position>position-0</position>
    <position>position-1</position>
    <position>position-2</position>
    <position>position-3</position>
    <position>my-custom-position</position>
    <position>pre-footer</position>
</positions>

Display the Position in Your Template

In your template's index.php, add a jdoc:include statement where you want the modules to appear:

<jdoc:include type="modules" name="my-custom-position" style="html" />

After Adding Positions

1. Save the templateDetails.xml file.
2. Go to Extensions > Modules and create a module.
3. The new positions appear in the Position dropdown.
4. Assign modules to the new position.

Module Chrome Customization

Module chrome controls the HTML wrapper around each module. You can customize it in your template.

Default Module Chrome

<div class="moduletable">
    <h3 class="module-title"><?php echo $module->title; ?></h3>
    <?php echo $module->content; ?>
</div>

Creating Custom Chrome

Copy the default chrome file to create a custom version. In Cassiopeia, chrome files are in templates/cassiopeia/html/modules.php.

Common Mistakes

1. Not checking which position a module is assigned to: A module published with no position selection defaults to "hidden" and does not appear. Always verify the position is set.

2. Using the wrong assignment type: Setting a module to "Only on the pages selected" but not checking any pages means the module appears nowhere. Select pages explicitly.

3. Conflicting order values: Setting all modules in a position to order "0" causes unpredictable ordering. Use unique or incremented values.

4. Forgetting to add positions to templateDetails.xml: Custom positions only appear in the Module Manager if they are defined in the template's XML file. Verify the XML after adding positions.

5. Overusing module class suffixes: Adding too many custom classes makes templates hard to maintain. Use a consistent naming convention and document your suffixes.

Practice Questions

1. What determines which module positions are available in Joomla? Answer: Module positions are defined in the template's templateDetails.xml file. Each template can define different positions.

2. How do you make a module appear only on the homepage? Answer: In the module's Menu Assignment tab, select "Only on the pages selected" and check the menu item that is set as the default (home) page.

3. What is the purpose of a module class suffix? Answer: A module class suffix adds a custom CSS class to the module's container div, allowing you to style individual modules differently without changing the template.

4. Challenge: Create a module layout strategy for a magazine website. Define at least 5 module positions, assign specific module types to each position, set menu assignment rules for each module, and add custom class suffixes for styling. Implement the layout in a local Joomla installation with at least 8 modules across 4 positions.

FAQ

Mini Project

Your task: Build a complete module layout for a blog website.

1. Create these modules and assign them to appropriate positions:

   • Main Menu in position-1 (header) — assigned to all pages
   • Breadcrumbs in position-2 — assigned to all pages
   • Login Form in position-7 (sidebar) — assigned to all pages except homepage, hidden from logged-in users
   • Latest News in position-7 — assigned to blog section only, 5 articles
   • Popular Tags in position-7 — tag cloud format, 10 tags
   • Who's Online in position-7 — assigned to all pages
   • Footer in position-9 — assigned to all pages

2. Order the sidebar modules: Login first, then Latest News, then Popular Tags, then Who's Online.

3. Add module class suffixes: "login-module" for login, "news-module" for latest news, "tags-module" for popular tags.

4. Create a custom module position called "sidebar-bottom" below the existing sidebar. Add a Custom HTML module there with copyright information.

5. Test the layout on the front end, verifying module positions and ordering.

What's Next

Now that you understand modules and positions, learn how to create custom content with Custom HTML modules:

Continue to Lesson 14: Custom HTML Modules — Building custom content and layouts with HTML, CSS, and module class suffixes.

Related lessons:

• Joomla Content Modules — Content display modules in detail
• Joomla Menu System — How menu modules connect menus to positions