Components in Joomla

1. The Basics

1.1 What is a Component?

A component is the main application that builds the body of a Joomla page. Think of it as a mini-application running inside Joomla. The CMS is the operating system; components are the apps that run on it.

The most important rule to remember is this:

A Joomla page is assembled from many extensions, but exactly one component produces its main content.

1.2 The Five Extension Types

A component is one member of a family of five extension types. Knowing the others is what makes the word "component" meaningful:

Components, modules, and plugins are often shipped together in one installable package (prefix pkg_).

1.3 The Page as a Newspaper

Here is the mental model. The template is the page frame. Inside it, the component fills the main area and the modules sit around it:

┌────────────────────────────────┐
│  TEMPLATE (the page frame)     │
│  ┌──────┐ ┌─────────┐ ┌──────┐ │
│  │MODULE│ │COMPONENT│ │MODULE│ │
│  │(menu)│ │ the main│ │(login│ │
│  │      │ │ content │ │    ) │ │
│  └──────┘ └─────────┘ └──────┘ │
│  ┌─────────────────────┐       │
│  │MODULE (footer)      │       │
│  └─────────────────────┘       │
└────────────────────────────────┘

If the page were a newspaper, the component is the main article. The modules are the sidebars, ads, and footers around it.

1.4 The com_ Naming Convention

Every component name starts with com_. The option parameter in the URL tells Joomla which component to run:

index.php?option=com_content&view=article&id=42
                       │            │        │
                       │            │        └─ which item
                       │            └─ which screen (the "view")
                       └─ which component

This single line is the key to understanding all Joomla routing and SEF (search engine friendly) URLs.

1.5 Components You Already Use Every Day

Open the Administrator and look at the menu. Nearly every item is a component:

Many of these are infrastructure. For example, com_categories and com_fields exist mainly so that other components can reuse them.

3. Inside a Component: The MVC Structure

3.1 The Modern Folder Layout

Since Joomla 4, components follow a clear, namespaced folder structure. Here is the admin side of com_content in Joomla 4, 5, and 6:

administrator/components/com_content/
├── content.xml              ← manifest (name, version, files, install)
├── services/
│   └── provider.php         ← DI service registration (the entry point)
├── src/                     ← PSR-4 namespaced PHP classes
│   ├── Controller/          ← decides WHAT to do
│   ├── Model/               ← talks to the DATABASE
│   ├── View/                ← prepares data for output
│   ├── Table/               ← maps one DB row to an object
│   ├── Field/               ← custom form fields
│   ├── Service/             ← routing, HTML helpers, category factory
│   ├── Helper/              ← shared utility code
│   └── Extension/           ← the component class itself
├── tmpl/                    ← the actual HTML layouts (.php)
├── forms/                   ← XML form definitions
├── sql/                     ← install / update / uninstall SQL
└── language/                ← translation .ini files

An important change to remember: since Joomla 4 there is no controller.php entry file. The entry point is now services/provider.php.

3.2 The Three MVC Roles

MVC stands for Model-View-Controller. It is a pattern that splits the work into three clear roles.

Controller - the traffic cop

• Reads the request (for example task=article.save).
• Calls the right model, then hands off to the right view.
• Contains no HTML and no SQL.

Model - the brain

• Holds the business logic and the database access.
• Answers requests like "give me article 42", "save this", "publish these IDs", or "build this list query".

View and Layout - the face

• The View object gathers data from the Model.
• The Layout (a file in tmpl/) outputs the actual HTML.

This separation of concerns is what makes a component easier to maintain, override, and test.

3.3 The Table Class

Between the Model and the database sits the Table. A Table object maps to a single database row. This is known as the Active Record pattern:

$table = $this->getTable();      // e.g. ContentTable
$table->load($id);               // SELECT * FROM #__content WHERE id = ?
$table->title = 'New title';
$table->store();                 // INSERT / UPDATE
$table->delete($id);

Tables also drive publishing state, ordering, check-in and check-out, and the JSON params column that many items use to store their settings.

5. The Developer Model

5.1 The Modern Entry Point: services/provider.php

Joomla 4 and later wire the component into a Dependency Injection (DI) container instead of using hard-coded includes. This is the single biggest change from "classic" Joomla. The file services/provider.php registers the factories the component needs and then builds the component object:

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        // Register the factories the component needs:
        $container->registerServiceProvider(new CategoryFactory('\\Joomla\\Component\\Content'));
        $container->registerServiceProvider(new MVCFactory('\\Joomla\\Component\\Content'));
        $container->registerServiceProvider(new ComponentDispatcherFactory('\\Joomla\\Component\\Content'));
        $container->registerServiceProvider(new RouterFactory('\\Joomla\\Component\\Content'));

        // Build the component object, injecting its dependencies:
        $container->set(ComponentInterface::class, function (Container $container) {
            $component = new ContentComponent($container->get(ComponentDispatcherFactoryInterface::class));
            $component->setMVCFactory($container->get(MVCFactoryInterface::class));
            $component->setCategoryFactory($container->get(CategoryFactoryInterface::class));
            $component->setRouterFactory($container->get(RouterFactoryInterface::class));
            return $component;
        });
    }
};

This is a real example from com_content, lightly trimmed.

5.2 Old Way versus New Way

The change is easiest to understand by comparing the two styles side by side.

Classic (Joomla 1.5 to 3):

require_once 'controller.php';
$controller = new ContentController();   // tightly coupled, global state
$controller->execute(JFactory::getApplication()->input->get('task'));

Modern (Joomla 4 to 6):

// The MVCFactory builds controllers, models and views for you,
// injecting the database, input, user, dispatcher, etc.
$controller = $mvcFactory->createController('Article', 'Site', [], $app, $input);

Why the new way is better:

• Namespaced PSR-4 autoloading: no manual require statements.
• Testable: dependencies are injected, not fetched from global state.
• Consistent: every core component is wired the same way.

5.3 The Dispatcher

The Dispatcher is the component's front door at runtime. The ComponentDispatcherFactory builds it. It reads the request, enforces access, and routes to the right controller and task:

CMS App → ComponentInterface → Dispatcher → Controller → Model → View

Most components never write their own dispatcher. They inherit the default ComponentDispatcher. You only override it for special bootstrapping needs.

5.4 Routing and SEF URLs

The RouterFactory gives a component its own Router. The router converts between the internal query and the clean URL:

?option=com_content&view=article&id=42&catid=9
        (internal query)

        ⇄

/news/9-events/42-summer-party
        (clean SEF URL)

• build() turns the query into URL segments, for the links you generate.
• parse() turns URL segments back into a query, for incoming requests.

Good routing is what makes a component's URLs friendly for both people and search engines.

5.5 Events: How Plugins Extend a Component

A component stays decoupled from the extensions that customise it by firing events at key moments. Plugins listen for these events. The component never needs to know who is listening:

// Inside the model's save(), com_content dispatches events:
$this->getDispatcher()->dispatch('onContentBeforeSave', $event);
// ... write to the database ...
$this->getDispatcher()->dispatch('onContentAfterSave', $event);

Common content events that any plugin can hook into:

This is loose coupling. A plugin can add behaviour to com_content, or to your own component, without touching its code.

7. Working with Components

7.1 How to Read Any Component

When you want to understand a component, read its files in this order. The same map fits every core component and most third-party ones:

1. The *.xml manifest: what is it, what version, what files, what tables?
2. services/provider.php: the entry point and which services it uses.
3. src/Controller/: the available tasks.
4. src/Model/: where the data comes from.
5. tmpl/: what the user actually sees.

7.2 Overriding a Component the Right Way

Never edit core component files directly. They are overwritten on the next update, and your changes are lost. Instead, use the correct technique for what you need to change:

A template override is simply a copy of the layout file in a special location:

Copy:  components/com_content/tmpl/article/default.php
To:    templates/mytemplate/html/com_content/article/default.php

7.3 Building Your Own: The Minimum

A bare-bones working component needs surprisingly little:

com_hello/
├── hello.xml                       ← manifest
├── services/provider.php           ← register with the DI container
├── src/
│   ├── Extension/HelloComponent.php
│   ├── Controller/DisplayController.php
│   ├── Model/HelloModel.php
│   └── View/Hello/HtmlView.php
└── tmpl/hello/default.php          ← <h1>Hello, JUG!</h1>

The steps to get it running are:

1. Zip it, then go to Extensions → Manage → Install.
2. Joomla reads the manifest, copies the files, registers the namespace, and runs the install SQL.
3. Visit index.php?option=com_hello and your code runs.

A practical tip: start by copying a tiny core component (for example com_wrapper) and renaming it. You learn the structure faster from a working example than from a blank page.

7.4 Common Pitfalls

These are the mistakes that catch people most often when working with components:

• Forgetting the <namespace> declaration in the manifest, which leads to a "class not found" error.
• Some <namespace> declaration was changed, but /administrator/cache/autoload_psr4.php was not refreshed. Delete the file and Joomla will recreate it automatically.
• Editing core files directly, so changes are lost on the next update. Use overrides instead.
• Confusing a module (a small, reusable box) with a component (one per page).
• Putting business logic or SQL in the layout instead of the model.
• Re-inventing categories, fields, or tags instead of consuming the shared service.

9. Common Mistakes and Pitfalls

9.1 Confusing Components with Modules

A component produces the one main content area of a page. A module is a small box that sits around it, and you can have many on one page. If you find yourself wanting "many of the same thing" on a page, you probably want a module, not a component.

9.2 Editing Core Files

Editing files inside components/com_content/ or the administrator equivalent feels quick, but Joomla overwrites those files on the next update. Always use a template override, a plugin, a custom field, or a language override instead.

9.3 Mixing Up the MVC Layers

The most common code smell is putting database queries or business logic inside a layout file in tmpl/. Keep SQL and logic in the Model, decisions in the Controller, and only display code in the Layout. This keeps the component testable and easy to override.

9.4 Reinventing Shared Services

Do not build your own category manager, field system, or tagging system. Joomla already provides com_categories, com_fields, and com_tags as shared services. Consuming them gives your component nesting, ACL, language support, and tooling for free.

9.5 Forgetting the Manifest Details

A missing <namespace> declaration causes "class not found" errors. A missing or wrong <files> or <sql> entry means files or tables are not installed. The manifest is small, but every line matters.

11. Quick Reference

IDENTIFY     Look for option=com_xxx in the URL
SITE FILES   components/com_xxx/
ADMIN FILES  administrator/components/com_xxx/
ENTRY POINT  services/provider.php  (NOT controller.php)
STRUCTURE    src/Controller, src/Model, src/View, src/Table, tmpl/
INSTALL ROW  #__extensions  (type=component, params=JSON Options)
OWN TABLES   #__content, #__contact_details, #__banners, ...
PERMISSIONS  #__assets  (rules JSON, inherited down the tree)
OVERRIDE     templates/{tpl}/html/com_xxx/{view}/{layout}.php
EXTEND       Plugin hooking onContent* events
REST API     /api/index.php/v1/...  (enable Web Services plugin)
SHARED       Categories, Fields, Tags, Workflow, Associations