components.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright © 2022-2024 Nikolaos Dionysopoulos

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with
no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
in the section entitled "GNU Free Documentation License".
-->
<chapter version="5.1" xml:id="com" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:trans="http://docbook.org/ns/transclusion"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>Components</title>

  <para>The Joomla component is arguably the most important extension type.
  It's not just the sheer fact that it is an application inside an
  application, letting us create custom experiences otherwise nearly
  impossible with just core code, it is also that Joomla embraces the need for
  this kind of custom experiences and has heavily invested in making component
  development relatively easy. This is in stark contrast with WordPress where
  your experience is far and foremost defined by its core code, custom
  experiences outside custom content types are actively discouraged and there
  is no sensible API for creating an equivalent extension type without a lot
  of reinventing the wheel, bending over backwards and judicious application
  of the Dark Arts.</para>

  <section xml:id="com-mvc">
    <title>The Joomla MVC: an introduction</title>

    <para>Joomla came with a strong legacy of modular architecture in version
    1.0, when it was a little more than a fork of and improvement upon Mambo
    4, its predecessor. Joomla 1.5 introduced extension developers to the
    concept of <link
    xlink:href="https://en.wikipedia.org/wiki/Model–view–controller">MVC</link>
    (Model-View-Controller) where each component has defined and logical
    structure, separating business logic from presentation. Joomla 4 improves
    upon this legacy, by further polishing the MVC and embracing concepts
    introduced to the PHP developer's arsenal over the last decade and a
    half.</para>

    <para>Before delving into improvements and changes in Joomla 4 I think a
    little Joomla MVC refresher is in order. This is especially useful if you
    are used to the MVC definition from a college Computer Science class or
    have used real MVC in other programming languages or even PHP frameworks
    (e.g. in Laravel the typical Model is Eloquent which works completely
    differently, the View is your Blade files and the Controller is more of a
    collection of middleware rather than a single class — it's still MVC but a
    different dialect in the same way Spanish, Italian and French are all
    Romance languages).</para>

    <para>Joomla follows the MVC model typically called “skinny controller -
    fat model”. This puts most of the business logic into the Model and keeps
    the Controller a relatively nimble affair. Further to that, Joomla also
    uses another class called a Table to abstract our interaction with the
    persistence layer objects (that's a fancy, pretentious way of saying
    “database table”). So, it's really an MVCT approach.</para>

    <para>But what are these Controllers, Models and Views anyway?</para>

    <para>The Controller consists of one or more <emphasis>tasks</emphasis>
    implemented as public methods. Each one of them tells the controller to
    <emphasis>do</emphasis> something. For example display an article, publish
    or unpublish an article, delete an article, log in the user, check the
    Multi-factor Authentication provided by the user, create a user data
    deletion request and so on and so forth. Controllers are orchestrators;
    they know what work needs to be done but they do not do it themselves. The
    Controller handles requests: it reads the user input and decides what
    needs to happen next which is invariably one of two things. For simple
    tasks with no output like publishing an article, deleting an article,
    logging in a user etc it will get the Model, tell it what to do and then
    issue a redirection to a different page, possibly setting a (very short!)
    message to show to the user. Most of the time it will need to create a
    document, e.g. an HTML page, a JSON document, an RSS feed etc. In this
    case it will get the appropriate View, push the Model to it and ask it to
    render itself. It then takes the rendered document and echoes it; Joomla
    will intercept that and decide what to do with the document effectively
    returned by the Controller. If an error occurred the Controller will catch
    it and decide what to do with it: swallow it or push it up the stack so
    that it ends up becoming an error page for the user.</para>

    <para><emphasis>Note that unlike the normative Controller of the MVC
    pattern the Joomla component's Controller DOES NOT normally push data to
    the Model. Yes, this is a violation of the separation of concerns.
    However, addressing that would be a massive backwards compatibility break
    which would necessitate the rethinking and rewriting of all Joomla
    components, core and third party. As a result we are unlikely to ever see
    this changing.</emphasis></para>

    <para>The Model is the workhorse of the component. It has the
    <emphasis>business logic</emphasis>, i.e. it knows how to get things done.
    In most cases it is a data-aware model which means that it knows how to
    get stuff from the database, put stuff back to the database and perform
    other auxiliary functions with the database data. It does NOT handle any
    presentation logic, i.e. it will NOT output any HTML. It returns raw data
    whenever it is asked to. Therefore you can use a Model in any context:
    inside the component, in a CLI script, in the API application (which only
    handles and returns JSON data), a Scheduled Task, a module, a plugin, even
    a template (though that would be a bit of an architectural violation; I
    won't judge you harshly if you do that because you're on a deadline and/or
    a shoestring budget).</para>

    <para><emphasis>Note that unlike the normative Model of the MVC pattern
    the Joomla component's Model will seek data from the user session and if
    it's not found there it will try to get it from the request. This makes it
    a pain in the posterior to use outside the frontend, backend and API
    applications, e.g. in a CLI application. Yes, there's a trick to that (and
    probably a section I will have to write at some point): set its state
    manually and it will no longer try to get data from the
    request.</emphasis></para>

    <para>As I said, Joomla also has a Table class which, architecturally
    speaking, is somewhere between a Model and a Persistence Layer. But we're
    not CS majors, we're Joomla extension developers. What we need to know is
    that the Table class is an abstraction which represents exactly one record
    of a database table. Table classes only exist in the backend of your
    component but can be used anywhere. They are used either inside a Model or
    directly on their own.</para>

    <para><emphasis>Tables are used by Models but not when returning multiple
    rows. When you run getItems on a ListModel you get an array of stdClass
    objects. This sounds odd at first but it makes sense; Models can join
    multiple tables and return embellished data in lists. For example, you may
    not just get a user ID but also the user's name and email address as
    separate fields. In most (but not all!) cases you could instantiate a
    Table object and call its bind() method with one of the aforementioned
    stdClass objects as its argument to get a Table object representation of
    your data. Just remember in this case that instantiating a Table object is
    computationally expensive as it needs to parse the database table's column
    definitions. Create an instance of the Table object. Then clone it for
    each row you are processing and bind the data to the Table object's clone.
    When processing a few dozen or more rows it can save you hundreds of
    milliseconds of page load time.</emphasis></para>

    <para>Then, we have Views. Now, this is the biggest departure of the
    normative MVC pattern. In Computer Science the View only renders
    information in a suitable way for the user to understand. A Joomla
    component's View is actually part controller and part ViewModel. Which
    means that Joomla's MVC is neither MVC nor MVVM, it's its own thing. But,
    as we said before, we are not CS majors, we are Joomla extension
    developers. So let's see what our View does.</para>

    <para>Our View gets data from the Model. It does a bit of error checking
    to make sure nothing is amiss — if it is, it will show an appropriate
    error state be it the new in Joomla 4 Empty State (guiding the user to
    please create some data when we have nothing to show them) or an error
    page if something has gone so bad we don't know what to do. It is also
    responsible for setting up the page metadata (frontend) or the page's
    Title and Toolbar (backend) which is View-related stuff in the same way
    that making coffee is related to hosting an in-person meeting: not really
    your job but people would be really upset if nobody did it.</para>

    <para>In the end, the View renders the information in an appropriate
    format for the user — which is what a View is really supposed to do if it
    wants to be called a View! For HTML pages it calls one or more View
    Template files to render some HTML. For other view types such as JSON,
    Raw, XML, Feed and so on a view template file may be used but it's neither
    necessary nor does it always make sense. If you're returning a JSON
    document or a CSV it makes far more sense to construct it directly in your
    View code and return it than going through an unnecessary round-trip
    through a view template file.</para>

    <para>Finally, we need to talk about the View Template files. These are
    the real View of the MVC pattern: they convert the raw data we got from
    our Model to the HTML which will be displayed to the user. Why not have
    the View return the HTML directly? Well, we <emphasis>could</emphasis> but
    we'd have two problems. First, the View itself is also part Controller and
    part ViewModel therefore we'd have an issue with the separation of
    concerns, mixing business logic with presentation logic (bad idea; we are
    using MVC to avoid this bad practice). Second, Joomla's raw, unadulterated
    power comes from the fact that our end users can
    <emphasis>override</emphasis> View Templates in their sites, thereby
    changing the presentation of our component in ways we can neither think of
    nor support in any meaningful way across our entire user base.</para>

    <para>This is the overview of Joomla's MVC and you'll be happy to know
    that it has not actually changed ever since Joomla 1.5. Some
    implementation details have changed but the core concepts — the good, the
    bad and the ugly parts alike — have remained unchanged in Joomla 4. In
    other words, if you already have a perfectly serviceable component written
    for Joomla 3 you <emphasis>can</emphasis> migrate it to Joomla 4. It's not
    a different language (like Italian to Spanish), it's a different
    <emphasis>dialect</emphasis>. Yes, you'll need to learn the vernacular of
    the new dialect but it's much, much easier than learning a new language. I
    am saying that as someone who had to learn three foreign (human) languages
    and more programming languages than I care to list.</para>
  </section>

  <section xml:id="com-j3-vs-j4-mvc">
    <title>Joomla 3 MVC vs Joomla 4 MVC</title>

    <para>As we already said, the basic functionality of Joomla's MVC has
    remained the same throughout Joomla 3 and 4. If you know how to make a
    Joomla 3 component you know most of what you need to make a Joomla 4
    component. The differences are a few minor, but salient, points.</para>

    <para><link linkend="com-namespaces"><emphasis
    role="bold">Namespaces</emphasis></link>. All native Joomla 4 components
    use <link
    xlink:href="https://www.php.net/manual/en/language.namespaces.php">PHP
    namespaces</link> for their PHP code. This is a simple change in naming
    classes for models, views and controllers. For example, instead of your
    frontend model being called <code>ExampleModelItem</code> it will now be
    the class <code>ItemModel</code> in the namespace
    <classname>\Acme\Component\Example\Site\Model</classname>. The first part
    of the namespace in this example, <code>\Acme\Component\Example</code>, is
    the same for the whole component. This component namespace prefix consists
    of 3 parts:<programlisting>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable></programlisting></para>

    <para>for instance (as often used throughout this book):<programlisting>\Acme\Component\Example</programlisting>The
    3 parts of a component namespace prefix:</para>

    <itemizedlist>
      <listitem>
        <para><code><emphasis
        role="bold">\<replaceable>My</replaceable></emphasis></code> vendor
        namespace prefix: a valid PHP namespace, unique for you, your company
        or your project. A valid vendor namespace prefix can for instance be
        <classname>\Acme</classname>. A vendor namespace prefix can also have
        sub-namespaces, for instance:
        <classname>\Acme\Support\Tools</classname>. You are free to choose
        your own vendor namespace, however:</para>

        <itemizedlist>
          <listitem>
            <para>The vendor namespace should not start with
            <classname>\Joomla</classname>, because component namespaces
            starting withIn <classname>\Joomla</classname> are reserved for
            core components.</para>
          </listitem>

          <listitem>
            <para>The vendor namespace should not contain a sub-namespace
            starting with <classname>\Component</classname>. It is a reserved
            sub-namespace, that should only be used immediately AFTER the
            vendor namespace prefix in a component namespace.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><code><emphasis role="bold">\Component</emphasis></code>
        sub-namespace: literally "\Component", with a capital C. You should
        use the <code>\Component</code> sub-namespace in the component
        namespace only once: AFTER the vendor namespace and BEFORE the
        sub-namespace with the component name.</para>
      </listitem>

      <listitem>
        <para><code><emphasis
        role="bold">\<replaceable>ComponentName</replaceable></emphasis></code>
        sub-namespace: a valid component name for Joomla as is used in
        com_componentname. In the namespace-part you can use camel case; in
        com_componentname only lowercase is used. A valid component name would
        for instance be <classname>Example</classname> in the namespace
        <classname>Acme\Component\Example</classname> for component
        <code>com_example</code>.</para>
      </listitem>
    </itemizedlist>

    <para>Namespaces are originally meant to avoid name collisions for
    classes, functions and constants, while conveniently using shorter names
    to identify those classes, functions and constants. In Joomla 3 many
    frontend and backend classes had the same name, like for instance
    <classname>ContentModelArticle</classname>, and those frontend and backend
    classes couldn't be used together. Namespaces to the rescue: the frontend
    class, including its namespace, is now called
    <classname>\Joomla\Component\Content\Site\Model\ArticleModel</classname>
    and the backend class
    <classname>\Joomla\Component\Content\Administrator\Model\ArticleModel</classname>.</para>

    <para>In the PHP-world there is a standard for autoloading, which uses
    namespaces: <link
    xlink:href="https://www.php-fig.org/psr/psr-4/">PSR4</link>. A namespace
    prefix is mapped to a path in the filesystem. Any sub-namespaces that are
    under the mapped namespace are one-on-one mapped to subdirectories with
    the same names. For instance the namespace
    <classname>\Joomla\Component\Content\Administrator</classname> is mapped
    to <filename>/administrator/components/com_content/src</filename>. The
    class
    <classname>\Joomla\Component\Content\Administrator\Model\ArticleModel</classname>
    is then found in the subdirectory <filename>/Model</filename> of
    <filename>/administrator/components/com_content/src</filename>. Any code
    with a namespace that adheres to PSR4 can automatically be autoloaded. In
    Joomla the mapping is cached in the
    <filename>administrator/cache/autoload_psr4.php</filename> file.</para>

    <para>Because of the PSR4 autoloading, the namespace of your custom
    component can be used to locate any file in your component from elsewhere
    in Joomla. For example, to find the code files for custom form fields you
    may need in your component. The way to tell Joomla which namespace to use
    for custom form fields is with the <code>addfieldprefix</code> attribute
    in an XML form. This attribute of a fieldset (and method of
    <classname>Joomla\CMS\Form\FormHelper</classname>) is new since Joomla 3.8
    and can be used to add a namespace for your custom fields, so they can be
    found with PSR4 autoloading, instead of directly providing a path as was
    done with the <code>addfieldpath</code> attribute.</para>

    <para><link linkend="com-services"><emphasis role="bold">Service
    provider</emphasis></link>. All Joomla components are passed a Dependency
    Injection Container (DIC) which is, in fact, a Service Locator. This even
    applies to components written with the Joomla 3 MVC as we'll see in <link
    linkend="com-lifetime">the lifetime of a component</link>. You can
    register services specific to your component in your service locator. At
    the very least, Joomla expects you to set up the <link
    linkend="com-extension">extension class</link> of your component.
    Unfortunately, even simple components need to have a service provider as
    there is no convention-over-configuration in Joomla 4's component
    DIC.</para>

    <para><link linkend="com-extension"><emphasis role="bold">Extension
    class</emphasis></link>. The extension class <emphasis>replaces</emphasis>
    the entry point file (e.g.
    <filename>administrator/components/com_example/example.php</filename>) you
    had in Joomla 3 MVC. All components written with the Joomla 4 MVC have an
    extension class which extends from
    <code>Joomla\CMS\Extension\MVCComponent</code>. It is used to register
    special services used when working with your component such as the
    <code>MVCFactory</code> service (responsible for creating model, view and
    controller object instances), an <link linkend="com-html">HTML helper
    service</link> which extends Joomla's HTMLHelper, a <link
    linkend="com-router">Router service</link> for frontend search engine
    friendly (SEF) URL routing, and a <link linkend="com-categories">Category
    service</link> if your component uses core Categories. It also returns
    your component's <link linkend="com-dispatcher">Dispatcher</link> which is
    where the execution of your component starts. For very simple components
    you can even use the core MVCComponent class as your extension class,
    without sub-classing. See, for example, what the core
    <code>com_actionlogs</code> component does.</para>

    <para><emphasis role="bold"><link
    linkend="com-dispatcher">Dispatcher</link> instead of a front
    controller</emphasis>. In the Joomla 3 MVC paradigm you had a
    <filename>controller.php</filename> file in the root of your component's
    directory structure. This was a front-controller, supposed to figure out
    which controller to use to handle the specified view and task in the
    request. This was a bit gimmicky and error-prone, especially if you had
    components capable of displaying more than one discrete types of
    information, e.g. a downloads repository would be able to display
    categories, releases in a category and files in a release which made for
    three discrete content types which had to be handled by the same front
    controller. The new Dispatcher does the same job, it works without
    sub-classing it for most simple extensions and benefits greatly the more
    complex extensions which need more involved request processing.</para>

    <para><emphasis role="bold"><link linkend="com-html">HTML helper</link> is
    a service</emphasis>. If you had ever registered an HTMLHelper class with
    static calls this is no longer the recommended method. If you need an HTML
    helper for your extension you need to register it through the extension
    class and its methods are no longer static. Since it's a real object
    instantiated by the extension object it has access to the component's DIC,
    therefore to any service you registered in your service provider or you
    were given by Joomla in the DIC. This makes helpers testable and means
    that they can access custom services (e.g. a shipping cost calculation
    service if you are writing an e-commerce component) without trying to
    contort your code.</para>

    <para><emphasis role="bold">New format for </emphasis><link
    linkend="com-router"><emphasis role="bold">Router</emphasis></link>.
    Joomla 4 comes with a new Router which is instantiated through a service.
    The new component router superclass allows you to write efficient routers
    without a lot of boilerplate, duplicated and convoluted code.</para>
  </section>

  <section xml:id="com-lifetime">
    <title>The lifetime of a component</title>

    <para>In the previous section we talked about the new concepts in the
    Joomla 4 MVC but it's really hard to understand how they all work
    together. It's best if we talk about the lifetime of a component, i.e.
    what happens when you try to access a Joomla URL in the form
    <uri>index.php?option=com_example&amp;view=foo</uri>.</para>

    <para>The lifetime of our component starts in the application object
    (<code>SiteApplication</code>, <code>AdministratorApplication</code> or
    <code>ApiApplication</code>), namely its <code>dispatch()</code> method.
    All these methods do some initialisation and call
    <code>Joomla\CMS\Component::renderComponent()</code>. This method runs
    this line where things get interesting for our component:</para>

    <programlisting language="php">$app-&gt;bootComponent($option)-&gt;getDispatcher($app)-&gt;dispatch();</programlisting>

    <para>Let's rewrite it so it's more readable:</para>

    <para><programlisting language="php">$componentExtension = $app-&gt;bootComponent($option)
            $componentDispatcher = $componentExtension-&gt;getDispatcher($app)
            $componentDispatcher-&gt;dispatch();</programlisting>What Joomla
    does is ask the application object to <emphasis>somehow</emphasis> get a
    component extension object — even if it is a legacy component using the
    Joomla 3 MVC. Then it asks the component extension object to get it the
    component's Dispatcher object. Finally, it tells the component's
    Dispatcher to dispatch (execute) the component.</para>

    <para>These three steps are crucial to understanding the difference
    between legacy Joomla 3 MVC components, modern Joomla 4 MVC components and
    how Joomla 4 makes them all work.</para>

    <section xml:id="com-lifetime-booting">
      <title>Booting the component</title>

      <para>The <code>bootComponent</code> method is implemented by
      <classname>Joomla\CMS\Extension\ExtensionManagerTrait</classname>. The
      first thing it does, by calling its <code>loadExtension</code> method,
      is to figure out if this is a Joomla 4 MVC or Joomla 3 MVC component. It
      does that by looking for the <filename>services/provider.php</filename>
      file under the component's root. As you may have guessed this is our
      component's <link linkend="com-services">service provider</link> and the
      reason why all Joomla 4 MVC components, even the simplest ones for which
      we could infer their service provider, really do need to have a service
      provider file.</para>

      <para>If the file exists it's loaded and its services are registered
      into the copy of the Joomla DIC which is used as our component's
      DIC.</para>

      <note>
        <para>This means that our component only sees a frozen in time copy of
        the global application services. You cannot register any services in
        the component's DIC and expect them to be available in the global
        application.</para>
      </note>

      <para>If the file does not exist, Joomla creates an instance of the
      <classname>Joomla\CMS\Extension\LegacyComponent</classname>. As you can
      see, this extension object uses a legacy MVC factory object which
      "speaks" the Joomla 3 non-namespaced MVC class names and a legacy
      component dispatcher which looks for the
      <filename>componentName.php</filename> (in our example:
      <filename>example.php</filename>) component entry point file and loads
      it. This is exactly how Joomla 4 can render components using Joomla 3
      MVC.</para>

      <para>The rest of this section will talk about a Joomla 4 MVC
      component.</para>

      <para>Finally, Joomla returns <link linkend="com-extension">the
      component's extension object</link> as the result of the
      <code>bootComponent</code> method.</para>

      <tip>
        <para>You can call
        <code>\Joomla\CMS\Factory::getApplication()-&gt;bootComponent('com_example')</code>
        to get the <code>com_example</code> component's extension object
        anytime, anywhere — <emphasis role="bold">including in modules and
        plugins</emphasis>. If you subclass the
        <code>Joomla\CMS\Extension\MVCExtension</code> class in your own
        component you can create your own methods to return <emphasis>ANY
        OBJECT KNOWN TO THE COMPONENT AND ITS CONTAINER</emphasis>.</para>

        <para>This is of enormous importance.</para>

        <para>You can instantiate any MVC class of the component. You have
        access to your HTML helper, categories service and router service. You
        can get an instance of any of the custom services you created in your
        component. All of that WITHOUT any static helpers in your extension,
        WITHOUT worrying that something might break if you call your code
        outside your component. Your Models can provide a public API for third
        party developers communicating with your component.</para>

        <para>Joomla core components already do that. For example, you can get
        the backend <classname>ArticleModel</classname> of
        <code>com_content</code> in a frontend component or plugin to create a
        new Joomla article <emphasis>the right way</emphasis>:</para>

        <programlisting language="php">$articleModel = \Joomla\CMS\Factory::getApplication()
                    -&gt;bootComponent('com_content')
                    -&gt;getMVCFactory()
                    -&gt;createModel('Article', 'Administrator');</programlisting>
      </tip>
    </section>

    <section xml:id="com-lifetime-dispatcher">
      <title>Getting the Dispatcher</title>

      <para>The extension object is responsible for returning a number of
      interesting objects through its methods. These objects are meant to be
      used for interacting with the component. One of these is
      <code>getDispatcher</code> which lets us retrieve the component's <link
      linkend="com-dispatcher">Dispatcher</link> object.</para>

      <para>Your extension can have a custom dispatcher class,
      <classname>\<replaceable>My</replaceable>\Component\<replaceable>Example</replaceable>\Dispatcher\Dispatcher</classname>,
      where
      <classname>\<replaceable>My</replaceable>\Component\<replaceable>Example</replaceable></classname>
      is your component's prefix. If this class exists, an object instance of
      it is returned.</para>

      <para>If your extension does not have a dispatcher an instance of the
      default <classname>Joomla\CMS\Dispatcher\ComponentDispatcher</classname>
      (site and administrator applications) or
      <classname>Joomla\CMS\Dispatcher\ApiDispatcher</classname> (API
      application) will be created and returned instead.</para>
    </section>

    <section xml:id="com-lifetime-dispatching">
      <title>Dispatching the component</title>

      <para>The dispatcher object has a <code>dispatch()</code> method. This
      method looks in the request data to figure out which controller it needs
      to instantiate and which task it should execute on it. The controller
      object is instantiated through your component's
      <classname>MVCFactory</classname> service and its <code>execute</code>
      and <code>redirect</code> methods are called on it. So, yes, this is
      basically what your old Joomla 3 MVC <filename>controller.php</filename>
      file was doing.</para>

      <tip>
        <para>Having a custom dispatcher means that you can manipulate the
        <emphasis>controller and task</emphasis> based on other request
        variables.</para>

        <para>This is very important when your component is accessed
        <emphasis>outside of a Joomla menu item (no Itemid in the request
        variables)</emphasis>. In this case Joomla always uses the default
        (Home) menu item for the current language. This means that you may be
        getting a <uri>controller</uri>, <uri>view</uri> or <uri>task</uri>
        request variable — as well as other variables which might mess with
        your component, like <uri>id</uri> — from the Home menu item.</para>

        <para>Your Dispatcher is responsible for figuring out if this is the
        case and fix the input variables to prevent weird bugs / showing the
        wrong page of your component when it's accessed without a menu item
        id, e.g. a URL like <uri>/component/example?view=foobar</uri>. This is
        something which has happened a lot when I converted my own extensions
        to Joomla 4, including LoginGuard (the extension contributed as
        Joomla's Multi-factor Authentication feature in Joomla 4.2).</para>
      </tip>
    </section>
  </section>

  <section xml:id="com-dirs">
    <title>Directory structure</title>

    <para>The directory structure of a typical Joomla 4 MVC component is as
    follows, assuming it's called <code>com_example</code> and has the
    namespace prefix <code>\Acme\Component\Example</code>. Directories are
    suffixed with <filename>/</filename>. Please note that capitalisation
    matters (directory and file names are case-sensitive).</para>

    <itemizedlist>
      <listitem>
        <para><filename>administrator/components/com_example/</filename> The
        component's backend directory</para>

        <itemizedlist>
          <listitem>
            <para><filename>forms/</filename> Optional. List view forms and
            search tools forms (formerly in models/forms)</para>

            <itemizedlist>
              <listitem>
                <para><filename>items.xml</filename> An example form for the
                Items list view.</para>
              </listitem>

              <listitem>
                <para><filename>filter_items.xml</filename> An example search
                tools form for the Items list view.</para>
              </listitem>

              <listitem>
                <para><filename>item.xml</filename> An example form for the
                Item edit view.</para>
              </listitem>

              <listitem>
                <para>…</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>language/</filename> Not required but you should
            always somehow provide language files with your extension. The
            language files of your component (typically installed in
            <filename>administrator/languages/en-GB</filename>)</para>

            <itemizedlist>
              <listitem>
                <para><filename>en-GB/</filename> The English (Great Britain)
                language files. That's the default Joomla language.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>com_example.ini</filename> The main
                    language file for your component's views. Note that there
                    is no longer an <filename>en-GB.</filename> prefix; it's
                    implied by the directory the language file is in.</para>
                  </listitem>

                  <listitem>
                    <para><filename>com_example.sys.ini</filename> The
                    language file used by Joomla to display backend menu
                    items, permissions, the component's Options page, core
                    categories used by your component, select menu item types
                    in the menu manager, and render each menu item type's
                    configuration parameters.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>layouts/</filename> Optional. Any Joomla Layouts
            you want to ship with your extension for use in its
            backend.</para>
          </listitem>

          <listitem>
            <para><filename>services/</filename> Required. Here lives the
            <link linkend="com-services">Service Provider</link> of your
            component.</para>

            <itemizedlist>
              <listitem>
                <para><filename>provider.php</filename> The service provider
                file.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>sql/</filename> Optional, unless your extension
            makes changes to database structure or content.</para>

            <itemizedlist>
              <listitem>
                <para><filename>updates/</filename> Required. Your component's
                schema (database) files applied on each update.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>mysql/</filename> Optional. Indicates
                    updates for sites running on the MySQL database.</para>

                    <itemizedlist>
                      <listitem>
                        <para><filename>1.0.0-20220815-0000.sql</filename> A
                        database update file. You should name them
                        <filename>version-date-time.sql</filename>. The
                        version part is mandatory.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>install.mysql.utf8.sql</filename> The SQL
                executed on your component's first installation. Update files
                are not executed in this case.</para>
              </listitem>

              <listitem>
                <para><filename>uninstall.mysql.utf8.sql</filename> The SQL
                executed on your component's uninstallation. Remove any tables
                or database data you created.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>src/ Required. The root of your extension's PHP files and
            the root of the PSR-4
            <code>\Acme\Component\Example\Administrator</code> namespace
            prefix.</para>

            <itemizedlist>
              <listitem>
                <para><filename>Controller/</filename> Required. Your
                component's controllers</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>ItemsController.php</filename> An example
                    controller for a ListView</para>
                  </listitem>

                  <listitem>
                    <para><filename>ItemController.php</filename> An example
                    controller for an AdminView</para>
                  </listitem>

                  <listitem>
                    <para>…</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Dispatcher/</filename> Optional. Holds your
                custom component dispatcher.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>Dispatcher.php</filename> Your custom
                    component dispatcher.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Extension/</filename> Optional. Holds your
                custom extension class.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>ExampleExtension.php</filename> Your
                    custom extension class.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Field/</filename> Optional. Custom form
                fields. Use them in your XML forms using the attribute
                <code>addfieldprefix="Acme\Component\Example\Administrator\Field"</code>.</para>
              </listitem>

              <listitem>
                <para><filename>Model/</filename> Required. Your component's
                Models.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>ItemsModel.php</filename> An example model
                    for the Items list view.</para>
                  </listitem>

                  <listitem>
                    <para><filename>ItemModel.php</filename> An example model
                    for the Item view. Handles editing and adding
                    records.</para>
                  </listitem>

                  <listitem>
                    <para>…</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Provider/</filename> Optional. Custom service
                providers.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>RouterFactory.php</filename> Example of a
                    RouterFactory provider, if you need a frontend SEF URL
                    router.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Router/</filename> Optional. The recommended
                place to put your custom RouterFactory, if you need a frontend
                SEF URL router.</para>
              </listitem>

              <listitem>
                <para><filename>Service/</filename> Optional. Custom
                services.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>Html/</filename> Optional. Where your
                    custom HTML services (which are made available through
                    Joomla's HTMLHelper) live.</para>

                    <itemizedlist>
                      <listitem>
                        <para><filename>Example.php</filename> An example HTML
                        service.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Table/</filename> Required. Your Table
                classes.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>ItemTable.php</filename> An example table
                    class for the items of this component (which should
                    ideally live in the <database>#__example_items</database>
                    table if you want to follow Joomla best practices).</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>View/</filename> Required. Your view classes.
                All subdirectories must be in Uppercasefirst format and match
                the controller's name before the <code>Controller</code>
                word.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>Items/</filename> The directory for the
                    Items list view.</para>

                    <itemizedlist>
                      <listitem>
                        <para><filename>HtmlView.php</filename> The HTML view
                        class for rendering this backend view.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para><filename>Item/</filename> The directory for the
                    Item add/edit view.</para>

                    <itemizedlist>
                      <listitem>
                        <para><filename>HtmlView.php</filename> The HTML view
                        class for rendering this backend view.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>tmpl/</filename> Required. The view templates for
            your backend views.</para>

            <important>
              <para>All the sub-directories are in <emphasis role="bold">all
              lowercase</emphasis>. This is VERY important!</para>

              <para>Be careful if you are developing on Windows or macOS
              (which use case-insensitive filesystems). You might accidentally
              use MixedCase or Uppercasefirst folder names. While this will
              work fine on Windows and macOS it will <emphasis>fail</emphasis>
              on the Linux servers most sites run on. That's because Linux
              primarily uses case-sensitive filesystems.</para>
            </important>

            <itemizedlist>
              <listitem>
                <para><filename>items/</filename></para>

                <itemizedlist>
                  <listitem>
                    <para><filename>default.php</filename> The view template
                    for the Items view.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>item/</filename></para>

                <itemizedlist>
                  <listitem>
                    <para><filename>edit.php</filename> The view template for
                    the Item view.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>access.xml</filename> The component's permissions
            configuration file</para>
          </listitem>

          <listitem>
            <para><filename>config.xml</filename> The component;s Options page
            form file</para>
          </listitem>

          <listitem>
            <para><filename>example.xml</filename> The component's XML
            manifest</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><filename>components/com_example/</filename> The component's
        frontend directory</para>

        <itemizedlist>
          <listitem>
            <para><filename>forms/</filename> Optional. Any forms for frontend
            views (formerly in models/forms).</para>
          </listitem>

          <listitem>
            <para><filename>language/</filename> Not required but you should
            always somehow provide language files with your extension. The
            language files of your component (typically installed in
            <filename>languages/en-GB</filename>)</para>

            <itemizedlist>
              <listitem>
                <para><filename>en-GB/</filename> The English (Great Britain)
                language files. That's the default Joomla language.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>com_example.ini</filename> The main
                    language file for your component's frontend views.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>layouts/</filename> Optional. Any Joomla Layouts
            you want to ship with your extension for use in its
            frontend.</para>
          </listitem>

          <listitem>
            <para>src/ Required. The root of your extension's PHP files and
            the root of the PSR-4 <code>\Acme\Component\Example\Site</code>
            namespace prefix.</para>

            <itemizedlist>
              <listitem>
                <para><filename>Controller/</filename> Required. Your
                component's controllers</para>
              </listitem>

              <listitem>
                <para><filename>Dispatcher/</filename> Optional. Holds your
                custom component dispatcher for the frontend only.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>Dispatcher.php</filename> Your custom
                    component frontend dispatcher.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Model/</filename> Required. Your component's
                Models.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>ItemsModel.php</filename> An example model
                    for the Items list view.</para>
                  </listitem>

                  <listitem>
                    <para><filename>ItemModel.php</filename> An example model
                    for the Item view. Handles editing and adding
                    records.</para>
                  </listitem>

                  <listitem>
                    <para>…</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>Service/</filename> Optional. Custom
                services.</para>

                <itemizedlist>
                  <listitem>
                    <para><filename>Category.php</filename> Optional. Your
                    site's category service.</para>
                  </listitem>

                  <listitem>
                    <para><filename>Router.php</filename> Optional. Your
                    site's SEF router.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para><filename>View/</filename> Required. Your frontend view
                classes. All subdirectories must be in Uppercasefirst format
                and match the controller's name before the
                <code>Controller</code> word.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><filename>tmpl/</filename> Required. The view templates for
            your backend views. All the sub-directories are in <emphasis
            role="bold">all lowercase</emphasis>.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><filename>api/components/com_example/</filename> Optional. Your
        Joomla API application integration. Just having this directory is not
        enough, you will also need a published plugin for your application in
        the <filename>webservices</filename> folder.</para>

        <itemizedlist>
          <listitem>
            <para>src/ Required. The root of your extension's PHP files and
            the root of the PSR-4 <code>\Acme\Component\Example\Api</code>
            namespace prefix.</para>

            <itemizedlist>
              <listitem>
                <para><filename>Controller/</filename> Required. Your
                component's controllers</para>
              </listitem>

              <listitem>
                <para><filename>View/</filename> Required. Your API view
                classes. All subdirectories must be in Uppercasefirst format
                and match the controller's name before the
                <code>Controller</code> word. Note that these views DO NOT use
                view template files; they return JSON data directly.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><filename>media/com_example/</filename> Optional. Your
        component's static assets.</para>

        <itemizedlist>
          <listitem>
            <para><filename>css/</filename> Optional. Custom CSS files for
            your component.</para>
          </listitem>

          <listitem>
            <para><filename>js/</filename> Optional. Custom JavaScript files
            for your component.</para>
          </listitem>

          <listitem>
            <para><filename>joomla.asset.json</filename> The <link
            linkend="concepts-webassetmanager">WebAssetManager configuration
            file</link> for your static assets.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </section>

  <section xml:id="com-services">
    <title>Service provider</title>

    <para>As discussed in the previous section, the service provider file is
    mandatory for Joomla 4 MVC components and lives in the component's
    <filename>services</filename> folder and always named
    <filename>provider.php</filename>.</para>

    <para>The absolutely minimal minimal service provider file looks like the
    following:</para>

    <programlisting language="php">&lt;?php
defined('_JEXEC') || die;

use Acme\Component\Example\Administrator\Extension\ExampleComponent;
use Joomla\CMS\Dispatcher\ComponentDispatcherFactoryInterface;
use Joomla\CMS\Extension\ComponentInterface;
use Joomla\CMS\Extension\Service\Provider\MVCFactory;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

return new class implements ServiceProviderInterface {
  public function register(Container $container)
  {
    // PART 1: Register service providers to the component's container
    $container-&gt;registerServiceProvider(new MVCFactory('Acme\\Example'));

    // PART 2: Instantiate and set up your extension object
    $container-&gt;set(
      ComponentInterface::class,
      function (Container $container) {
        /**
         * PART 2.a: Instantiate the extension object
         *
         * If you do not have a custom extension class use \Joomla\CMS\Extension\MVCComponent instead.
         */
        $component = new \Acme\Component\Example\Administrator\Extension\ExampleComponent(
          $container-&gt;get(ComponentDispatcherFactoryInterface::class)
        );

        // PART 2.b: Set up the extension object
        $component-&gt;setMVCFactory($container-&gt;get(MVCFactoryInterface::class));

        // PART 2.c: return the extension object
        return $component;
      }
    );
  }
};
        </programlisting>

    <para>As you can see the service provider returns an <link
    xlink:href="https://www.php.net/manual/en/language.oop5.anonymous.php">anonymous
    PHP class</link> which implements the
    <code>Joomla\DI\ServiceProviderInterface</code>. That's the standard way
    to extend Joomla's DIC. Remember, as we learned in <link
    linkend="com-lifetime">the lifetime of a component</link>, Joomla creates
    a <emphasis>copy</emphasis> of its DIC and uses it as our component's own
    DIC. The service providers we set up in our component stay with our
    component, they do not leak out to the global application scope (the
    global Joomla DIC you get through the
    <code>Joomla\CMS\Factory::getContainer()</code> static method).</para>

    <para>Part 1 of that file lets us register service providers to our
    component's DIC. At the bare minimum we need to register a
    <code>Joomla\CMS\Extension\Service\Provider\MVCFactory</code> provider.
    This returns an object implementing
    <code>Joomla\CMS\MVC\Factory\MVCFactoryInterface</code> which is used by
    our component's code (and Joomla's core code) to get the MVC objects of
    our component (Controllers, Models, Views, Tables). If we want to use more
    core Joomla features with our component we may have to register more
    service providers as we'll see in the <link
    linkend="com-extension">Extension class</link> section and the rest of the
    sections of this chapter.</para>

    <para>Part 2 sets up a service provider returning an object implementing
    the <code>Joomla\CMS\Extension\ComponentInterface</code>, i.e. our
    component's extension object.</para>

    <para>Part 2.a is where we create an instance of our <link
    linkend="com-extension">extension class</link>. If you have a dead simple
    component which does not use a custom extension class you can use Joomla's
    built-in <code>\Joomla\CMS\Extension\MVCComponent</code> class instead.
    Most components will need a custom extension class so we instantiate it
    here.</para>

    <para>Part 2.b is where we set up the extension object we created in Part
    2.a. Remember when I told you that <link
    linkend="concepts-container">Joomla's DIC is not really a Dependency
    Injection Container</link> but more of a Service Locator? Because of that
    fact, when we create the extension object it does not know of any service
    objects it needs to use. Therefore we have to push them manually.</para>

    <para><emphasis>Sidebar: In my opinion, the three biggest shortcomings of
    the Joomla 4 MVC are the lack of convention over configuration, the lack
    of abstracted configuration and the lack of a real Dependency Injection
    container. These three shortcomings are, respectively, why we need to have
    a service provider file, why we need Part 1 and Part 2.b and why we need
    Part 2.a. Most other PHP frameworks have already solved these
    shortcomings. This means that any complaints that Joomla is moving to a
    very abstracted approach just to compete with other PHP frameworks are
    entirely unfounded; Joomla's architecture is still a good 10 or so years
    behind the PHP state of the art. This is not a bad thing! Too much
    abstraction may be a good thing for experienced, hardcore developers like
    yours truly but not necessarily the easiest thing to get your head around
    if you're a newcomer to Joomla or PHP in general.</emphasis></para>

    <para>Finally, we have Part 3 where we return the configured extension
    object, necessary for our custom service provider to <emphasis>actually
    work</emphasis>.</para>

    <warning>
      <para>You may be tempted to think that the service provider is only ever
      called when Joomla is about to render your component. <emphasis
      role="bold">This is not the case</emphasis>. Joomla will load a
      component's service provider any time it needs to interact with any of
      its services including the Router, or because another extension (such as
      a plugin, or module) wants to get access to your component's Models or
      some other service or object.</para>

      <para>Just because your service provider's code is running DOES NOT mean
      you are about to render an HTML page with your component, it DOES NOT
      mean that you necessarily have access to the JPATH_COMPONENT and
      JPATH_COMPONENT_ADMINISTRATOR constants and absolutely DOES NOT mean
      that you should ever, <emphasis>ever</emphasis>, try to push CSS,
      JavaScript or run any other code which assumes that Joomla is in an HTML
      output state.</para>

      <para>If you have such code (which is generally a bad idea) you should
      run it in your component's <link
      linkend="com-dispatcher">Dispatcher</link> and only after checking that
      you are indeed running in an HTML application (check the type of the
      object returned from calling
      <code>\Joomla\CMS\Factory::getApplication()-&gt;getDocument()</code>).</para>
    </warning>
  </section>

  <section xml:id="com-extension">
    <title>Extension class</title>

    <para>As we saw earlier in <link linkend="com-lifetime">the lifetime of a
    component</link>, the Extension class of a component is <emphasis>sort
    of</emphasis> a service locator for our component. Joomla checks if that
    objects implements a PHP Interface it knows about and uses the service
    communicated via the Interface implementation (typically one of the
    corresponding PHP Traits provided by Joomla) to do something useful, e.g.
    register an HTMLHelper helper, integrate with Tags, create SEF URLs by
    using a Router and so on and so forth.</para>

    <para>If your component does not make use of any of these features you do
    not need to create a custom extension class for your component. Joomla
    gives you the perfectly serviceable
    <code>Joomla\CMS\Extension\MVCComponent</code> class which implements a
    minimal Joomla 4 component: it can run because it returns a Dispatcher and
    it can create MVC objects using the Joomla 4 MVC because it returns an
    MVCFactory object. This is enough for a component which only runs in the
    backend or runs in both the frontend and the backend but has no way of
    letting Joomla create SEF URLs for it. You may think this is useless but
    I'd contest you're not thinking simple enough. Case in point, some core
    Joomla components doing exactly that. For example the
    <code>com_actionlogs</code> component which only has a backend user
    interface.</para>

    <para>That said, there wouldn't be much to write if all or even most
    components didn't need a custom extension class. You see, most components
    need one or more of the following features. I am documenting the features
    I discovered that need customisations in the extension class and give you
    an overview of the required changes in your component's code to make them
    work.</para>

    <itemizedlist>
      <listitem>
        <para>Use a custom <link linkend="com-html">HTML Helper</link>.</para>

        <para>Your extension class must implement the
        <classname>Joomla\CMS\HTML\HTMLRegistryAwareInterface</classname> and
        use the <classname>Joomla\CMS\HTML\HTMLRegistryAwareTrait</classname>.
        The extension class must override the <code>boot</code> method and
        have a line similar to
        <code>$this-&gt;getRegistry()-&gt;register('something', new
        MyHTMLHelper())</code>. We'll see what that means in the section
        covering the HTML helper.</para>
      </listitem>

      <listitem>
        <para>Use <link linkend="com-categories">core
        categories</link>.</para>

        <para>Your extension class must implement the
        <code>Joomla\CMS\Categories\CategoryServiceInterface</code> and use
        the <code>Joomla\CMS\Categories\CategoryServiceTrait</code>. Your
        service provider (<filename>provider.php</filename>) needs to register
        a <code>Joomla\CMS\Extension\Service\Provider\CategoryFactory</code>
        service provider and use the extension object's
        <code>setCategoryFactory</code> method to pass this factory to the
        extension object. The extension class must override the
        <code>getTableNameForSection</code> and
        <code>getStateColumnForSection</code> methods defined in the
        aforementioned trait and interface.</para>
      </listitem>

      <listitem>
        <para>Integrate with Joomla's Tags feature.</para>

        <para>Your extension class must implement the
        <code>Joomla\CMS\Tag\TagServiceInterface</code> and use the
        <code>Joomla\CMS\Tag\TagServiceTrait</code>. The extension class must
        override the <code>getTableNameForSection</code> and
        <code>getStateColumnForSection</code> methods defined in the
        aforementioned trait and interface.</para>
      </listitem>

      <listitem>
        <para>Integrate with <link linkend="com-fields">Joomla's Custom Fields
        feature</link>.</para>

        <para>Your extension class must implement the
        <code>Joomla\CMS\Fields\FieldsServiceInterface</code>. The extension
        class must implement the <code>validateSection</code> and
        <code>getContext</code> methods defined in the aforementioned
        interface.</para>
      </listitem>

      <listitem>
        <para>Provide a <link linkend="com-router">Router</link> for
        meaningful, human-readable SEF URLs in the frontend.</para>

        <para>Your component must have a class implementing the
        <code>Joomla\CMS\Component\Router\RouterFactoryInterface</code>
        (Router factory) and a class implementing the
        <code>Joomla\DI\ServiceProviderInterface</code> (Router factory
        provider). Your extension class must implement the
        <code>Joomla\CMS\Component\Router\RouterServiceInterface</code> and
        use the <code>Joomla\CMS\Component\Router\RouterServiceTrait</code>.
        Your service provider (<filename>provider.php</filename>) needs to
        register your Router factory provider and use the extension object's
        <code>setRouterFactory</code> method to pass the resulting Router
        factory to the extension object.</para>
      </listitem>

      <listitem>
        <para>Let Joomla associate items between languages on multi-language
        sites.</para>

        <para>Your component must have a class extending the
        <code>Joomla\CMS\Association\AssociationExtensionHelper</code>. Your
        service provider (<filename>provider.php</filename>) must register
        this class with the
        <code>Joomla\CMS\Association\AssociationExtensionInterface::class</code>
        key and use the extension object's
        <code>setAssociationExtension</code> method to assign the object
        resulting from that service to the extension object. Your extension
        object needs to implement the
        <code>Joomla\CMS\Association\AssociationServiceInterface</code> and
        use the
        <code>Joomla\CMS\Association\AssociationServiceTrait</code>.</para>
      </listitem>

      <listitem>
        <para>Integrate with Joomla's Workflows feature.</para>

        <para>Your extension class must implement the
        <code>Joomla\CMS\Workflow\WorkflowServiceInterface</code> and use the
        <code>Joomla\CMS\Workflow\WorkflowServiceTrait</code>. The extension
        class must override the <code>getModelName</code>,
        <code>filterTransitions</code>,
        <code>getWorkflowTableBySection</code>,
        <code>getWorkflowContexts</code> and
        <code>getCategoryWorkflowContext</code> methods defined in the
        aforementioned trait and interface.</para>
      </listitem>
    </itemizedlist>

    <para>As you can see, trying to do pretty much anything useful does
    require a custom extension class.</para>

    <section xml:id="com-extension-naming">
      <title>Naming your extension class</title>

      <para>There are no hard rules for naming your component's extension
      class. That said, to help anyone reading your code — including yourself
      six or so months later — retain a modicum of their sanity it is
      advisable to use the convention
      <code>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable>\Administrator\Extension\<replaceable>ComponentName</replaceable>+Component</code>
      where:</para>

      <itemizedlist>
        <listitem>
          <para><code>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable></code>
          is the namespace prefix of your component, for instance
          <classname>\Acme\Component\Example</classname></para>
        </listitem>

        <listitem>
          <para><code><replaceable>ComponentName</replaceable></code> is the
          name of your component without the <code>com_</code> prefix, with
          the first letter in uppercase, for instance <code>Example</code> for
          component <code>com_example</code></para>
        </listitem>

        <listitem>
          <para><code>Component</code> is the literal "Component". With
          <code><replaceable>ComponentName</replaceable>+Component</code> we
          mean a concatenation of the component name and the literal string
          "Component", for instance <code>ExampleComponent</code> for
          component <code>com_example</code></para>
        </listitem>
      </itemizedlist>

      <para>For example, if you have a component named
      <code>com_example</code> with the namespace prefix
      <classname>\Acme\Component\Example</classname> your extension class
      should be
      <classname>\Acme\Component\Example\Administrator\Extension\ExampleComponent</classname>
      and placed in the file
      <filename>administrator/components/com_example/src/Extension/ExampleComponent.php</filename>.</para>
    </section>

    <section xml:id="com-extension-provider">
      <title>Using your extension class in the service provider</title>

      <para>As you remember from the service provider section, in Part 2.a you
      need to instantiate the extension class. These lines would look like
      this:</para>

      <programlisting language="php">$component = new \Acme\Component\Example\Administrator\Extension\ExampleComponent(
  $container-&gt;get(ComponentDispatcherFactoryInterface::class)
);</programlisting>

      <para>Simple, isn't it?</para>
    </section>

    <section xml:id="com-extension-outside-com">
      <title>Using your extension class from outside the component</title>

      <para>Now we are finally able to answer the question which you had in
      mind coming to this section: why in the name of Cthulu do I have to have
      an extension class and what does it accomplish beyond adding yet another
      layer of complexity to my extension writing problems?</para>

      <para>For that, let's consider this. Let's say we have a news site and
      we are building a system plugin which checks every day for newly
      published articles, auto-generating a daily summary blog post using the
      intro text of these articles and some preset template (maybe even some
      judicious use of a GPT-3–based AI). This plugin would need to publish an
      article. You could of course just instantiate the
      <code>ArticleTable</code> class of <code>com_content</code> directly to
      do that but this would not run any content plugins or create the right
      entries in the #__assets table, breaking your site. You need to use the
      com_content Article backend model of <code>com_content</code>.</para>

      <para>Back in the Joomla 3 days you would do that by directly
      instantiating the <code>ContentModelArticle</code> class. Okay, first
      problem: Joomla didn't know where to find it so you have to
      <code>require_once()</code> the file. Second problem: what if that model
      changes over time and has dependencies to other classes you have failed
      to require the files of? Believe me, I've been there, done that and it
      was about as enjoyable as using a rusty fork to pull my eyes out of
      their sockets.</para>

      <para>In Joomla 4 you don't have to care about the class autoloading,
      but the <code>ArticleModel</code> will actually need access to other
      services provided by the <code>com_content</code> component for things
      like tagging, custom fields and workflows. If you try to instantiate the
      model class directly you will get a lot of errors as well. So, who are
      you gonna call? No, not Ghostbusters; they are Hollywood fiction. You're
      gonna call the very real and very useful <code>bootComponent</code>
      method of the application!</para>

      <programlisting language="php">$contentExtension = \Joomla\CMS\Factory::getApplication()
  -&gt;bootComponent('com_content');
$articleModel = $contentExtension
  -&gt;getMVCFactory()
  -&gt;createModel('Article', 'Administrator');</programlisting>

      <para>The first two lines told Joomla to “boot” the
      <code>com_content</code> component, returning its <emphasis>extension
      object</emphasis>. Now we have have access to all services known to this
      object through its various getters (method whose name start with
      <code>get</code>).</para>

      <para>This works for any component, anywhere, anytime. You can be in the
      frontend, backend, API application or CLI application or in an execution
      context you don't care to know about in a Scheduled Tasks plugin. No
      problem! You can boot any components — yours, core, or third party — to
      get its extension object and Bob's your uncle.</para>
    </section>

    <section xml:id="com-extension-dic-proxy">
      <title>Getting access to the component's DIC anytime, anywhere</title>

      <para>I see that some of you are <emphasis>still</emphasis> not
      convinced that the extension object is a cool concept.</para>

      <para>Remember when I told you that the Joomla DIC — therefore the
      component's DIC which is a customised copy of it — is not a real
      Dependency Injection Container but a Service Locator and lamented the
      fact that you cannot get a reference to it from anywhere in your
      component, unlike modern PHP frameworks like Laravel?</para>

      <para>Well, it turns out that you can get access to your component's DIC
      anywhere, anytime. You just need to add the following handy code to your
      extension's class:</para>

      <programlisting language="php">protected static $dic;

public function boot(ContainerInterface $container)
{
  self::$dic = $container;
}

public static function getContainer()
{
  if (empty(self::$dic))
  {
    Factory::getApplication()
      -&gt;bootComponent('com_example');
  }

  return self::$dic;
}
            </programlisting>

      <para>This code is very simple. We declare a protected static variable
      holding our component's DIC. This is initialised by the boot method
      which is called whenever the component is booted. The static method
      getContainer returns the component's DIC; if the DIC was undefined at
      this point it boots the component first.</para>

      <para>So now you can simply do:</para>

      <programlisting language="php">$exampleDIC = \Acme\Component\Example\Administrator\Extension\ExampleComponent::getContainer();</programlisting>

      <para>The component's DIC gives you access to all of the application's
      services and your component's service. Using the MVCFactory to get an
      MVC object you can be sure that it will work as intended.</para>
    </section>
  </section>

  <section xml:id="com-dispatcher">
    <title>Dispatcher</title>

    <para>As we said <link linkend="com-j3-vs-j4-mvc">when comparing the
    Joomla 3 to the Joomla 4 MVC</link>, the Dispatcher takes the place of the
    front controller (<filename>controller.php</filename>) in the legacy
    Joomla 3 MVC. In some ways it also takes the place of the entry point file
    (e.g. <filename>example.php</filename> for a component named
    <code>com_example</code>) as it's the first code which is executed when
    our component is loaded with the explicit intent of rendering
    output.</para>

    <para>Most components do not need a custom Dispatcher. The default
    Dispatcher provided by Joomla is just fine.</para>

    <para>If you do decide to create a custom Dispatcher its class name
    <emphasis role="bold">MUST</emphasis> be
    <classname>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable>\Administrator\Dispatcher\Dispatcher</classname>
    (backend),
    <classname>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable>\Site\Dispatcher\Dispatcher</classname>
    (frontend) or
    <classname>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable>\Api\Dispatcher\Dispatcher</classname>
    (API application) where
    <classname>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable></classname>
    is the namespace prefix for your component, for instance
    <classname>\Acme\Component\Example</classname>. This custom Dispatcher
    class must extend from
    <classname>\Joomla\CMS\Dispatcher\ComponentDispatcher</classname>.</para>

    <para>Typically, there are two methods you might need to customise. One is
    <code>loadLanguage</code> which loads your component's language files. You
    may have to customise that if, for example, you need to load the backend
    files in the frontend or vice versa, or if you need to load some core
    component's language files on top of yours.</para>

    <para>The other method may be the <code>dispatch()</code> method which
    figures out the view, task and controller from the input and executes the
    component.</para>

    <para>Usually, I override the <code>dispatch()</code> method to add a
    minimum PHP version check and fix up the request variables so I always
    have a view and task. The latter helps when writing Routers for components
    which have record add / edit views in the <emphasis>frontend</emphasis>.
    Such a Dispatcher would look like the following code example.</para>

    <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Site\Dispatcher;

defined('_JEXEC') or die;

class Dispatcher extends \Joomla\CMS\Dispatcher\ComponentDispatcher
{
  /**
   * The default controller (and view), if none is specified in the request.
   *
   * @var   string
   */
  protected $defaultController = 'items';

  /** @inheritdoc */
  public function dispatch()
  {
    $minPHPVersion = '7.4.0';

    if (version_compare(PHP_VERSION, $minPHPVersion, 'lt'))
    {
      throw new \RuntimeException(
        sprintf(
          'This component requires PHP %s or later.',
          $minPHPVersion
        )
      );
    }

    $this-&gt;applyViewAndController();

    parent::dispatch();
  }

  /**
   * Applies the view and controller to the input object communicated to the MVC objects.
   *
   * If we have a controller without view or just a task=controllerName.taskName we populate the view to make things
   * easier and more consistent for us to handle.
   *
   * @return  void
   */
  protected function applyViewAndController(): void
  {
    $controller = $this-&gt;input-&gt;getCmd('controller', null);
    $view       = $this-&gt;input-&gt;getCmd('view', null);
    $task       = $this-&gt;input-&gt;getCmd('task', 'default');

    if (strpos($task, '.') !== false)
    {
      // Explode the controller.task command.
      [$controller, $task] = explode('.', $task);
      $view = null;
    }

    if (empty($controller) &amp;&amp; empty($view))
    {
      $controller = $this-&gt;defaultController;
      $view       = $this-&gt;defaultController;
    }
    elseif (empty($controller) &amp;&amp; !empty($view))
    {
      $controller = $view;
    }
    elseif (!empty($controller) &amp;&amp; empty($view))
    {
      $view = $controller;
    }

    $controller = strtolower($controller);
    $view       = strtolower($view);

    $this-&gt;input-&gt;set('view', $view);
    $this-&gt;input-&gt;set('controller', $controller);
    $this-&gt;input-&gt;set('task', $task);
  }
}</programlisting>
  </section>

  <section xml:id="com-namespaces">
    <title>Namespaces and MVC</title>

    <para>Before we delve into the specifics of how Models, Views, Controllers
    and Tables work in the Joomla 4 MVC we need to talk about how they are
    <emphasis>named</emphasis>.</para>

    <section xml:id="com-namespaces-j3">
      <title>How things worked from Joomla 1.5 to 3.10</title>

      <para>In Joomla 3 the naming convention was
      <code>ComponentTypeName</code> where</para>

      <itemizedlist>
        <listitem>
          <para><code>Component</code> is the name of the component without
          the <code>com_</code> prefix and with the first letter in uppercase.
          For example, if you have <code>com_example</code> the first part of
          an MVC class name was <code>Example</code>.</para>
        </listitem>

        <listitem>
          <para><code>Type</code> is the type of the class you have, i.e. one
          of <code>Component</code>, <code>Model</code>, <code>View</code>, or
          <code>Table</code>. Again, the first letter is uppercase.</para>
        </listitem>

        <listitem>
          <para><code>Name</code> is the name of the specific MVC class with
          its first letter in uppercase, e.g. <code>Item</code>.</para>
        </listitem>
      </itemizedlist>

      <para>This conventions held true in both the front- and backend parts of
      your component. For example, both the frontend and the backend would
      have a class named ExampleControllerItem and they could not extend from
      each other. This led to a <emphasis>lot</emphasis> of code duplication.
      Code duplication is the natural enemy of <link
      xlink:href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY</link>
      (Don't Repeat Yourself) code and a source of the most egregious bugs.
      That's why this practice is mockingly called WET: Write Everything
      Twice. When you put it like that it sounds exactly as ridiculous as it
      is practicing it.</para>

      <para>As for file naming, things were pretty clear for Controllers,
      Models and Tables. The name of the file was the <code>Name</code> part
      of your class name, but in all lowercase. For example, the class
      <code>ExampleControllerItem</code> was placed in a file called
      <filename>item.php</filename>.</para>

      <para>Views were... a bit more complicated. A view has a <emphasis>view
      type</emphasis> which corresponds to the <parameter>format</parameter>
      URL parameter, the default (if not specified) being
      <option>html</option>. However, if all view classes of the
      <code>com_example</code> component for the view name <code>item</code>
      are called <code>ExampleViewItem</code> how does Joomla figure out which
      one to load for the <code>html</code>, <code>json</code>,
      <code>raw</code>, <code>feed</code> etc view types? The trick was in the
      <emphasis>file name</emphasis>. Regardless of the name of the view
      class, the file name the class was stored in was following the naming
      convention
      <filename>view.<replaceable>view_type</replaceable>.php</filename> where
      the <replaceable>view_type</replaceable> is the view type in all
      lowercase (corresponds to the URL <parameter>format</parameter>
      parameter). The HTML view class would be stored in a file called
      <filename>view.html.php</filename>. This was maddening because a. the
      file name does not include even a hint to the class name and b. view
      classes cannot extend from each other. Another case of WET.</para>

      <para>With such complicated class and file naming — not to mention one
      not always being related to the other — it was impossible to write
      anything that remotely resembled a working autoloader for component
      classes. This resulted in Joomla using some ugly static calls in its
      base controller, model, view and table classes to get the MVC object you
      wanted. Whether that worked or not depended on whether they were called
      from within the same component or if you had used other badly documented
      static calls to tell these base classes where to look for component
      classes. If you wanted to mix front- and backend classes… let's just say
      the result was not pretty.</para>

      <para>Basically, the Joomla 1.5 to 3.10 MVC class and file naming was a
      rolling Dumpster fire in the sixth ring of Hell. Yet, it was still
      better than nothing, i.e. what WordPress plugin developers have to
      contend with even to this day. It's funny how literally anything is
      better than nothing and how attached people got to what is objectively a
      bad solution which was rushed out of the door.</para>

      <para>A bit of history: The MVC in Joomla 1.5 to 3.10 was never
      considered “finished” by its lead developer, Johan Janssens. He was
      aware of its shortcomings but ran out of time improving it in 2006.
      Janssens left the project shortly after Joomla 1.5 was released. The MVC
      architecture wasn't updated significantly in subsequent versions.
      Features were still added to it, e.g. Forms support in Joomla 1.6, but
      the class and file naming remained untouched until the release of Joomla
      4 in 2020.</para>
    </section>

    <section xml:id="com-namespaces-j4">
      <title>How things work Joomla 4.0 onwards</title>

      <para>Fixing the hot mess of class and file naming in component's MVC
      was one of the priorities in Joomla 4. Having a CMS in 2020 (when Joomla
      4 was released) still use a half-finished and proven problematic
      architecture from 2006 would just not cut it.</para>

      <para>The first step was to add <link
      linkend="concepts-namespaces">namespaces</link> and make sure that the
      <link linkend="com-dirs">folder and file names</link> follow the <link
      xlink:href="https://www.php-fig.org/psr/psr-4/">PSR-4</link>
      standard.</para>

      <para>Your component's namespace prefix is declared in the XML manifest
      of the component using a new XML element under the
      <code>&lt;extension&gt;</code> root element:</para>

      <programlisting language="xml">&lt;namespace path="src"&gt;Acme\Component\Example&lt;/namespace&gt;</programlisting>

      <para>The <code>path</code> attribute tells Joomla which subdirectory of
      your extension holds the PSR-4 of your extension's PHP files. It is best
      practice to name it <filename>src</filename> but <emphasis>you don't
      have to</emphasis>. I always assume you are using
      <filename>src</filename>.</para>

      <para>The text inside the XML element,
      <code>Acme\Component\Example</code> in our example, is the namespace
      prefix you will be using. Each component has its own namespace prefix,
      which consists of 3 parts:
      <classname>\<replaceable>My</replaceable>\Component\<replaceable>ComponentName</replaceable></classname>.
      For instance (as often used throughout this book)
      <classname>\Acme\Component\Example</classname>.</para>

      <para>The 3 parts of a component namespace prefix are as follows:</para>

      <itemizedlist>
        <listitem>
          <para>The vendor namespace prefix: a valid PHP namespace, unique for
          you, your company or your project. A valid vendor namespace prefix
          can for instance be <classname>\Acme</classname>. A vendor namespace
          prefix can also have sub-namespaces, for instance:
          <classname>\Acme\Support\Tools</classname>. You are free to choose
          your own vendor namespace, however:</para>

          <itemizedlist>
            <listitem>
              <para>The vendor namespace should not start with
              <classname>\Joomla</classname>, because component namespaces
              starting withIn <classname>\Joomla</classname> are reserved for
              core components.</para>
            </listitem>

            <listitem>
              <para>The vendor namespace should not contain a sub-namespace
              starting with <classname>\Component</classname>. It is a
              reserved sub-namespace, that should only be used immediately
              AFTER the vendor namespace prefix in a component
              namespace.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>The literal string <classname>Component</classname>, with a
          capital C. You should use the <code>\Component</code> sub-namespace
          in the component namespace only once, to separate the vendor
          namespace prefix from the component's sub-namespace i.e.
          <emphasis>after</emphasis> the vendor namespace and
          <emphasis>before</emphasis> the sub-namespace with the component
          name.</para>
        </listitem>

        <listitem>
          <para>The component sub-namespace: a valid component name for Joomla
          as is used in <code>com_componentname</code>. In simple terms, it's
          the same as your component's folder name, without the
          <code>com_</code> prefix. You can optionally use camel case in your
          sub-namespace. However, you can only use lowercase in your component
          name and folder name (everywhere you have to use
          <code>com_componentname</code>). A valid component
          sub-namepsacewould for instance be <classname>Example</classname> in
          the namespace <classname>Acme\Component\Example</classname> for
          component <code>com_example</code>.</para>
        </listitem>
      </itemizedlist>

      <para>Note that this component namespace is the common namespace prefix
      for your entire component. Your component has a different namespace
      <emphasis>suffix</emphasis> for each of the three web applications in
      Joomla: frontend (site), backend (administrator) and api (the brand-new
      JSON API; this is optional).</para>

      <para>Here is how namespace prefixes work across the three Joomla
      applications, assuming a common namespace prefix
      <classname>Acme\Component\Example</classname>:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Component, frontend</emphasis>. The
          frontend classes MUST be under the namespace
          <code>\Acme\Component\Example\Site</code>. The folder
          <filename>components/com_example/src</filename> is the root of the
          <code>\Acme\Component\Example\Site</code> namespace.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Component, backend</emphasis>. The
          backend classes MUST be under the namespace
          <code>\Acme\Component\Example\Administrator</code>. The folder
          <filename>administrator/components/com_example/src</filename> is the
          root of the <code>\Acme\Component\Example\Administrator</code>
          namespace.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Component, API application</emphasis>.
          The API application classes MUST be under the namespace
          <code>\Acme\Component\Example\Api</code>. The folder
          <filename>api/components/com_example/src</filename> is the root of
          the <code>\Acme\Component\Example\Api</code> namespace.</para>
        </listitem>
      </itemizedlist>

      <para>Please note that you do not get a special namespace to use for the
      Joomla Console (CLI) application. You will be reusing the classes from
      the other three Joomla applications.</para>

      <para>Class names are different than, but not a huge departure from,
      what you had in Joomla 3.</para>

      <para>In Joomla 4 and beyond the naming convention for controllers,
      models and tables is
      <code>\<replaceable>NamespacePrefix</replaceable>\<replaceable>ApplicationType</replaceable>\<replaceable>Type</replaceable>\<replaceable>Name</replaceable><replaceable>Type</replaceable></code>
      where:</para>

      <itemizedlist>
        <listitem>
          <para><replaceable>NamespacePrefix</replaceable> is your common
          namespace prefix, e.g. <code>\Acme\Component\Example</code>.</para>
        </listitem>

        <listitem>
          <para><replaceable>ApplicationType</replaceable> is the type of the
          application part of your component i.e. one of <code>Site</code>
          (frontend), <code>Administrator</code> (backend), or
          <code>Api</code> (JSON API application).</para>
        </listitem>

        <listitem>
          <para><replaceable>Name</replaceable> is the name of the specific
          MVC class with its first letter in uppercase, e.g.
          <code>Item</code>.</para>
        </listitem>

        <listitem>
          <para><replaceable>Type</replaceable> is the type of the class you
          have, i.e. one of <code>Controller</code>, <code>Model</code>, or
          <code>Table</code>. Again, the first letter is uppercase.</para>
        </listitem>
      </itemizedlist>

      <para>All of your classes need to be placed inside the folder you have
      declared in your XML manifest as your namespace root folder, typically
      <code>src</code>. The files and folders under it follow the PSR-4 naming
      standard. Assuming that you have a component called
      <code>com_example</code>, with a namespace prefix
      <classname>Acme\Component\Example</classname> and a namespace root
      folder called <filename>src</filename>, the backend model class
      <classname>\Acme\Component\Example\Administrator\Model\ItemModel</classname>
      can be found in the file
      <filename>administrator/components/com_example/src/Model/ItemModel.php</filename>.</para>

      <para>Views have a very slightly different convention because we also
      have the <emphasis>view type</emphasis>. Their naming convention is
      <code>\<replaceable>NamespacePrefix</replaceable>\<replaceable>ApplicationType</replaceable>\View\<replaceable>Name</replaceable>\<replaceable>ViewType</replaceable></code>
      where:</para>

      <itemizedlist>
        <listitem>
          <para><replaceable>NamespacePrefix</replaceable> is your common
          component namespace prefix, e.g.
          <classname>\Acme\Component\Example</classname>.</para>
        </listitem>

        <listitem>
          <para><replaceable>ApplicationType</replaceable> is the type of the
          application part of your component i.e. one of <code>Site</code>
          (frontend), <code>Administrator</code> (backend), or
          <code>Api</code> (JSON API application).</para>
        </listitem>

        <listitem>
          <para><replaceable>Name</replaceable> is the name of the specific
          MVC class with its first letter in uppercase, e.g.
          <code>Item</code>.</para>
        </listitem>

        <listitem>
          <para><replaceable>ViewType</replaceable> corresponds to the format
          URL parameter with its first letter in uppercase, e.g.
          <code>Html</code>, <code>Json</code>, <code>Feed</code>,
          <code>Raw</code> and so on.</para>
        </listitem>
      </itemizedlist>

      <para>The HTML view class for a view called <code>item</code> of the
      hypothetical component we discussed above would have the fully qualified
      class name
      <classname>\Acme\Component\Example\Administrator\View\Item\HtmlView</classname>
      and you would find it in the file
      <filename>administrator/components/com_example/src/View/Item/HtmlView.php</filename>.</para>

      <para>Right away you can see how namespaces are benefiting us. A
      controller, model, or view in the frontend, backend and api application
      have a different FQN (<link
      xlink:href="https://www.php.net/manual/en/language.namespaces.rules.php">Fully
      Qualified Name</link>). They no longer have the same name. One can
      extend the other if we want to, we <emphasis>can</emphasis> mix front-,
      backend and api MVC objects if we need to and all of these classes can
      be autoloaded without having to use weird static calls. Cool!</para>
    </section>
  </section>

  <section xml:id="com-mvcfactory">
    <title>The MVCFactory</title>

    <para>In Joomla 3 you had to make a static call to the base MVC class
    included in Joomla itself to get an instance of an MVC object. For
    example, getting your ExampleModelItem model object you had to do
    something like the following.</para>

    <programlisting language="php">$model = \Joomla\CMS\MVC\Model\BaseDatabaseModel::getInstance('Item', 'ExampleModel');</programlisting>

    <para>If you were to do that in the frontend of the site you'd get the
    frontend <code>ExampleModelItem</code> class stored in
    <filename>components/com_example/models/item.php</filename>. If you were
    to do that in the backend of the site you'd get the backend
    <code>ExampleModelItem</code> class stored in
    <filename>administrator/components/com_example/models/item.php</filename>.
    If you did that from outside the <code>com_example</code> component, e.g.
    in a module or plugin, it would fail unless either the class was already
    loaded beforehand OR you had done something like</para>

    <programlisting language="php">\Joomla\CMS\MVC\Model\BaseDatabaseModel::addIncludePath(
  'components/com_example/models', 'ExampleModel'
);</programlisting>

    <para>Having to call a static method to get an object is bad architecture
    since the superclass where the static method lives in becomes a God Object
    — it knows way too much about how everything works in the entire CMS!
    Moreover, having the ability to auto-load classes only under certain
    circumstances, and having the object returned depend on both the
    application running under and magic configuration supplied by static
    method calls made it impossible to know what will be returned every time.
    The fact that backend and frontend classes had the exact same Fully
    Qualified Name made it impossible to double-check something didn't go
    awry. This loopy behaviour was a constant source of bugs.</para>

    <para>Joomla 4 addressed this source of endless frustration by introducing
    the MVCFactory service in the <link
    linkend="concepts-container">component's DI container</link>. The
    MVCFactory object implements the <link
    xlink:href="https://en.wikipedia.org/wiki/Factory_method_pattern">Factory
    method pattern</link> which means it can create instances of our MVC
    objects: controllers, models, views and tables.</para>

    <important>
      <para>Each MVCFactory object instance can only create MVC objects for a
      <emphasis role="bold">specific</emphasis> component! This is in stark
      contrast with the static calls in Joomla 3 which could create an MVC
      object for just about any component.</para>

      <para>This is actually a good thing! It is implementing the fundamental
      computer science principle called <link
      xlink:href="https://en.wikipedia.org/wiki/Separation_of_concerns">Separation
      of Concerns</link>. Put another way, if I get the MVCFactory object for
      <code>com_example</code> I know that it can create any MVC object I need
      for <code>com_example</code> and only that components. It won't be
      “polluted” by any other component. Every time I call an MVCFactory
      method <emphasis role="bold">I AM 100% CONFIDENT</emphasis> I am getting
      the object I asked for and expected, not something potentially random I
      have no way of checking. Therefore, the MVCFactory object solves the
      single biggest source of frustration in Joomla component development.
      Hallelujah!</para>
    </important>

    <para>When you are writing code in a Controller or Model class you can get
    your own component's MVCFactory instance using the
    <code>$this-&gt;getMVCFactory()</code> method.</para>

    <para>If you are outside a component — a module, plugin, template or a
    different component — you can <emphasis>still</emphasis> get the
    MVCFactory of any installed and enabled component on the site as we saw in
    <link linkend="com-lifetime">the lifetime of a component</link>:</para>

    <programlisting language="php">$comContentMVCFactory = \Joomla\CMS\Factory::getApplication()
  -&gt;bootComponent('com_content')
  -&gt;getMVCFactory();</programlisting>

    <tip>
      <para>Before trying to boot a component you are supposed to check the
      component is installed <emphasis>and</emphasis> enabled. You can do that
      very simply, e.g. for <code>com_content</code>, with this code</para>

      <programlisting language="php">\Joomla\CMS\Component\ComponentHelper::isEnabled('com_content')</programlisting>
    </tip>

    <para>The MVCFactory has four public methods corresponding to the MVC
    objects we can create:</para>

    <variablelist>
      <varlistentry>
        <term>createController</term>

        <listitem>
          <para>Loads and creates a controller object.</para>

          <programlisting language="php">$myController = $this-&gt;getMVCFactory()
                  -&gt;createController('Item', 'Administrator');</programlisting>

          <para>The first argument is the name of the controller. The second
          argument is the application type (<code>Site</code>,
          <code>Administrator</code>, or <code>Api</code>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>createModel</term>

        <listitem>
          <para>Loads and creates a model object.</para>

          <programlisting language="php">$myModel = $this-&gt;getMVCFactory()
             -&gt;createModel('Item', 'Administrator');</programlisting>

          <para>The first argument is the name of the model. The second
          argument is the application type (<code>Site</code>,
          <code>Administrator</code>, or <code>Api</code>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>createView</term>

        <listitem>
          <para>Loads and creates a view object.</para>

          <programlisting language="php">$myView = $this-&gt;getMVCFactory()
            -&gt;createView('Item', 'Administrator', 'Html');</programlisting>

          <para>The first argument is the name of the view. The second
          argument is the application type (<code>Site</code>,
          <code>Administrator</code>, or <code>Api</code>). The third argument
          is the view type which corresponds to the
          <parameter>format</parameter> URL parameter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>createTable</term>

        <listitem>
          <para>Loads and creates a table object.</para>

          <programlisting language="php">$myTable = $this-&gt;getMVCFactory()
             -&gt;createTable('Item', 'Administrator');</programlisting>

          <para>The first argument is the name of the table. The second
          argument is the application type (<code>Site</code>,
          <code>Administrator</code>, or <code>Api</code>).</para>

          <warning>
            <para>Joomla table classes are only defined in the backend
            (<code>Administrator</code>) of your component. Therefore your
            second argument MUST always be
            <code>'Administrator'</code>.</para>

            <para>While you could conceivably define table classes in the site
            or api parts of your component it's not recommended and you should
            not expect Joomla's core code to be able to find them. Think of
            that second argument as a “forwards compatibility” provision, in
            case Joomla ever fully supports creating tables in the site or api
            parts of your component.</para>
          </warning>
        </listitem>
      </varlistentry>
    </variablelist>

    <bridgehead>MVCFactory and Dependency Injection</bridgehead>

    <para>The MVCFactory also performs a modicum of dependency injection. It
    inspects each created MVC object and checks which interfaces it
    implements. Depending on which interfaces are implemented some basic
    objects (form factory, dispatcher, router, cache controller, database
    object) are taken from the corresponding services in the component's DI
    container and injected into the MVC object.</para>

    <para>If you want to inject additional services you will have to extend
    the MVCFactory service in your component's service provider using a custom
    MVCFactory wrapper. When registering the service extension in your
    component's <link linkend="com-services">service provider</link> you can
    push your custom service to the MVCFactory wrapper and use it in the
    overridden methods of the wrapper. We will see an example of that <link
    linkend="com-models-push-service-joomla">pushing a custom service into a
    Model</link> later in this book.</para>

    <para>While this sounds like a bit of a chore, it is actually a very clean
    architecture. If you decide to make a change in your service's
    initialisation — or swap it out with a completely different implementation
    altogether — you can do that trivially by changing one line of code in
    your service provider. No more hunting down all over your codebase for
    that elusive reference to the service you are using. This is just another
    way Dependency Injection helps you write more sustainable code.</para>
  </section>

  <section xml:id="com-models">
    <title>Models</title>

    <para>The bulk of the implementation logic for Joomla 4 MVC models is the
    same as in Joomla 3 MVC.</para>

    <para>The Model classes extend from one of the base Joomla MVC Model
    super-classes:</para>

    <variablelist>
      <varlistentry>
        <term>Joomla\CMS\MVC\Model\BaseModel</term>

        <listitem>
          <para>The most basic model you can get. It does not connect to a
          database and does not support form. This is the kind of model you
          may need to use if you have a static view in your component (e.g. a
          control panel not implemented with a core <link
          linkend="com-dashboard">Dashboard</link>), if your model deals with
          data outside of the database (e.g. processing images, talking to a
          third party API over HTTP, converting files, etc) or if it uses an
          external or third party library (e.g. in Akeeba Backup the
          BackupModel uses our Akeeba Engine backup engine library).</para>

          <para>The basic service it provide is model state management using
          the <code>getState</code>, <code>setState</code> and
          <code>populateState</code> methods.</para>

          <tip>
            <para>In a proper MVC implementation the only way the Controller
            would “talk” to a Model is by setting its state and then reading
            either the return value of the method it called or inspecting the
            Model's state.</para>

            <para>In Joomla MVC the model state is a weird beast. It is
            ‘normally’ set by reading it from the session and overriding it
            from the request parameters using the application's
            <code>getUserStateFromRequest</code> method.</para>

            <para>While this is mostly okay for simple administrator pages
            listing and editing records you may find yourself in situations
            where you need to “talk” to the model from the Controller. Instead
            of passing this information around as HTTP GET/POST parameters —
            which can be inspected and <emphasis>overridden</emphasis> by a
            curious or malicious user — I urge you to instead override the
            <code>display</code> method of your Controller and set the Model's
            state after instantiating it. This is something you will not see
            anywhere in the Joomla core code but something you SHOULD be doing
            in your more complex components to avoid embarrassing and easily
            preventable security vulnerabilities.</para>

            <para>Speaking of which, <emphasis>always</emphasis> validate the
            data type and values of your model state in your code. Writing
            secure code requires you to adopt a “trust no-one” stance against
            any data which is not hard-coded into your extension's code! Do
            not assume that the data will be safe because (you think that)
            only a Super User can access a specific view. First of all, your
            assumption may be wrong. Moreover, your Model may be used outside
            the View you have in mind, even by third party components, plugins
            and modules integrating with your extension. Trust no-one, not
            even your own assumptions!</para>
          </tip>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joomla\CMS\MVC\Model\BaseDatabaseModel</term>

        <listitem>
          <para>This is an extension to BaseModel primarily adding database
          support. You can get the applicable database object with
          <code>$this-&gt;getDbo()</code> (Joomla 4.0 or later 4.x version) or
          <code>$this-&gt;getDatabase()</code> (Joomla 4.2 and later versions,
          including 5.0 and later).</para>

          <para>Beyond that, it lets you dispatch events using the global
          Event Dispatcher you get with <code>$this-&gt;getDispatcher()</code>
          (Joomla 4.2 and later), get the Joomla user object of the currently
          logged in user with <code>$this-&gt;getCurrentUser()</code> (Joomla
          4.2 and later), and get the CacheControllerFactory to talk to
          Joomla's cache with
          <code>$this-&gt;getCacheControllerFactory()</code> (Joomla 4.2 and
          later).</para>

          <para>This is the most used type of model super-class, either having
          your models directly extend it or indirectly extend it by using one
          of its descendant classes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joomla\CMS\MVC\Model\FormModel</term>

        <listitem>
          <para>This is an extension to the BaseDatabaseModel which
          additionally implements Form handling.</para>

          <important>
            <para>This IS NOT the class you want to extend in pages which edit
            existing or create new records! What you are looking for in this
            case is Joomla\CMS\MVC\Model\AdminModel (yes, even in the
            frontend!).</para>
          </important>

          <para>This is the kind of Model you are going to use on pages which
          render a Form using an XML file for collecting information from the
          user BUT NOT for the purpose of editing or creating a record.</para>

          <para>A practical example of this is the Joomla Global Configuration
          page's model
          (<code>Joomla\Component\Config\Administrator\Model\ApplicationModel</code>)
          which does render an XML form with the Global Configuration option.
          Compare this to the article edit page's model
          (<code>Joomla\Component\Content\Administrator\Model\ArticleModel</code>)
          and the difference becomes evident right away!</para>

          <para>In your components you might want to use this type of Model in
          custom configuration pages. For example, you may have a component
          which post new articles automatically on social media. You may want
          to create different configurations for Facebook, Twitter, Reddit and
          whatnot. The page managing each of these configurations, each one
          using its own XML form file, would very likely use a Model class
          extending from <code>FormModel</code> instead of
          <code>AdminModel</code>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joomla\CMS\MVC\Model\AdminModel</term>

        <listitem>
          <para>This is an extension to the <code>FormModel</code> which is
          designed specifically for creating new and editing existing
          records.</para>

          <para>What is the difference? Whereas <code>FormModel</code> is made
          to deal with the collection of arbitrary data, the
          <code>AdminModel</code> is made to create and edit records having
          the same data shape, defined in a database table. As a result, it
          works together with a <link linkend="com-tables">Table
          object</link>. Most of its methods will be talking to the Table
          object.</para>

          <para>It also supports automatic integration with content plugins
          and implements the methods you need to save new/existing records,
          reorder records, change record associations, batch process records,
          check-in and check-out records to the database, change the publish /
          trash state, and permanently delete records. Yup, this type of Model
          basically handles nearly everything you need to manage records in
          the backend of a site <emphasis>except</emphasis> listing
          records.</para>

          <note>
            <para>I had personally found it extremely confusing that the
            <code>AdminModel</code> (and the corresponding
            <code>FormController</code>) is responsible for handling all the
            actions you see available in the toolbar of a records list page.
            When you think about architecture it does make sense. When you are
            new to Joomla you might wonder why this is not handled by
            <code>ListModel</code> (and its corresponding
            <code>AdminController</code>). This is unfortunately a case of
            “you do this just because”, not a case of using what you'd
            intuitively think is the right thing to use. I know,
            right?!</para>

            <para>You may also get confused by the fact that an
            AdminController has a ListModel whereas a FormController has an
            AdminModel. It looks like someone had a stroke trying to name
            things.</para>

            <para>Thankfully, no, nobody had a stroke — the weird naming comes
            from the fact that when forms were introduced in Joomla 1.6 we had
            to maintain backwards compatibility to Joomla 1.5, thereby causing
            a class naming mayhem. You know what are the two hardest things in
            software development? Handling dates, managing backwards
            compatibility and off-by-one errors!</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joomla\CMS\MVC\Model\ItemModel</term>

        <listitem>
          <para>This is an extension of the BaseDatabaseModel, designed to
          <emphasis>display</emphasis> a single record in the frontend.</para>

          <para>This is something you will use probably a lot in the frontend
          of your application when you want to show a single record which
          cannot be edited. Unlike the FormModel and the AdminModel, this
          Model class does not have any kind of management code for the
          records. It just displays them and that's it.</para>

          <tip>
            <para>Practically speaking, you might just end up extending your
            frontend Model from your backend Model which in turn extends from
            Joomla's AdminModel if you need to provide any kind of frontend
            administration of your component. There is no point creating two
            models to talk to the same data, one just to show it and one just
            to modify it. It also makes no sense to have your frontend Model
            extend from AdminModel and duplicate your code (WET code) when you
            can simply extend your backend model and refrain from repeating
            yourself (DRY code).</para>
          </tip>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Joomla\CMS\MVC\Model\ListModel</term>

        <listitem>
          <para>This class extends from the BaseDatabaseModel and has the
          ability to manage forms (you need them for Search Tools a.k.a. list
          filters) and, crucially, to provide pagination-aware list of records
          from a database table.</para>

          <para>You know how the main Joomla backend user interface pattern is
          a list of records? Yup, this is the Model which implements
          it.</para>

          <tip>
            <para>In the frontend of your component you will very frequently
            find yourself needing to list a bunch of items in pagination-aware
            lists. The traditional Joomla code pattern was to create a
            frontend Model which extended from BaseDatabaseModel and have the
            same code to list items copied over from the backend.</para>

            <para>Don't do that. It's WET code and I've already mentioned that
            it's the source of many a bug.</para>

            <para>What you will practically find yourself doing is extending
            the frontend Model from the backend Model. Unlike Joomla 3, this
            is now possible!</para>

            <para>You need to be acutely aware, though, that you will need to
            override the <code>populateState</code> method in the frontend
            model. By default, this method will accept any kind of user input
            for filtering the list of records which could indeed be used by a
            malicious user to display items they are not supposed to
            access!</para>

            <para>An even better approach is what I hinted to earlier.
            Override the <code>display</code> method of your Controller. In
            there, first do a <code>getState</code> on your model (to run the
            <code>populateState</code> and be done with it), then explicitly
            set the Model state using its <code>setState</code> method before
            passing it to your View object. When you do that, the state set by
            your Controller's code overrides whatever
            <code>populateState</code> did, thereby mitigating any security
            risks.</para>
          </tip>
        </listitem>
      </varlistentry>
    </variablelist>

    <section xml:id="com-models-interfaces-traits">
      <title>Interfaces and Traits</title>

      <para>In Joomla 3 each Model type tried to do everything under the sun
      and even implement features which might have nothing to do with your
      component, like tags and versioning.</para>

      <para>In Joomla 4 and later versions the default Model classes don't do
      any of that. That's a good thing because it promotes the computer
      science principle called Separation of Concerns. If you need additional
      features you will be doing a bit of <emphasis>object
      composition</emphasis>.</para>

      <para>For those with a Computer Science background, you may wonder how
      you can do object composition in a language like PHP which, unlike C for
      example, does not allow classes to inherit (extend) from multiple
      classes. The answer is by using Traits provided by Joomla.</para>

      <variablelist>
        <varlistentry>
          <term>\Joomla\CMS\Versioning\VersionableModelTrait</term>

          <listitem>
            <para>Implements support for Versions (record history).</para>

            <para>Only applicable to models extending from
            <code>AdminModel</code>. This requires the <guilabel>Behaviour -
            Versionable</guilabel> plugin to be published. The corresponding
            Table must implement the
            <code>\Joomla\CMS\Versioning\VersionableTableInterface</code>
            interface and the corresponding Controller must use the
            <code>\Joomla\CMS\Versioning\VersionableControllerTrait</code>
            trait.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>\Joomla\CMS\MVC\Model\WorkflowBehaviorTrait</term>

          <listitem>
            <para>Implements support for Workflows (prescribed steps for state
            changes in records).</para>

            <para>Only applicable to models extending from
            <code>AdminModel</code>. The model must implement the
            <code>\Joomla\CMS\MVC\Model\WorkflowModelInterface</code>
            interface.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section xml:id="com-models-push-service-joomla">
      <title>Pushing services to the Model: the Joomla Way</title>

      <note>
        <para>This way only applies to Joomla 4.3 and later. If you want your
        component to support earlier Joomla versions you will have to use the
        alternative method outlined towards the end of this section.</para>
      </note>

      <para>TODO — This section is pending the submission and acceptance of a
      Pull Request to the Joomla Project.</para>
    </section>

    <section xml:id="com-models-push-service-alt">
      <title>Pushing services to the Model: an alternative</title>

      <para>While Joomla 4.3 and later allows you to push services into the
      Model using an MVCFactory wrapper which extends the MVC service,
      necessary parts of this architecture did not exist in previous Joomla
      versions. We will have to use a slightly less “architecturally clean”
      solution.</para>

      <para>We will <emphasis role="bold">pull</emphasis> the custom service
      <emphasis role="bold">from</emphasis> the component's DIC.</para>

      <para>First, you need to make sure that you register a service provider
      in <link linkend="com-services">your component's service provider</link>
      implementation:</para>

      <programlisting language="php">$container-&gt;set(
  \Acme\Component\Example\Administrator\Service\FacebookPublish::class,
  function (Container $container) {
    return new \Acme\Component\Example\Administrator\Service\FacebookPublish();
  }
);</programlisting>

      <para>Then, you need to modify your <link
      linkend="com-extension">component's extension class section</link> as we
      saw on that section's “Getting access to the component's DIC anytime,
      anywhere” to be able to statically return the component's DI Container
      anytime, anywhere:</para>

      <programlisting language="php">protected static $dic;

public function boot(ContainerInterface $container)
{
  self::$dic = $container;
}

public static function getContainer()
{
  if (empty(self::$dic))
  {
    Factory::getApplication()
      -&gt;bootComponent('com_example');
  }

  return self::$dic;
}</programlisting>

      <para>Now your Model can simply pull the service from the Component's
      DIC in its constructor:</para>

      <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Model;

use Acme\Component\Example\Administrator\Extension\ExampleComponent;
use Acme\Component\Example\Administrator\Service\FacebookPublish;
use Joomla\CMS\Form\FormFactoryInterface;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\CMS\MVC\Model\AdminModel;

class ItemModel extends AdminModel
{
  private $fbPublish;

  public function __construct($config = [], MVCFactoryInterface $factory = null,
    FormFactoryInterface $formFactory = null)
  {
    parent::__construct($config, $factory, $formFactory);

    $exampleDIC      = ExampleComponent::getContainer();
    $this-&gt;fbPublish = $exampleDIC-&gt;get(FacebookPublish::class);
  }

  protected function getFacebookPublish(): FacebookPublish
  {
    return $this-&gt;fbPublish;
  }

  // The rest of your model's code goes here…
}</programlisting>

      <para>For completeness' sake, here are there are two (minor) downsides
      to this approach:</para>

      <itemizedlist>
        <listitem>
          <para>The Model now has a direct hard dependency on the component's
          extension class. For real world use inside Joomla this is not a big
          deal; the only recommended way to create instances of a component's
          Models is through its MVCFactory object which necessarily goes
          through the component's extension object. If you are writing Unit
          Tests, though, you can no longer isolate the Model. You will need to
          inject a dependency injection container with your custom service in
          the component's extension class.</para>
        </listitem>

        <listitem>
          <para>The extension class has a static method to fetch the DIC. If
          this is not already set up it will try to go through the global
          application object to boot the component. If you are writing Unit
          Tests this is a problem, hence why I said that you need to inject a
          DIC to your component's extension class.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section xml:id="com-controllers">
    <title>Controllers</title>

    <para>The bulk of the implementation logic for Joomla 4 MVC Controllers is
    the same as in Joomla 3 MVC.</para>

    <para>The logic is that most views are displayed using the component's
    <code>DisplayController</code> which extends from Joomla's
    <code>Joomla\CMS\MVC\Controller\BaseController</code>. You only write
    custom controllers when there's an action needed or when you need access
    to a Form object.</para>

    <tip>
      <para>The kind of MVC practiced by Joomla and described above is a bit
      “dirty”; all views share a common DisplayController for displaying. This
      is fine with Joomla's one-trick-pony components, only able to display
      one kind of information.</para>

      <para>When you have something more complex this may not be at all
      convenient. For example, a document management system might need
      separate views to display nested categories, available items (including
      the actual <emphasis>downloading</emphasis> part!) and uploading items,
      as well as viewing, adding and managing comments per document. In these
      cases it's typically much more efficient to have a separate controller
      per view. In components like that each view consists of a Controller,
      Model and View class (an MVC triad) which is more in line with how the
      normative MVC coding pattern is meant to work. This is perfectly
      possible in Joomla <emphasis>as long as you have a custom
      Dispatcher</emphasis>. You can see how I am doing that <link
      xlink:href="https://github.com/akeeba/release-system/blob/development/component/backend/src/Dispatcher/Dispatcher.php">in
      the Dispatcher of Akeeba Release System</link>, the software downloads
      management software used by Joomla's official Downloads site.</para>
    </tip>

    <para>The Controller classes extend from one of the base Joomla MVC
    Controller super-classes:</para>

    <variablelist>
      <varlistentry>
        <term>Joomla\CMS\MVC\Controller\BaseController</term>

        <listitem>
          <para>The most basic controller you can get. It is mainly used to
          power the <code>DisplayController</code> of the component or
          whenever you want to create custom controllers to display stuff and
          perform non-administrative actions (e.g. in the frontend).</para>

          <warning>
            <para>Heads up! In Joomla 3 the default display controller was in
            the root of the component as the file
            <filename>controller.php</filename> e.g.
            <filename>administrator/components/com_example/controller.php</filename>.
            This is no longer the case in Joomla 4 and later. All controllers
            are under the <filename>src/Controller</filename> folder and the
            default controller is named <code>DisplayController</code> which
            means that in the above example it would be located in
            <filename>administrator/components/com_example/srs/Controller/DisplayController.php</filename>.</para>

            <para>In Joomla 4 and later the <code>DisplayController</code> is
            mostly empty except for a line like this:</para>

            <programlisting language="php">protected $default_view = 'foobar';</programlisting>

            <para>This is the name of the “default view”. That's the view
            which will be displayed if the <parameter>view</parameter> URL
            parameter is not provided in the request.</para>
          </warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\Controller\AdminController</term>

        <listitem>
          <para>This is an extension to BaseController. It is meant for
          displaying list views in the backend of your site, e.g. a list of
          articles.</para>

          <tip>
            <para>This is the controller you will be typically using for
            controllers whose name is <emphasis role="bold">plural</emphasis>
            such as
            <code>\Acme\Component\Example\Administrator\Controller\ItemsController</code>.
            Since this is the Items controller and “items” is plural it gives
            us a hint that it will be displaying multiple items which, in the
            Joomla backend, is very likely to be a list.</para>

            <para>A mnemonic way to remember this is PASiFIC (yes, with the
            misspelling and all) "Plural Admin Singular Form Identifies the
            Controller".</para>
          </tip>

          <para>It also handles <emphasis role="bold">some</emphasis> of the
          admin tasks you will have to perform on records in a Joomla list
          view: publish, unpulish, archive, trash, report, orderup, orderdown,
          delete, reorder, saveorder, checkin, checkout, saveOrderAjax and
          runTransition. Everything else has to be handled by a singular named
          Controller which extends FormController. Yes, that's confusing and
          yes, it's the source of many bugs — but that's the same as Joomla 3
          and earlier so at least it's <emphasis>consistently
          confusing</emphasis>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\Controller\FormController</term>

        <listitem>
          <para>This is an extension to the BaseController which additionally
          implements Form handling. This is meant to be used in views which
          add or edit a database record. Additionally, it will be used in
          views which handle an XML Form e.g. a configuration page.</para>

          <tip>
            <para>This is the controller you will be typically using for
            controllers whose name is <emphasis
            role="bold">singular</emphasis> such as
            <code>\Acme\Component\Example\Administrator\Controller\ItemController</code>.
            Since this is the Item controller and “item” is singular it gives
            us a hint that it will be displaying a single item which, in the
            Joomla backend, is very likely to be an add / edit record
            page.</para>

            <para>In the frontend of the site you may have <emphasis
            role="bold">two</emphasis> controllers for the same data type. One
            DisplayController extending from BaseController to display the
            item and one singular name controller extending from
            FormController to add or edit an item. It <emphasis>is</emphasis>
            possible to have a single controller, extending from
            FormController. You see, FormController itself extends from
            BaseController which has the display method which is used to
            display stuff, i.e. it already contains the functionality of the
            typical DisplayController.</para>
          </tip>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\Controller\ApiController</term>

        <listitem>
          <para>This is a very special kind of controller which is only used
          in the <link linkend="com-api">JSON API application part of your
          component</link> e.g. the code under
          <filename>api/components/com_example</filename>.</para>

          <para>This type of controller does not have a direct equivalent in
          the other controllers. It can do everything. Produce a list of
          records, return a single record, create a new record and modify or
          delete an existing record.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <section xml:id="com-controllers-basic-services">
      <title>Basic services in your Controller</title>

      <para>A Controller object created by Joomla has a few basic services. In
      the olden days before Joomla 4 we had to use static methods in
      <code>\Joomla\CMS\Factory</code> (formerly <code>JFactory</code>) or the
      base MVC objects themselves to get access to these services. You are no
      longer supposed to do that, you are supposed to use the services
      provided in the Controller object itself.</para>

      <bridgehead>Application</bridgehead>

      <para>In Joomla 3 and earlier we would get the currently active
      application object through
      <code>\Joomla\CMS\Factory::getApplication()</code>. Do NOT do
      that.</para>

      <para>In Joomla 4 and later you can get the currently active application
      object through <code>$this-&gt;app</code>.</para>

      <para>Please remember that the application you are getting is not
      necessarily a <code>SiteApplication</code> or
      <code>AdministratorApplication</code>. It may very well be an
      <code>ApiApplication</code> (JSON API), a
      <code>ConsoleApplication</code> (Joomla CLI app) or even a custom
      application extending from
      <code>\Joomla\CMS\Application\CMSApplication</code>.</para>

      <bridgehead>Dispatcher</bridgehead>

      <para>In Joomla 3 and earlier you'd run plugin events by doing something
      like this:</para>

      <programlisting language="php">$results = \Joomla\CMS\Factory::getApplication()
                -&gt;triggerEvent('onSomething', [$param1, $param2]);</programlisting>

      <para>In Joomla 4 and later there are two ways to call plugin
      events.</para>

      <para>The first method is the legacy method, going through the
      application's <code>triggerEvent</code> method, which is discouraged and
      will eventually go away.</para>

      <programlisting language="php">$results = $this-&gt;app-&gt;triggerEvent('onSomething', [$param1, $param2]);</programlisting>

      <para>The second and recommended method is going through the Joomla
      events dispatcher and using real events.</para>

      <programlisting language="php">$event = new \Joomla\Event\Event('onSomething', [$param1, $param2]);
$this-&gt;getDispatcher()-&gt;dispatch($event-&gt;getName(), $event);
$results = $event-&gt;getArgument('result', []);</programlisting>

      <para>While this looks a bit more complicated it has some
      benefits.</para>

      <para>Using Events to access plugins means that you get access to a
      <link linkend="plg-concrete-events">concrete event object</link>. All
      core Joomla events will correspond to concrete event objects in Joomla
      5.0, meaning that you will be able to add typehinting and have your IDE
      (e.g. phpStorm, Visual Studio Code, NetBeans, Eclipse, ...)
      auto-complete the argument names when manipulating an event.</para>

      <para>The real Events implemented in Joomla 4 and later, unlike plain
      old plugin handlers we had in Joomla 1.0 to 3.10, can prevent some of
      their arguments to be modified, prescribe exactly
      <emphasis>what</emphasis> can be modified and even allow plugins to stop
      the processing of an event when we reach a point that further processing
      is unnecessary. If you slowly move from just using custom event names to
      concrete event classes you can implement far more complex features in
      your code with much less code — believe me, I've been there and done
      that! Event handling is one of those fundamental things which you are
      <emphasis>really</emphasis> upset it's changed but once you start
      getting the idea of how the new system works you start wondering how you
      could have ever written software without it.</para>

      <bridgehead>Input</bridgehead>

      <para>Back in the olden days we'd get the user's input by doing one of
      these (the more of these you remember the older you are — some date back
      to the early 00s!):</para>

      <programlisting language="php">// Joomla 1.0
$foo = \JRequest::getCmd('foo');
// Joomla 1.5
$input = new \Joomla\CMS\Input\Input();
$foo = $input-&gt;getCmd('foo');
// Joomla 1.6
$foo = Joomla\CMS\Factory::getApplication()-&gt;input-&gt;getCmd('foo');</programlisting>

      <para>This had always been a bad idea because our Controller had to
      <emphasis>know</emphasis> about the global application object and its
      request variables.</para>

      <para>Since Joomla 3.0 the Controller object has an <code>input</code>
      property which holds its own <code>\Joomla\CMS\Input\Input</code>
      object. In Joomla 3 this was typically just the application's input
      object unless you were manually constructing a controller (with a lot of
      effort).</para>

      <para>In Joomla 4.0 and later the input property contains its own
      \Joomla\CMS\Input\Input object <emphasis>which comes from the DI
      Container of the component</emphasis>. Remember that when booting a
      component we get access to its <link linkend="com-extension">component
      extension object</link> which has access to the component's <link
      linkend="concepts-container">DI Container</link>. This of course means
      that we can add <link linkend="com-extension-dic-proxy">a method to that
      object to access the DI Container</link> and set a custom input object,
      thereby implementing HMVC very easily — something that Joomla core
      maintainers didn't think was possible with the core architecture a few
      years ago! This means that whenever we want to create a module which
      displays the same information an existing view of our component already
      does, albeit in a slightly different format, all we need to do is create
      a new view template or layout and use HMVC, without having to rewrite
      our business logic in the module. We can write less code to do more.
      That's awesome!</para>

      <para>That is (one of the many reasons) why you should
      <emphasis>always</emphasis> be accessing the input as
      <code>$this-&gt;input</code> in your controllers. Now you know.</para>

      <bridgehead>MVCFactory</bridgehead>

      <para>Back in Joomla 1.0 to 3.10 creating an MVC object such as a Model,
      View, Table, or even another Controller from inside our Controller
      required calling static methods in the base MVC objects or proxy methods
      in the controller, like so:</para>

      <programlisting language="php">$someController = \Joomla\CMS\MVC\Controller\BaseController::getInstance('Some');
$someModel = \Joomla\CMS\MVC\Model\BaseDatabaseModel::getInstance('Some', 'ExampleModel');
// or
$someModel = $this-&gt;createModel('Some', 'ExampleModel');
$someView = $this-&gt;createView('Some', 'ExampleView', 'Html');
$someTable = \Joomla\CMS\Table\Table::getInstance('Some', 'ExampleTable');</programlisting>

      <para>There are two things which strike us as suboptimal:</para>

      <itemizedlist>
        <listitem>
          <para>There is no consistency in how you create MVC objects. Some
          are static calls, some are method calls to proxy functions.</para>
        </listitem>

        <listitem>
          <para>There is no consistency in the arguments you provide. Creating
          a controller only needs its name (and requires the magic
          configuration array key <code>base_path</code> if you want to get a
          controller from a component other than the current one), creating
          anything else requires us to give it the prefix of the MVC class
          name (not just the component name).</para>
        </listitem>
      </itemizedlist>

      <para>This is what we'd call “sanity came here to die”.</para>

      <para>Joomla 3.10 introduced the MVCFactory for creating models, views
      and tables and Joomla 4.0 extended it by also letting it create
      controllers. See how easier and more consistent everything is
      now:</para>

      <programlisting language="php">// Only on Joomla 4.0 and later
$someController = $this-&gt;getMVCFactory()-&gt;createController('Some', 'Administrator');
// Joomla 3.10 and later
$someModel = $this-&gt;getMVCFactory()-&gt;createModel('Some', 'Administrator');
$someView = $this-&gt;getMVCFactory()-&gt;createView('Some', 'Administrator', 'Html');
$someTable = $this-&gt;getMVCFactory()-&gt;createTable('Some', 'Administrator');
// Inside the Controller I can still do this (4.0 and later):
$someModel = $this-&gt;getModel('Some', 'Administrator');
$someView = $this-&gt;getView('Some', 'Administrator', 'Html');</programlisting>

      <para>First of all, we see that creating MVC objects is now very
      consistent and easier.</para>

      <para>Second, we notice that the <code>$prefix</code> argument is no
      longer something component-specific (such as <code>ExampleModel</code>)
      but simply the side of the application (Site, Administrator or Api) that
      we want to get the MVC object from.</para>

      <note>
        <para>Tables are only available in the Administrator side of the
        application. While you can theoretically define different Table
        classes in the frontend (Site) or JSON API (Api) side it's not a good
        idea as you will very likely run into issues where the “wrong” table
        class is being used. As a result, it's advisable to always call
        <code>createTable</code> with two parameters and set the second
        parameter to <option>Administrator</option>).</para>
      </note>

      <para>Legacy Joomla 3 components still work despite the apparent
      backwards compatibility (b/c) break in the <code>getModel</code> and
      <code>getView</code> methods. Why is that? Well, it's because Joomla 4
      uses the <code>\Joomla\CMS\MVC\Factory\LegacyFactory</code> instead of
      <code>\Joomla\CMS\MVC\Factory\MVCFactory</code> for these components.
      The LegacyFactory is aware of the b/c break and acts accordingly so you,
      the extensions developer, do not suffer. This is possible because each
      component has its own DI Container. So that's another way how using a DI
      Container allowed Joomla to create an updated, richer MVC API without
      breaking backwards compatibility with Joomla 3 — at least until Joomla
      6.0. Neat, huh?</para>

      <para>As a developer, you should remember this when you are inside a
      Controller writing code:</para>

      <itemizedlist>
        <listitem>
          <para>If you want to get a Model or View use the controller's
          <code>getModel</code> and <code>getView</code> methods.</para>
        </listitem>

        <listitem>
          <para>If you want to get another <code>Controller</code> or a
          <code>Table</code> do not instantiate them directly! Always go
          through the MVCFactory.</para>
        </listitem>

        <listitem>
          <para>The second argument to all these methods is the application
          side you are getting an object from. Leave it empty to use the
          <emphasis>current</emphasis> application side or pass an explicit
          value. If you leave it empty keep in mind that, for example, your
          backend controller may be running in the frontend. In this case, do
          you <emphasis>really</emphasis> want to get the frontend
          model?</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section xml:id="com-views">
    <title>Views</title>

    <para>Views, in Joomla 3, referred to two different things: the View
    classes and the view templates. In fact, the view templates were placed in
    a <code>tmpl</code> folder under each View's folder which was a bad idea:
    you had the output rendering in a subdirectory of the business logic,
    making it hard to discern when one ends and the other begins.</para>

    <para>In Joomla 4 there is a separation of these two very different types
    of code. The view classes (which we will call Views) are placed in the
    <filename>src/View</filename> folder with one subdirectory for each view
    in <code>Uppercasefirst</code> format. The view templates are placed in
    the <filename>tmpl</filename> folder in your component's folder with one
    subdirectory for each view they correspond to in <code>lowercase</code>
    format.</para>

    <warning>
      <para><emphasis role="bold">Folder and file name case
      matters</emphasis>. You may not notice it when developing on a Windows
      or macOS machine with a case-insensitive filesystem but you will
      <emphasis>definitely</emphasis> suffer if you mix it up when deploying
      your component on a Linux-based server where the filesystem is virtually
      guaranteed to be case-sensitive.</para>

      <para>Let's say you have a view which is called Foobar.</para>

      <para>Your HTML View class file path relative to your component's root
      MUST be <filename>src/View/Foobar/HtmlView.php</filename>. It can NOT be
      <filename>src/View/FooBar/HtmlView.php</filename> (mixed case in the
      subdirectory) or <filename>src/View/Foobar/HTMLVIEW.php</filename>
      (wrong case for the filename)!</para>

      <para>Your view <filename>default.php</filename> view template file path
      relative to your component's root MUST be
      <filename>tmpl/foobar/default.php</filename>. It cannot be
      <filename>tmpl/Foobar/default.php</filename> (wrong case for the
      subdirectory)!</para>

      <para>Knowing this will save you hours of “fun” hitting your head
      against a brick wall, wondering why it works on your computer but not on
      your server.</para>
    </warning>

    <para>The bulk of the implementation logic for Joomla 4 MVC Views is the
    same as in Joomla 3 MVC.</para>

    <para>The View classes extend from one of the base Joomla MVC View
    super-classes:</para>

    <variablelist>
      <varlistentry>
        <term>\Joomla\CMS\MVC\View\AbstractView</term>

        <listitem>
          <para>This is the base class all views extend from. You will have to
          implement the <code>display</code> method yourself.</para>

          <para>It is very rare that you are going to extend from this view.
          Typically, this is something you will do when you are rendering a
          non-HTML document, without using a view template file. Do note that
          if you are outputting JSON you may want to use
          <code>\Joomla\CMS\MVC\View\JsonView</code> instead.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\HtmlView</term>

        <listitem>
          <para>This is the most common view type, used whenever you want to
          display HTML output in the front- or backend.</para>

          <note>
            <para>Even though Joomla defines the
            <code>\Joomla\CMS\MVC\View\ListView</code> class for administrator
            list views and <code>\Joomla\CMS\MVC\View\FormView</code> for
            add/edit views, these view classes are no longer used in Joomla 4.
            Both types of pages use the HtmlView instead. As a result, the two
            more specialised view types will not be mentioned again in this
            book.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\JsonView</term>

        <listitem>
          <para>This view type is used to output a JSON document. You set its
          <code>_output</code> property and that's all there is to it. This is
          rarely used on its own.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\JsonApiView</term>

        <listitem>
          <para>This view type is used exclusively in the Api (JSON API)
          application. It's used to output data from the JSON API in JSON
          format (what else?).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\CategoriesView</term>

        <listitem>
          <para>This view type is used in the frontend (site) application to
          display a list of categories. You are supposed to use this if you
          are using Joomla's core categories in your component.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\CategoryView</term>

        <listitem>
          <para>This view type is used in the frontend (site) application to
          display a single category, typically with a list of its
          subcategories and items. You are supposed to use this if you are
          using Joomla's core categories in your component.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\MVC\View\CategoryFeedView</term>

        <listitem>
          <para>This view type is used in the frontend (site) application to
          display an RSS / Atom feed of a category's objects. You are supposed
          to use this if you are using Joomla's core categories in your
          component.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Since Joomla 4.2.0 you can use
    <code>$this-&gt;getCurrentUser()</code> in a view to get the Joomla User
    object for the currently logged in user.</para>

    <para>Since Joomla 4.0.0 you can get the Joomla event dispatcher with
    <code>$this-&gt;getDispatcher()</code> to run plugin events as explained
    <link linkend="com-controllers-basic-services">in the Controller
    documentation</link>.</para>
  </section>

  <section xml:id="com-tables">
    <title>Tables</title>

    <para>Tables, or rather Table classes, in Joomla's MVC are an abstraction
    to a row of an actual database table. They are used internally by Models
    to create new records, modify existing records and delete old records.
    It's not exactly an <link
    xlink:href="https://en.wikipedia.org/wiki/Active_record_pattern">Active
    Record</link> pattern as it does not really participate in the R (Read) of
    the <link
    xlink:href="https://en.wikipedia.org/wiki/Create,_read,_update_and_delete">CRUD</link>
    operations — Joomla's models query the database directly for listing
    multiple records and returning a single record. It also does not handle
    relationships. Like, at all.</para>

    <para>The logic of how Table classes work has not changed between Joomla 3
    and 4. They are namespaced and they have the familiar superclasses they
    extend from:</para>

    <variablelist>
      <varlistentry>
        <term>\Joomla\CMS\Table\Table</term>

        <listitem>
          <para>A plain old record in a database table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>\Joomla\CMS\Table\Nested</term>

        <listitem>
          <para>A record in a database table which supports <link
          xlink:href="https://en.wikipedia.org/wiki/Nested_set_model">Nested
          Sets</link> (think how categories work, where categories can be
          placed under other categories and so on).</para>

          <para>The table MUST have the following columns:</para>

          <itemizedlist>
            <listitem>
              <para><code>parent_id</code>. The primary key of the parent
              node. Provides adjacency list data for nodes.</para>
            </listitem>

            <listitem>
              <para><code>level</code>. The depth level of the node in the
              tree.</para>
            </listitem>

            <listitem>
              <para><code>lft</code>. The left value of the node for managing
              its placement in the nested sets tree.</para>
            </listitem>

            <listitem>
              <para><code>rgt</code>. The right value of the node for managing
              its placement in the nested sets tree.</para>
            </listitem>

            <listitem>
              <para><code>alias</code>. The alias of this node used to
              construct the full text path, forward-slash delimited.</para>
            </listitem>
          </itemizedlist>

          <note>
            <para>Nested Sets are very slow when you need to add, remove, and
            reorder records. It's not necessary to use a Nested table to
            create a nested structure. In some use cases where writing is very
            common and the number of items in each nested structure rather
            limited (e.g. nested comments) it may actually be easier to only
            store the parent ID of each node and calculate the tree structure
            in PHP code. The read performance is comparable within a few dozen
            milliseconds but the write performance can be over 100 times(!!!)
            faster when you have more than a couple thousand records.</para>

            <para>On that note, do remember that Joomla uses a Nested table
            for the <database>#__assets</database> records. Everything that
            has its own permissions such as categories, articles, banners,
            contacts, extensions, custom data types you add with an asset ID,
            etc also has a record in that table. That's why as a site grows in
            size operations against these records become increasingly
            slow.</para>

            <para>Unfortunately, this cannot be (easily) solved in Joomla;
            nested assets are a cornerstone of Joomla access control since
            version 1.6. The only real solution would be using a graph
            database which is impractical; neither MySQL nor PostgreSQL, the
            two database server technologies supported by Joomla and widely
            found on commercial hosting, have graph features (they are
            relational databases a.k.a. <link
            xlink:href="https://en.wikipedia.org/wiki/Relational_database#RDBMS">RDBMS</link>).</para>

            <para>So, if you find yourself in a situation where you need
            nested sets but can't afford the performance hit after adding
            thousands or millions of records and calculating the tree in
            memory using PHP code is impractical (and cannot be cached in a
            sensible manner) ask yourself: am I actually developing for the
            right database server and platform? Not all software can be
            written for Joomla and MySQL / PostgreSQL and that's alright. We
            are software engineers; our job is to find the right tool for the
            job and use it in the most efficient way possible to make
            something new and functional.</para>
          </note>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The rest of this section is mostly tips and tricks for using Tables
    the way Joomla intended — and even more efficiently!</para>

    <section xml:id="com-tables-get-object">
      <title>Getting the table object</title>

      <para>As noted in the <link linkend="com-mvcfactory">MVCFactory</link>
      section, you are no longer meant to instantiate Table objects using
      static method calls. You are meant to go through MVCFactory's
      <code>createTable</code> method.</para>

      <para>In the olden days we'd do something like this:</para>

      <programlisting language="php">// Returns the Item table from com_example (ExampleTableItem)
$table = \Joomla\CMS\Table\Table::getInstance('Item', 'ExampleTable');</programlisting>

      <para>While this still works for old components written with the Joomla
      3 MVC, it's part of the backwards compatibility with legacy component
      code and will eventually be removed. In fact, the
      <emphasis>only</emphasis> time you are supposed to use this in Joomla 4
      is when interfacing an old component which has not been migrated to the
      Joomla 4 architecture yet.</para>

      <para>For components based on the Joomla 4+ MVC this won't work at all!
      You need to go through the MVCFactory of the extension.</para>

      <para>If you are inside a Controller or Model and need to get a Table
      object instance for a Table class which belongs <emphasis>to your own
      component</emphasis> you must do:</para>

      <programlisting language="php">/**
 * Gets a NEW table object for the Item table in the Administrator section of the component, e.g.
 * \Acme\Component\Example\Administrator\Table\ItemTable
 */
$table = $this-&gt;getMVCFactory()-&gt;createTable('Item', 'Administrator');</programlisting>

      <para>In any other case you will need to boot the component through the
      application object to get its MVCFactory to create the table instance.
      For example:</para>

      <programlisting language="php">// It's best to have the application object injected to your code instead of using this...
$app = \Joomla\CMS\Factory::getApplication();
// Get the table
$table = $app-&gt;bootComponent('com_example')
  -&gt;getMVCFactory()
  -&gt;createTable('Item', 'Administrator');</programlisting>

      <para>Going through the MVCFactory makes sure that the table is
      constructed correctly. Remember, as we saw <link
      linkend="com-models-push-service-joomla">in the Model section</link>,
      you can push custom services into any MVC object — including Tables —
      through a custom MVCFactory decorator. This means that the only forwards
      compatible method of getting a Table object which will always work is
      going through the MVCFactory of its component.</para>
    </section>

    <section xml:id="com-tables-check">
      <title>Customising the validation</title>

      <para>One of the many jobs of a Table object is to validate the data
      before it's written to the database. This is done in its
      <code>check()</code> method.</para>

      <para>You can override that method in your custom Table classes to add
      custom validation. At the very least you should validate the data type
      and that the data is within an accepted range of values. The latter is
      domain-specific, i.e. you need to know how your database table and
      component work to write that code. That's why Joomla doesn't offer much
      in the way of automatic data validation.</para>
    </section>

    <section xml:id="com-tables-events">
      <title>Using plugin events</title>

      <para>Table classes can call plugin events. For example, Joomla's
      default <code>Table::check()</code> implementation goes through the
      <code>onTableCheck</code> plugin event to let plugins perform additional
      data validation before data is written to the database.</para>

      <para>The Table superclasses offer a <code>getDispatcher()</code> method
      to get a reference to Joomla's Events Dispatcher object. As we noted in
      the <link linkend="com-controllers-basic-services">Controllers</link>
      section this is the preferred way to use plugins in Joomla 4 and
      beyond.</para>
    </section>

    <section xml:id="com-tables-docblocks">
      <title>Add type hints with phpDoc DocBlocks and @property</title>

      <para>The Table classes do NOT declare concrete public properties for
      most of the database table columns. Instead, they use implied public
      properties — and eventually the magic <code>__get()</code> and
      <code>__set()</code> PHP methods as PHP 9 will remove support for
      implied public properties in objects which do not extend directly from
      <code>\stdClass</code>.</para>

      <para>This means that when you get a Table object and type-hint it
      correctly, like the example below, your IDE will not offer any
      auto-completion suggestions or type hints for the database table columns
      supported by your table class.</para>

      <programlisting language="php">/** @var \Acme\Component\Example\Administrator\Table\ItemTable **/
$table = $this-&gt;getMVCFactory()-&gt;createTable('Item', 'Administrator');</programlisting>

      <para>I find this annoying. The whole reason we're using an IDE is so we
      don't have to remember a large number of little things, like how the
      table columns are named in every table of every table the core CMS or
      our component is using.</para>

      <para>Luckily, this is trivial to fix.</para>

      <para>Given the following table definition:</para>

      <programlisting language="mysql">CREATE TABLE IF NOT EXISTS `#__example_items` (
  `id`          bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `catid`       bigint(20)          NOT NULL,
  `fromname`    varchar(255)        NOT NULL,
  `fromemail`   varchar(255)        NOT NULL DEFAULT '',
  `subject`     varchar(255)        NOT NULL DEFAULT '',
  `body`        mediumtext          NOT NULL,
  `enabled`     tinyint(3)          NOT NULL DEFAULT 1,
  `token`       char(32)                     DEFAULT NULL,
  `created_on`  datetime            NULL     DEFAULT NULL,
  `created_by`  bigint(20)          NOT NULL DEFAULT '0',
  `modified_on` datetime            NULL     DEFAULT NULL,
  `modified_by` bigint(20)          NOT NULL DEFAULT '0',
  `locked_on`   datetime            NULL     DEFAULT NULL,
  `locked_by`   bigint(20)          NOT NULL DEFAULT '0',
  PRIMARY KEY (`id`)
) ENGINE = InnoDB
  DEFAULT COLLATE = utf8mb4_unicode_ci;</programlisting>

      <para>You can add the following phpDoc DocBlock at the top of your
      class:</para>

      <programlisting language="php">/**
 * @property int    $id            The primary key
 * @property int    $catid         The category ID, foreign key to #__categories
 * @property string $fromname      Name of the sender
 * @property string $fromemail     Email address of the sender
 * @property string $subject       Subject line of this contact item
 * @property string $body          Body text of this contact item
 * @property int    $enabled       Is it published?
 * @property string $token         Reply token
 * @property string $created_on    Date and time the record was created
 * @property int    $created_by    ID of the user who created the record
 * @property string $modified_on   Date and time the record was last modified
 * @property int    $modified_by   ID of the user who last modified the record
 * @property string $locked_on     Date and time the record was locked
 * @property int    $locked_by     ID of the user who locked the record
*/</programlisting>

      <para>Now you get full auto-completion, type hinting and inline
      documentation for your table columns. You're welcome!</para>
    </section>

    <section xml:id="com-tables-relations">
      <title>Basic relation management with getters and setters</title>

      <para>As noted earlier in this section, Joomla does not really offer a
      full implementation of the Active Record pattern — at least, not yet.
      One of the biggest omissions is relationships.</para>

      <para>Let's say that we have a helpdesk ticket system. Each support
      ticket has one or more posts. Conversely, each post has exactly one
      ticket. Posts and tickets are database tables with corresponding Table
      classes. I actually wrote such a component and found myself too often
      having to get the ticket a post belongs to, usually many times within
      the same request. Sure I can instantiate a TicketTable object and have
      it load the data off the database but if I'm doing that several times in
      a request it's slow and unhelpful. So, how about we “upgrade” our
      PostTable to return our ticket object? It's quite easy, really!</para>

      <programlisting language="php">&lt;?php

use Acme\Component\Example\Administrator\Table\TicketTable;

class PostTable extends \Joomla\CMS\Table\Table
{
  /**
   * Ticket this post belongs to
   *
   * @var   TicketTable|null
   */
  private $ticket;

  /**
   * Get the ticket this post belongs to
   *
   * @return  TicketTable|null
   */
  public function getTicket(): ?TicketTable
  {
    if (is_null($this-&gt;ticket))
    {
      $this-&gt;ticket = new TicketTable($this-&gt;getDbo(), $this-&gt;getDispatcher());

      if ($this-&gt;ticket-&gt;load($this-&gt;ticket_id) === false)
      {
        throw new RuntimeException('There is no such ticket');
      }
    }

    return $this-&gt;ticket;
  }

  /**
   * Set the ticket this post belongs to.
   *
   * @param   TicketTable|null  $ticket  The ticket to set. NULL to make ATS reload the ticket on the next getTicket()
   *                                     method call.
   * @param   bool              $force   True to reset $this-&gt;ticket_id to the $ticket ID (or NULL, if no ticket).
   *
   * @return  self
   */
  public function setTicket(?TicketTable $ticket, bool $force = false): self
  {
    $this-&gt;ticket = $ticket;

    if ($force)
    {
      $this-&gt;ticket_id = empty($ticket) ? null : $ticket-&gt;getId();

      return $this;
    }

    if (empty($ticket) &amp;&amp; $this-&gt;ticket-&gt;getId() != $this-&gt;ticket_id)
    {
      throw new InvalidArgumentException('Ticket ID does not correspond to the loaded post');
    }

    return $this;
  }

  /**
   * Remember to remove the loaded relationship when resetting the table.
   */
  public function reset()
  {
    $this-&gt;ticket = null;

    parent::reset();
  }
}</programlisting>

      <note>
        <para>I am instantiating the TicketTable directly because, in this
        case, I know I can safely do so. If my TicketTable had dependencies on
        other tables I should be going through the MVCFactory. I decided to
        keep it simple here because there's already a lot going on.</para>
      </note>

      <para>The idea can be broken down in the following steps:</para>

      <itemizedlist>
        <listitem>
          <para>Create a private property to hold our related object, in this
          case the ticket the post belongs to.</para>
        </listitem>

        <listitem>
          <para>Reset that property back to NULL in the <code>reset()</code>
          method.</para>
        </listitem>

        <listitem>
          <para>Create a setter which sets the relationship <emphasis>if and
          only if</emphasis> the TicketTable object we're passing matches the
          post table's <code>ticket_id</code> column value. The setter is
          optional; it makes it easier for us when creating both a new post
          and a new ticket i.e. when a client submits a new helpdesk
          item.</para>
        </listitem>

        <listitem>
          <para>Create a getter which returns the already saved relationship
          object. If none is specified, we load it from the database.</para>
        </listitem>
      </itemizedlist>

      <para>This is very naive, late-bound relationship handling (lazy
      loading) but it's better than nothing.</para>

      <para>If you'd like to do eager relationship loading (when loading a big
      list of posts) you'd have to implement it yourself. For starters, you'd
      need something like that in your PostTable:</para>

      <programlisting language="php">/**
 * @param   self[]  $postTables
 */
public function eagerLoad(array &amp;$postTables): void
{
  // Get the unique ticket IDs
  $ticketIDs = array_map(
    function (PostTable $x) {
      return $x-&gt;ticket_id;
    },
    $postTables
  );
  $ticketIDs = array_unique($ticketIDs);

  // Get the raw ticket data, keyed by ticket ID
  $db = $this-&gt;getDbo();
  $query = $db-&gt;getQuery(true)
    -&gt;select('*')
    -&gt;from('#__example_tickets')
    -&gt;whereIn($db-&gt;quoteName('id'), $ticketIDs);
  $tickets = $db-&gt;setQuery($query)-&gt;loadObjectList('id') ?: [];

  // Convert the raw ticket data into TicketTable objects
  $tickets = array_map(
    function (object $rawData): TicketTable
    {
      $ticket = new TicketTable($this-&gt;getDbo(), $this-&gt;getDispatcher());
      $ticket-&gt;bind($rawData);

      return $ticket;
    },
    $tickets
  );

  // Set the TicketTable objects to each PostTable object
  foreach ($postTables as $postTable)
  {
    $postTable-&gt;setTicket($tickets[$postTable-&gt;ticket_id]);
  }
}            </programlisting>

      <para>Now, whenever you write code which returns an array of PostTable
      objects just run the resulting through that method and it set the
      related TicketObject instances to each member of the array of PostTable
      objects.</para>

      <para>Why do eager loading? With eager loading you only need 2 queries:
      one to get the list of posts data, one to get the list of tickets data.
      With lazy loading you'd need N + 1 database queries: one to get the list
      of posts data, one per post (N queries in total) to get each post's
      ticket data.</para>

      <para>Eager loading only makes sense if you are going to process a large
      number of records all at once and you are definitely going to need
      access to their related objects.</para>
    </section>

    <section xml:id="com-tables-assets">
      <title>Asset management</title>

      <para>In some cases you want your database records to have a special set
      of permissions which can override those set for the entire component in
      its Options. This is especially important if you are using the Joomla
      Categories, in which case your items may belong to a category, which
      belongs in another category, which belongs in another category… This
      cascading of permissions is made easy with Joomla's assets
      management.</para>

      <para>To enabled assets management in your table you need to have an
      <code>asset_id</code> column in your database table. This sets
      <code>$this-&gt;_trackAssets = true</code> when your table object is
      constructed (no need to do it manually).</para>

      <para>Moreover, you MAY have to override the
      _<code>getAssetParentId</code>, <code>_getAssetName</code> and
      <code>_getAssetTitle</code> methods if your items described by this
      table class belong in categories. Look at
      <code>\Joomla\CMS\Table\Content</code> to understand what is going
      on.</para>

      <para>Finally, your <code>bind()</code> method needs to be overwritten
      so you can call the <code>$this-&gt;setRules()</code> method against the
      raw, JSON-encoded permissions data stored in the database table. Saving
      rules is automatic; you don't have to handle it yourself.</para>
    </section>

    <section xml:id="com-tables-arrays-and-json">
      <title>Working with arrays and JSON data</title>

      <para>Sometimes you need to work with arrays of values or data which is
      stored as JSON but needs to be accessed as an object or array. Don't
      worry, this is possible with Joomla's Table class, albeit not
      immediately obvious.</para>

      <para>Let's say you want to work with array data in a column called
      <database>params</database>, stored in the database as a JSON-encoded
      string. You will need to think about three things:</para>

      <itemizedlist>
        <listitem>
          <para>Resetting a table. By default, Joomla uses the default value
          you have for the same named column in your database table. You want
          to change that to an empty array.</para>
        </listitem>

        <listitem>
          <para>Binding data. When Joomla loads a record and when we call the
          table object's <code>save()</code> method to create or modify a
          record, Joomla always calls the <code>bind()</code> method to set up
          the object's properties in way which makes sense for use in the
          code. In there we will need to convert our encoded field into an
          array.</para>
        </listitem>

        <listitem>
          <para>Storing data. The store() method needs the data in the record
          to be in a format which can be stored in the database table as-is.
          The plan here is to convert the array data to JSON before this
          method executes and convert out data back to array data right before
          this method returns.</para>
        </listitem>
      </itemizedlist>

      <programlisting language="php">class ItemTable extends \Joomla\CMS\Table\Table
{
  public function bind($src, $ignore = [])
  {
    $src           = (array) $src;
    $src['params'] = @json_decode($src['params']);

    return parent::bind($src, $ignore);
  }

  public function store($updateNulls = false)
  {
    $this-&gt;params = @json_decode($this-&gt;params ?? '{}', true) ?? [];

    $result = parent::store($updateNulls);

    $this-&gt;params = @json_encode($this-&gt;params) ?? '{}';

    return $result;
  }

  public function reset()
  {
    parent::reset();

    $this-&gt;params = [];
  }
}</programlisting>

      <para>Nothing stops you from using a
      <code>\Joomla\Registry\Registry</code> object instead of a plain array;
      in fact, it may be easier to manage. You may also have multiple fields
      in need of this kind of conversion.</para>

      <para>Another practical example is multi-select form fields, e.g.
      selecting one or more usergroups. The resulting array of integers can be
      easily converted to a comma-separated string for saving in the
      database.</para>
    </section>
  </section>

  <section xml:id="com-html">
    <title>HTML helper service</title>

    <para>Joomla has long provided a mechanism for creating your own HTML
    helper classes. These are meant to provide relatively short methods which
    return HTML snippets based on data which requires more than a line or two
    of PHP code to be processed and/or is called frequently enough throughout
    your component that it makes no sense having to the same thing over and
    over again. For example, you could have methods which return item
    associations, format dates, load a layout for presenting user information
    in backend grid views etc.</para>

    <para>Joomla 4 continues to offer this possibility and further enhances
    it. Your key take-aways are:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">Joomla 4 HTML helpers are services
        registered through your extension class</emphasis> instead of pure
        static classes which had to be registered with
        <code>\Joomla\CMS\HTML\HTMLHelper::addIncludePath</code>.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Joomla 4 HTML helpers have non-static
        methods</emphasis> whereas Joomla 3 HTML helpers had static
        methods.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">In Joomla 4 you can register whichever
        prefix you want</emphasis>, not necessarily the same as the name of
        the class(es) providing your HTML helper service(s).</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">You still call your HTML helpers through
        the <code>\Joomla\CMS\HTML\HTMLHelper::_()</code>
        method</emphasis>.</para>
      </listitem>
    </itemizedlist>

    <bridgehead>How we did things in Joomla 3</bridgehead>

    <para>Back in Joomla 3 we'd create a class file in our
    <filename>helpers/html</filename> folder, e.g.
    <filename>administrator/components/helpers/html/example.php</filename>. It
    would contain a pure static class with a name starting with
    <code>JHtml</code>, e.g <code>JHtmlExample</code>. Here's a trivial
    example:</para>

    <programlisting language="php">&lt;?php
class JHtmlExample {
  public static function hello($who) {
    $who = htmlspecialchars($who);
    
    return "&lt;p&gt;Hello, {$who}!&lt;/p&gt;";
  }
}</programlisting>

    <para>Within our component the helper was automatically registered and we
    could use it like this:</para>

    <programlisting language="php">&lt;?php echo \Joomla\CMS\HTML\HTMLHelper::_('example.hello', 'world') ?&gt;</programlisting>

    <para>This would result in</para>

    <screen>&lt;p&gt;Hello, world!&lt;/p&gt;</screen>

    <para>Outside our component we'd have to remember to register this helper
    manually:</para>

    <programlisting language="php">\Joomla\CMS\HTML\HTMLHelper::addIncludePath(JPATH_ADMINISTRATOR .
  '/components/com_example/helpers/html');</programlisting>

    <para>When we forgot to do that, e.g. in a module of ours? Hilarity
    ensued…</para>

    <para>This approach also had other problems. What if there are two
    helpers, one of ours and one of another component, using the same class
    name? PHP Fatal Error! What happens if we use a name for our helper which
    “shades” a name used by Joomla itself? We break things! What happens if
    the service we need to use is not available as a static method? Ugly
    workarounds! Generally speaking, it was a bad idea but, like most things
    in older versions of Joomla, was better than nothing which made it good
    enough.</para>

    <bridgehead>The way to do it in Joomla 4</bridgehead>

    <para>In Joomla 4 we will create a <emphasis>service</emphasis>. It sounds
    big and scary but... let me tell you a secret. We are just going to create
    a regular PHP class. It does not extend from anything, it does not have
    any special requirements. That's right, we are writing the simplest
    possible PHP class.</para>

    <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Service\Html;

class Example {
  public function hello($who) {
    $who = htmlspecialchars($who);

    return "&lt;p&gt;Hello, {$who}!&lt;/p&gt;";
  }
}</programlisting>

    <para>Now we can instantiate it in our component's extension class's boot
    method.</para>

    <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Extension;

use Acme\Component\Example\Administrator\Service\Html\Example;

class Example extends MVCComponent implements BootableExtensionInterface {

  public function boot(ContainerInterface $container)
  {
    $this-&gt;getRegistry()-&gt;register('example', new Example());
  }
}</programlisting>

    <bridgehead>Pushing services</bridgehead>

    <para>In the Joomla 3 paradigm the HTML helper class was static, meaning
    that any services it needs would have to be fetched with static or
    otherwise global calls as well. For example, getting the database driver
    object would require doing <code>\Joomla\CMS\Factory::getDbo()</code>. In
    Joomla 4 this kind of static calls is deprecated. So, how do you do
    it?</para>

    <para>The trick is that you can push services using the HTML helper
    class's constructor. For example, pushing the database:</para>

    <para><programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Service\Html;

class Example {
<emphasis role="bold">  private $db;</emphasis>

  <emphasis role="bold">public function __construct(\Joomla\Database\DatabaseDriver $db) {
    $this-&gt;db = $db;
  }</emphasis>

  public function hello($who) {
    $who = htmlspecialchars($who);

    return "&lt;p&gt;Hello, {$who}!&lt;/p&gt;";
  }
}</programlisting>We also need to change the initialisation of our HTML
    service:</para>

    <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Extension;

use Acme\Component\Example\Administrator\Service\Html\Example;

class Example extends MVCComponent implements BootableExtensionInterface {
  public function boot(ContainerInterface $container)
  {
    <emphasis role="bold">$db = $container-&gt;get('DatabaseDriver');</emphasis>
    $this-&gt;getRegistry()-&gt;register('example', new Example(<emphasis
        role="bold">$db</emphasis>));
  }
}</programlisting>

    <para>You can push any service, including your component's MVCFactory
    service which means that you can get instances of any Model of your
    component to retrieve database data in your HTML helper. Or, maybe,
    Joomla's UserFactory service so you can create instances of any user given
    their ID or username to get and present information about them. You get
    the idea!</para>
  </section>

  <section xml:id="com-categories">
    <title>Categories</title>

    <para>Sometimes your components may need to use Joomla's Categories
    feature. I am not talking about using content categories, where articles
    are placed in. I am talking about having Joomla manage categories for your
    own items. This is what Joomla itself is doing for its core components
    like Contacts and Banners.</para>

    <para>Using Joomla's categories instead of inventing your own
    categorisation has many benefits. The obvious benefit is that users are
    exposed to a familiar and consistent category management interface. Beyond
    the obvious, this is the only way you can have nice things such as <link
    linkend="com-fields">integration with custom fields</link>.</para>

    <section xml:id="com-categories-db">
      <title>Database schema changes</title>

      <para>Your table which contains the <emphasis>items</emphasis> which go
      into each category needs to have a few columns:</para>

      <programlisting language="mysql">`id`          BIGINT(20)    NOT NULL AUTO_INCREMENT COMMENT 'Item unique ID',
`catid`       BIGINT(20)    NOT NULL COMMENT 'Category ID',
`state`       TINYINT(3)    NOT NULL DEFAULT '1' COMMENT 'Publish status',</programlisting>

      <para>These fields don't necessarily need to have these names; we can
      change them in the code. However, these column names are the default
      used in Joomla and it makes it easier for you to follow third party
      tutorials and for other people to follow what you are doing with your
      code.</para>
    </section>

    <section xml:id="com-categories-manifest">
      <title>Changes to your XML manifest and forms</title>

      <para>A lot of this integration is, in fact, smoke and mirrors. Users
      are taken to the core <code>com_categories</code> component to manage
      categories. <code>com_categories</code> uses a form in our component, in
      the file
      <filename>administrator/components/<replaceable>com_example</replaceable>/forms/category.xml</filename>
      where <replaceable>com_example</replaceable> is our component, to add
      sections to the category configuration beyond the standard Joomla stuff.
      The way Joomla's main menu works along with a small change in our XML
      manifest will make the user think they are still in our component while
      they are using Joomla's com_categories.</para>

      <para>For the user to have a way to manage categories and maintain the
      illusion they remain in our extension you have to add the following code
      in your XML manifest under &lt;extension&gt;, &lt;administration&gt;,
      &lt;submenu&gt;:</para>

      <programlisting language="xml">&lt;menu link="option=com_categories&amp;amp;extension=<replaceable>com_example</replaceable>"&gt;JCATEGORIES&lt;/menu&gt;</programlisting>

      <para>where <replaceable>com_example</replaceable> is the name of your
      component.</para>

      <para>By default, you'll get a rather barren category edit page with
      just the bare minimum of information Joomla needs to store about a
      category (a title, alias and description are required — you can't hide
      them or remove them in any way). The basic tabs you get in the category
      editor are Category, Options, Publishing, Fields (if any custom Fields
      are set up for the category) and Permissions.</para>

      <para>You can display additional tabs with component-specific
      configuration options by creating the file
      <filename>administrator/components/<replaceable>com_example</replaceable>/forms/category.xml</filename>
      where <replaceable>com_example</replaceable> is the name of your
      component. This is a regular Joomla XML form file. Just remember, every
      <code>&lt;fieldset&gt;</code> you add becomes a tab in the Category edit
      page. Neat, huh?</para>
    </section>

    <section xml:id="com-categories-service">
      <title>The Category service</title>

      <para>Categories are great and all, but if you need to get their
      parameters or create SEF routes for nested categories you need to
      somehow get information on categories. This is what the category service
      does for us.</para>

      <para>It is customary — or at least I have not found a concrete reason
      to not be able to do otherwise — that the Category Service is created in
      the <emphasis>frontend</emphasis> part of your site.</para>

      <para>Assuming our <code>com_example</code> component with the namespace
      prefix <code>Acme\Component\Example</code>, you need to create the class
      <classname>Acme\Component\Example\Site\Service\Category</classname> in
      the file
      <filename>components/com_example/src/Service/Category.php</filename>
      like this:</para>

      <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Site\Service;

defined('_JEXEC') or die;

use Joomla\CMS\Categories\Categories;

class Category extends Categories
{
  public function __construct($options)
  {
    $options = array_merge($options, [
      'extension'  =&gt; 'com_example',
      'table'      =&gt; '#__example_items',
      'field'      =&gt; 'catid',
      'key'        =&gt; 'id',
      'statefield' =&gt; 'state',
      ]);

    parent::__construct($options);
  }

}</programlisting>

      <para>The array in the <methodname>__construct</methodname> method is
      all you need to customise and it's fairly self-explanatory.</para>

      <variablelist>
        <varlistentry>
          <term>extension</term>

          <listitem>
            <para>The name of your component e.g.
            <code>com_example</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>table</term>

          <listitem>
            <para>The name of the table holding the category
            <emphasis>items</emphasis>. As customary in Joomla you use
            <database>#__</database> to denote the common table name
            prefix.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>field</term>

          <listitem>
            <para>The name of the database column which contains the numeric
            category ID. The default is <code>catid</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>key</term>

          <listitem>
            <para>The name of the database column which contains the item's
            primary key. The default is <code>id</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>statefield</term>

          <listitem>
            <para>The name of the database column which contains the item's
            publish state. The default is <code>state</code>.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Now you see why I told you to use the database table field names
      customarily used by Joomla; they minimise the code you need to write
      down to two array keys: <code>extension</code> and
      <code>table</code>.</para>

      <para>Unlike other services provided by your component, the category
      service is instantiated directly:</para>

      <programlisting language="php">$catService = new Acme\Component\Example\Site\Service\Category([]);</programlisting>

      <para>The array in the constructor arguments is not just for show. It
      can help you narrow down the list of categories to be returned with the
      following keys:</para>

      <variablelist>
        <varlistentry>
          <term>access</term>

          <listitem>
            <para>Boolean. When true, Joomla will only return the categories
            visible to the current user. It does that by only getting from the
            database the categories whole <database>access</database> field is
            one of the Joomla viewing access levels the current user has
            access to.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>published</term>

          <listitem>
            <para>Integer 0 or 1. When it's 1 it will only return categories
            which are published. When 0 it will return published, unpublished
            <emphasis>and trashed</emphasis> categories.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>countItems</term>

          <listitem>
            <para>Integer 0 or 1. Note the weird capitalisation in the middle
            of this key's name! When it's 1, Joomla will return the number of
            items contained in each category at the expense of performance.
            Use this sparingly and only when you absolutely need it e.g. when
            displaying paginated views.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Also keep in mind that Joomla tries to be smart. A bit
      <emphasis>too</emphasis> smart, maybe. When you are on a multilingual
      site it will only return categories whose language is either the
      currently selected language or “All” (denoted by a <code>*</code> in the
      language column of the <database>#__categories</database> table). If you
      want to override this behaviour you will need to change your Categories
      Service constructor like so:</para>

      <programlisting language="php">public function __construct($options)
{
  $options = array_merge($options, [
    'extension'  =&gt; 'com_example',
    'table'      =&gt; '#__example_items',
    'field'      =&gt; 'catid',
    'key'        =&gt; 'id',
    'statefield' =&gt; 'state',
  ]);

  parent::__construct($options);

  $this-&gt;_options['currentlang'] = $options['currentlang'] ?? $this-&gt;_options['currentlang'];
}</programlisting>

      <para>If you want the instance of the Categories Service to return all
      categories regardless of the current language in a multilingual site you
      can now do:</para>

      <programlisting language="php">$catService = new Acme\Component\Example\Site\Service\Category([
  'currentlang' =&gt; 0
]);</programlisting>
    </section>
  </section>

  <section xml:id="com-router">
    <title>Router</title>

    <para>Most components have a backend and a frontend part. The backend part
    is used by the site administrators to set up the content being managed by
    the component and the frontend part is used to display said content to the
    visitors of the site.</para>

    <section xml:id="com-router-routing-overview">
      <title>The case for URL routing</title>

      <para>By default, Joomla's frontend URLs look something like
      this:</para>

      <para><uri>https://www.example.com/index.php?option=com_example&amp;view=item&amp;id=123&amp;Itemid=456</uri></para>

      <para>This is called a regular or non-SEF URL. The SEF URL — what other
      CMS may call a “permalink” or a “<emphasis>route</emphasis>” — could be
      something like</para>

      <para><uri>https://www.example.com/acme-shop/roadrunner-hunting/explosives/tnt-crate.html</uri></para>

      <note>
        <para><acronym>SEF</acronym> is an acronym which stands for Search
        Engine Friendly and is called like that for historical reasons — back
        in 2001 when Joomla's predecessor, Mambo, introduced this feature a
        human-understandable URL was also helping the primitive search engines
        of that era to get better context of what the page is about. This
        stopped being true by the time Joomla emerged as its own software, in
        2005.</para>

        <para>Joomla co-founder Brian Teeman coined a better, if not much more
        British, term: Pub Ear Friendly. The idea being that when you try to
        give the URL of a page to your mate while downing pints at your local,
        rather lively, pub it's easier to give them a few words they can
        understand than a long string of alphanumeric characters. For some
        reason this alternate term never stuck…</para>
      </note>

      <para>The transformation of the ugly, incomprehensible (at least to
      non-developers), non-SEF URL into the SEF URL and of the SEF URL back to
      the ugly non-SEF version (so Joomla can figure out which component to
      load and what to tell it to do) is called <emphasis role="bold">SEF
      routing</emphasis> in the Joomla vernacular. Most everywhere else you
      will see it being called <emphasis role="bold">URL routing</emphasis>.
      Well, the Joomla vernacular is full of certain historical quirks which
      makes it harder for newcomers to figure out what is what, but this is
      neither here nor there.</para>

      <para>URL routing in Joomla is implemented in the core. However, the
      core code cannot <emphasis>possibly</emphasis> know how your component
      is supposed to logically structure its content so as to convert this
      into a human and machine understandable URL. Therefore it delegates that
      responsibility to the component, namely to our component's
      Router.</para>
    </section>

    <section xml:id="com-router-abandon-all-hope">
      <title>Intermission: abandon all hope ye who enter here</title>

      <para>Before we go on, let's discuss a little bit how Joomla URL routing
      works. It's long, it's a bit depressing, but read to the end — as you'll
      see, all problems with the URL routing in Joomla are ultimately
      <emphasis role="bold">a user education issue</emphasis>, not a coding
      issue.</para>

      <para>You would expect web software to have have absolutely
      deterministic, clear routing for URLs. Given a set of URL parameters
      (the “non-SEF URL”) the URL router (“SEF router”) will spit out the same
      route (“SEF URL”). In this ideal world we already have nuclear fusion
      and world peace, we have solved poverty and hunger and… I
      digress.</para>

      <para>In the imperfect world we live in, web software has to choose one
      of two evils. URL routing is either extremely technical and inflexible
      but robust, or it is is user-friendly and flexible but can result in
      some very weird situations. Joomla chose the latter. It's what allows
      modules to work the way they do which is one of the many reasons Joomla
      is an insanely powerful but still user-friendly CMS. But which part of
      its soul did it have to sell to you-know-who to do that? Let's
      see…</para>

      <para>URL routing in Joomla operates in two axes. On one hand we have
      the user-defined menu structure which operates as the first pass of URL
      routing and is defined by users, who are humans and not very good at
      managing hierarchies (make that <emphasis>doubleplusungood</emphasis>,
      Winston). Then you have the SEF router of our component which, unlike
      users, works in a perfectly logical, orderly fashion.</para>

      <para>The thing is, they are both working at the same time to do URL
      routing and this can cause some… uh…
      <emphasis>complications</emphasis>.</para>

      <para>Let's say you have the following data hierarchy:</para>

      <itemizedlist>
        <listitem>
          <para>Category A, alias <code>alpha</code>.</para>

          <itemizedlist>
            <listitem>
              <para>Category B, alias <code>bravo</code>.</para>

              <itemizedlist>
                <listitem>
                  <para>Article C, alias <code>charlie</code></para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>And you have the following menu structure (as to why the user
      chose this seemingly bonkers menu structure, no, they are not trying to
      sabotage your code, they have a good reason but we'll get back to that
      later):</para>

      <itemizedlist>
        <listitem>
          <para>Category item list for Category B, alias <code>bravo</code>.
          Item ID 123.</para>

          <itemizedlist>
            <listitem>
              <para>Single article view for Article C, alias
              <code>charlie</code>. Item ID 234.</para>

              <itemizedlist>
                <listitem>
                  <para>Category A, alias <code>alpha</code>. Item ID
                  345.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>You would expect that the URL for category A is
      https://www.example.com/alpha, category B's is
      https://www.example.com/alpha/bravo and article C's is
      https://www.example.com/alpha/bravo/charlie.</para>

      <para>Nope.</para>

      <para>The URL for category A is
      <uri>https://www.example.com/bravo/charlie/alpha</uri> per the menu
      structure.</para>

      <para>The URL for category B is <uri>https://www.example.com/bravo</uri>
      per the menu structure.</para>

      <para>The URL for article C is
      <uri>https://www.example.com/bravo/charlie</uri> per BOTH the menu
      structure AND the SEF router of com_content.</para>

      <para>However, it's perfectly possible to access article C as
      https://www.example.com/bravo/charlie/alpha/charlie. The first three
      parts of the route (/bravo/charlie/alpha) are the menu structure to
      category A. The rest (bravo/charlie) is handled by the SEF router of
      com_content.</para>

      <para>*record scratch*</para>

      <para>But, wait, wait a second! How does Joomla know when to use each
      URL?! I am glad you asked, the answer is the <code>Itemid</code> URL
      parameter, i.e. the menu item ID for which we are going to be generating
      a URL for our… something!</para>

      <para>If we are routing the URL to article C using a URL with Itemid=123
      Joomla will first figure out that we have a menu item to Article C's
      parent category (Category B). It will then ask our URL router to route
      this item in this category which will make our com_content router return
      <code>charlie</code>. Therefore Joomla will return the relative URL
      <code>bravo/charlie</code>.</para>

      <para>If we are routing the URL to article C using a URL with Itemid=234
      Joomla sees that the Itemid matches exactly what we need to route,
      therefore it will return the menu structure up to this point, i.e. the
      relative URL <code>bravo/charlie</code>.</para>

      <para>HOLD ON A SECOND! Both of these methods returned… THE SAME URL!
      Ah, keen eyed reader, you are right! I can see you despairing. Oh,
      please, not yet! It's about to get <emphasis>worse</emphasis>. You see,
      when Joomla parses the URL it prioritises the menu structure over the
      SEF router of each component. Since <code>bravo/charlie</code> is,
      indeed, a valid menu structure it will simply return the non-SEF URL
      index.php?Itemid=234 — in both cases.</para>

      <para>But, but, but… Isn't the Itemid how we tell modules when to
      display? Why, yes, it is! Oh, you had different modules displaying in
      menu items 123 and 234? Too bad! You don't get to choose. Sorry.</para>

      <para>Back to routing non-SEF to SEF URLs. If you route article C using
      a URL with Itemid=345 Joomla tells you that you are on category A. So
      your SEF route has to find a full path to your article which would be
      bravo/charlie and this is added to Category A, menu item 345's URL of
      bravo/charlie/alpha to make the entirely confusing URL
      bravo/charlie/alpha/bravo/charlie which works perfectly.</para>

      <para>What about trying to route article C without an Itemid? Now things
      get a bit tastier and testier. Joomla will try to find the most relevant
      route using the segments returned by your SEF router and trying to match
      them with the menu structure… Which one it is? Frankly, I don't have the
      foggiest off the top of my head. I'd have to build that site to figure
      it out. I would think it's the same as using Itemid=345. If all else
      fails, Joomla will use the Home item's Itemid and all bets are
      off.</para>

      <para>Of course, this means that the same article can have three URLs,
      two of which are identical and one of them does not resolve to what
      you'd expect. But this is normal! And no, forget about getting a
      canonical URL for article C because there's none.</para>

      <para>This insanity cannot be addressed because it would require
      decoupling URL routing from Joomla's menu system. However, this would
      mean that all published modules appear in all pages as there is no
      longer a way to know which menu item you're in. Of course it's the
      solution to this problem which broke module display in our example above
      but this is what you get when the users are “crazy”.</para>

      <para>Or are they?</para>

      <para>While it sounds convoluted and problematic, this method is not the
      least bit more convoluted and problematic than any other given CMS
      <emphasis>when you take into account all the possible<footnote>
          <para>For any given, singular use case and a set of routing
          algorithms it is very easy to find the one algorithm which is most
          suitable, meaning the rest are unsuitable. However, every single use
          case has a different most suitable algorithm. Given a very large
          number of use cases, like the near infinite uses cases a CMS is
          called to address, any given routing algorithm would be just as
          unsuitable for most use cases as every other. Therefore the task of
          finding the “best” algorithm is reduced to finding an algorithm
          which fulfils some secondary or tertiary business goals such as
          making it possible for an end user to easily configure with a GUI or
          support our vision of having different modules show up in each page.
          The primary business goal of the “best” routing for the generic use
          case is, by definition, a bust unless we are willing to drastically
          reduce the use cases we are willing to support.</para>
        </footnote>, almost infinite use cases it's called to work
      with</emphasis>. It works great insofar the user can be trusted to not
      create psychopathic menu structures which work against the data
      structure, reusing the same aliases for a good measure of
      insanity.</para>

      <para>But why would any user even create such a menu structure to begin
      with?!</para>

      <para>As a matter of fact, the menu structure I presented <emphasis
      role="bold">is the wrong way to use Joomla</emphasis>. I confess I
      misdirected you but I did so for a noble reason. What the user most
      likely wanted was the menu item's <emphasis>visual</emphasis> structure
      to be what we presented for user experience reasons. They most likely
      don't care or not even <emphasis>want</emphasis> the crazy URL
      structure. They would very likely be spending hundreds of Euros every
      year in various SEF / SEO tools to try and fix their mistake… when they
      could just be told how to use Joomla the way Joomla was intended to be
      used to begin with.</para>

      <para>The One True Joomla Way™ is to use a “hidden” menu (a menu without
      a module to display it) to generate the URL structure in a way that's
      mostly following the data structure and a shown menu with Alias menu
      items for the visual display.</para>

      <para>So, in our example, the hidden menu would be:</para>

      <itemizedlist>
        <listitem>
          <para>Category A, alias <code>alpha</code>. Item ID 345.</para>

          <itemizedlist>
            <listitem>
              <para>Category item list for Category B, alias
              <code>bravo</code>. Item ID 123.</para>

              <itemizedlist>
                <listitem>
                  <para>Single article view for Article C, alias
                  <code>charlie</code>. Item ID 234.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>And the visible menu:</para>

      <itemizedlist>
        <listitem>
          <para>Category item list for Category B, alias to menu item
          123.</para>

          <itemizedlist>
            <listitem>
              <para>Single article view for Article C, alias to menu item
              234.</para>

              <itemizedlist>
                <listitem>
                  <para>Category A, alias <code>alpha</code>, alias to menu
                  item 345.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>That's the reason I went through this intentionally provocatively
      named section. When you are doing end user support you <emphasis
      role="bold">WILL</emphasis> come up with the atrocious menu structures
      like the one I presented above.</para>

      <para>Do NOT try to address this in your router code; you will lose your
      mind and you will never make it work for all of your users. Remember,
      there is no routing method which is suitable for every use case and you
      cannot possibly address infinite use cases. Value your sanity as a
      developer! Learn when to say “no” to users.</para>

      <para>Instead, ask your user what is their <emphasis>use case</emphasis>
      and is <emphasis>their intention</emphasis> with their menu structure:
      are they trying to shape the URL structure or just the way things are
      presented on their site? In 99 out of 100 cases the user intended to
      affect only the visual presentation of the menu; they have no idea they
      are shooting their feet by affecting the URL structure. Patiently
      explain them the trick about hidden menus. You'll get grateful clients
      for life.</para>
    </section>

    <section xml:id="com-router-j3-vs-j4">
      <title>Joomla 3 vs Joomla 4</title>

      <para>In Joomla 3 we would create a router as a
      <filename>router.php</filename> file in the root of our component's
      frontend, e.g. <filename>components/com_example/router.php</filename>.
      That file had two ways to implement a router:</para>

      <itemizedlist>
        <listitem>
          <para>Two separate functions whose names consisted of the name of
          the component without the <code>com_</code> prefix and the suffixes
          <code>BuildRoute</code> and <code>ParseRoute</code>, e.g.
          <function>exampleBuildRoute</function> and
          <function>exampleParseRoute</function>. This was the very old way
          which was deprecated since Joomla 3.3 released in 2014.</para>
        </listitem>

        <listitem>
          <para>As a class extending
          <classname>JComponentRouterBase</classname> (renamed to
          <classname>Joomla\CMS\Component\Router\RouterBase</classname> in
          later Joomla versions) or, more usually,
          <classname>JComponentRouterView</classname> (introduced in Joomla
          3.5 and renamed to
          <classname>Joomla\CMS\Component\Router\RouterView</classname> in
          later Joomla versions).</para>
        </listitem>
      </itemizedlist>

      <para>If you are using the former method you have a lot of work ahead of
      you to convert it to a Joomla 4 compatible router. If you are using the
      latter method you are virtually ready, with minimal changes!</para>

      <para>In Joomla 4 the router is implemented as the class
      <code>Service\Router</code> in the frontend part of our component. So,
      with a component <code>com_example</code> that has a namespace prefix
      <code>Acme\Component\Example</code> that would be the class
      <classname>Acme\Component\Example\Site\Service\Router</classname> in the
      file <filename>components/com_example/src/Service/Router.php</filename>.
      That class needs to extend from
      <classname>Joomla\CMS\Component\Router\RouterBase</classname> or, more
      typically <classname>Joomla\CMS\Component\Router\RouterView</classname>,
      just like in Joomla 3.5<footnote>
          <para>The entire concept of routing using the RouterView has not
          changed since Joomla 3.5 which was released in 2016. You see, at
          this point in time development of Joomla 4 had already started and
          Joomla introduced the new routing to help developers migrate their
          extensions to the new router before Joomla 4 is released.</para>
        </footnote> and later versions.</para>

      <para>There is one more difference in Joomla 4 and later versions. By
      default, the component does not know that it needs to use a
      router.</para>

      <para>To understand what and why we need to do, let's go backwards.
      Joomla only knows it needs to use a router factory when the component's
      extension class implements the
      <interfacename>\Joomla\CMS\Component\Router\RouterServiceInterface</interfacename>.
      When this is the case, Joomla knows that it can ask the extension class
      to return a Router Factory object using the
      <methodname>createRouter</methodname> method defined in said interface.
      The component's extension class does not know how to find the router
      factory object; it is injected into it by the component service provider
      (<filename>services/provider.php</filename>). In its turn, it asks the
      component's DI Container for that Router Factory object. The DI
      Container will only know how to get a Router Factory object if we
      register a Router Factory service provider in the service provider
      (<filename>services/provider.php</filename>).</para>

      <para>Unraveling these chained dependencies we see that we need to make
      changes in just two files.</para>

      <para>Your component's extension class must implement the
      <interfacename>\Joomla\CMS\Component\Router\RouterServiceInterface</interfacename>
      interface. The easiest way to provide its implementation is having it
      use the
      <classname>\Joomla\CMS\Component\Router\RouterServiceTrait</classname>
      trait.</para>

      <para>That trait requires your component service provider (e.g.
      <filename>administrator/components/com_example/services/provider.php</filename>)
      to do two things. First, it needs to register a Router Factory service
      provider before trying to create the component object:</para>

      <programlisting language="php">$container-&gt;registerServiceProvider(
  new \Joomla\CMS\Extension\Service\Provider\RouterFactory
  (
    '\\Acme\\Component\\Example'
  )
);</programlisting>

      <para>The
      <classname>\Joomla\CMS\Extension\Service\Provider\RouterFactory</classname>
      class is the default Joomla implementation of a component router
      factory. It needs exactly one configuration parameter in its
      constructor, the namespace of your component
      <emphasis>without</emphasis> the <code>Site</code> or
      <code>Administrator</code> suffix.</para>

      <para>Then, after having created our component extension class' object,
      we need to inject the Router Factory object into it:</para>

      <programlisting language="php">$container-&gt;set(
  ComponentInterface::class,
  function (Container $container) {
    $component = new ExampleComponent(
      $container-&gt;get(ComponentDispatcherFactoryInterface::class)
    );

    // ... other initialisation goes here ...

    // Inject the router factory object
    <emphasis role="bold">$component-&gt;setRouterFactory(
      $container-&gt;get(
        \Joomla\CMS\Component\Router\RouterFactoryInterface::class
      )
    );</emphasis>
  }
);</programlisting>

      <para>While it looks a bit verbose, it accomplishes two things. First,
      it's not possible to be surprised by Joomla magically implementing a
      feature in your component you did not expect. Second, in the case of a
      router, it allows us to <link
      linkend="com-router-push-dependencies">push dependencies (services) into
      our router object</link>.</para>
    </section>

    <section xml:id="com-router-routerview">
      <title>Using RouterView</title>

      <para>If you are using a router class extending from
      <classname>Joomla\CMS\Component\Router\RouterView</classname> it is
      fairly easy to create a router for most components.</para>

      <para>The constructor of your class tells Joomla which views of your
      component can be routed in the frontend and the relation to each other.
      For example:</para>

      <programlisting language="php">public function __construct(SiteApplication $app = null, AbstractMenu $menu = null)
{
  $welcome = new \Joomla\CMS\Component\Router\RouterViewConfiguration('welcome');
  $this-&gt;registerView($welcome);

  $item = (new \Joomla\CMS\Component\Router\RouterViewConfiguration('item'))
    -&gt;setKey('id')
    -&gt;addLayout('default')
    -&gt;addLayout('fancy');
  $this-&gt;registerView($item);

  $detail = (new \Joomla\CMS\Component\Router\RouterViewConfiguration('detail'))
    -&gt;setKey('id')
    -&gt;setParent($item, 'itemid');
  $this-&gt;registerView($detail);

  parent::__construct($app, $menu);

  $this-&gt;attachRule(new \Joomla\CMS\Component\Router\Rules\MenuRules($this));
  $this-&gt;attachRule(new \Joomla\CMS\Component\Router\Rules\StandardRules($this));
  $this-&gt;attachRule(new \Joomla\CMS\Component\Router\Rules\NomenuRules($this));
}</programlisting>

      <para>This tells Joomla that we have three routable views called
      <code>welcome</code>, <code>item</code> and <code>detail</code>. The
      <code>detail</code> view is a child of <code>item</code>.</para>

      <para>How would Joomla know about which detail is under a specific item?
      We told it that the <code>detail</code>'s <code>itemid</code> property
      must match the key of the <code>item</code> and the key of the
      <code>item</code> is called <code>id</code>.</para>

      <para>The last three lines tell Joomla which routing rules to
      register:</para>

      <itemizedlist>
        <listitem>
          <para><classname>MenuRules</classname>. Tries to detect the correct
          Itemid for a view if none was provided in the non-SEF URL. You
          should keep that unless you want to implement the
          <methodname>preprocess</methodname> method yourself.</para>

          <note>
            <para>The <methodname>preprocess</methodname> method is called
            before the SEF URL is built and, crucially, before Joomla tries to
            figure out the <code>format</code> and <code>Itemid</code> URL
            parameters to send to your component's Router's build
            method.</para>

            <para>In Joomla 3 you could get away with trying to figure out and
            change the <code>format</code> and <code>Itemid</code> parameters
            in your router's <methodname>build</methodname> method. While this
            was necessary for compatibility with legacy
            <filename>router.php</filename> files (those using the two
            distinct functions), <emphasis>this “hack” will no longer work in
            Joomla 4</emphasis>. You must move that code into the
            <methodname>preprocess</methodname> method. If you fail to do so,
            your SEF URLs will not work properly; from your perspective, it
            will be as if your <code>format</code> and <code>Itemid</code>
            values overridden in the built method were never taken into
            account. That's <emphasis>exactly</emphasis> what happens.</para>

            <para>This is actually a good change. It makes the core routing
            code more efficient and keeps us third party developers in the
            habit of applying separation of concerns in our code.</para>
          </note>
        </listitem>

        <listitem>
          <para><classname>StandardRules</classname>. Standard non-SEF to SEF
          URL (and vice-versa) routing. If you omit this you will not get any
          SEF URL routing which beats the purpose of having a router.</para>
        </listitem>

        <listitem>
          <para><classname>NomenuRules</classname>. Process URLs when no
          Itemid exists for the component. This is necessary to route URLs
          when no published menu items exist for your component and Joomla
          needs to create or parse URLs in the format
          <uri>/component/example/foo/bar.html</uri>.</para>
        </listitem>
      </itemizedlist>

      <para>At this point Joomla knows the logical hierarchy of our
      component's views but it does not know how to convert an id in the
      non-SEF URL to a SEF URL segment when building the SEF URL (e.g. convert
      an item ID to its alias) or how to convert a SEF URL segment back to a
      non-SEF URL's numeric ID when it's parsing the SEF URL (e.g. convert an
      item alias to its ID). This is up to us.</para>

      <para>We need to provide two methods for each
      <classname>RouterViewConfiguration</classname> objects we created:
      <methodname>get<replaceable>Something</replaceable>Segment</methodname>
      and <methodname>get<replaceable>Something</replaceable>Id</methodname>
      where <replaceable>Something</replaceable> is the name of the view with
      its first letter capitalised. Here's what the code for the Item view
      would look like in our example:</para>

      <programlisting language="php">public function getItemId(string $segment, array $query): bool|int
{
  $db = \Joomla\CMS\Factory::getContainer()-&gt;get('DatabaseDriver');
  $dbQuery = $db-&gt;getQuery(true)
    -&gt;select($db-&gt;quoteName('id'))
    -&gt;from($db-&gt;quoteName('#__example_items'))
    -&gt;where($db-&gt;quoteName('alias') . ' = :alias')
    -&gt;bind(':alias', $segment);

    return  $db-&gt;setQuery($dbQuery)-&gt;loadResult() ?: false;
  }

  public function getItemSegment(int $id, array $query): array
  {
    $db = \Joomla\CMS\Factory::getContainer()-&gt;get('DatabaseDriver');
    $dbQuery = $db-&gt;getQuery(true)
      -&gt;select($db-&gt;quoteName('alias'))
      -&gt;from($db-&gt;quoteName('#__example_items'))
      -&gt;where($db-&gt;quoteName('id') . ' = :id')
      -&gt;bind(':id', $id);

    $segment = $db-&gt;setQuery($dbQuery)-&gt;loadResult() ?: null;

    if ($segment === null) {
      return [];
    }

    return [$segment];
  }</programlisting>

      <para>There is something worth noting here. The
      <methodname>get<replaceable>Something</replaceable>Segment</methodname>
      method can return an array with more than one segments. This is useful
      if you want to somehow return a more complex structure e.g.
      <uri>item/foo/detail/bar</uri> where <code>item</code> and
      <code>detail</code> are fixed strings. However, if you do that, you will
      need to override the <methodname>parse</methodname> method to handle
      multi-segment views. The default implementation in
      <classname>StandardRules</classname> assumes that you are using exactly
      one segment per view and that's why
      <methodname>get<replaceable>Something</replaceable>Id</methodname>
      accepts a string, not an array, as its first argument.</para>

      <para>You may wonder, what about our <code>welcome</code> view? Don't we
      need to create methods for it? No, we don't. Views which do not have a
      key set for them use the name of the view as the (only) segment for SEF
      URLs. If there is a naming clash between such a view and an alias of a
      top-level view (or category, as we will see below) the first
      <classname>RouterViewConfiguration</classname> object registered “wins”
      in determining how that segment should be parsed. As a result, you
      should keep this kind of top-level views to a minimum and either inform
      users that they cannot use these aliases or actively prevent them with
      validation rules whenever possible.</para>
    </section>

    <section xml:id="com-router-push-dependencies">
      <title>Pushing dependencies to the Router</title>

      <para>You may have noticed that in the sample code above I got the
      database driver object using the
      <methodname>Factory::getContainer</methodname> static method. This is
      not ideal. It's even worse if I'd need to get access to MVC objects such
      as Models and Tables — having to boot the entire component just to get
      its MVCFactory is something to use only if there is no other way, not
      something to do by default.</para>

      <para>Fortunately, Joomla gives us the option to push any services we
      need — such as the database driver object and the component's MVCFactory
      — into the router. Unfortunately, it's a bit non-obvious.</para>

      <para>To inject services into the Router service object they need to be
      injected into the object after it is created by the Router Factory
      object. The Router Factory object needs to have access to these services
      to inject them. This means injecting these services to the Router
      Factory object from the Router Factory Service Provider. The Router
      Factory Service Provider can get any of the dependencies (services) it
      needs since it has access to the component's service provider.</para>

      <para>Therefore we need to create the two missing pieces of the puzzle
      (Router Factory and its service provider) and register the latter with
      our component's service provider.</para>

      <important>
        <para>The component's service provider
        (<filename>services/provider.php</filename>) lives in the backend
        portion of your component. Therefore. it makes sense that the Router
        Factory and the Router Factory Service Provider also live in the
        backend of your component <emphasis>even though the Router is only
        used in the frontend of the site</emphasis>.</para>

        <para>Yup. It sounds backwards. You can definitely create them in the
        frontend but, if you do, <emphasis>you</emphasis> and everyone else
        reading your code might get confused. Don't over-think it, just do
        what I tell you to do. There's method in this madness, I
        promise.</para>
      </important>

      <para>First, let's make our router MVCFactory-aware (it's already
      database-aware).</para>

      <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Site\Service;

use Joomla\CMS\Component\Router\RouterView;
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;

class Router extends RouterView
{<emphasis role="bold">
  use MVCFactoryAwareTrait;
                </emphasis>
  // ... the rest of the router implementation goes here ...
}</programlisting>

      <para>Now, let's create a Router Factory
      (<classname>\Acme\Component\Example\Administrator\Service\RouterFactory</classname>).
      The default Joomla implementation is already database-aware. I am just
      extending it to also know about the MVCFactory so we can inject it to
      our router.</para>

      <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\Service;

use Joomla\CMS\Application\CMSApplicationInterface;
use Joomla\CMS\Component\Router\RouterInterface;
use Joomla\CMS\Menu\AbstractMenu;
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;

class RouterFactory extends \Joomla\CMS\Component\Router\RouterFactory
{
  use MVCFactoryAwareTrait;

  public function createRouter(CMSApplicationInterface $application, AbstractMenu $menu): RouterInterface
  {
    $router = parent::createRouter($application, $menu);

    $router-&gt;setMVCFactory($this-&gt;getMVCFactory());

    return $router;
  }
}</programlisting>

      <para>Now, we need to create a RouterFactory service provider.
      Unfortunately, Joomla has a bad habit of registering factory objects in
      the DI container even though they are only going to return exactly one
      object with no initialisation, like a router. This complicates thing
      because we cannot extend the DI container definition. We have to do
      something stupid: copy Joomla's default implementation of the Router
      Factory Service Provider just so we can change the returned object type
      and register dependencies on it. Well... I guess it could be
      worse?</para>

      <para>Anyway. Let's create our router factory service provider
      <classname>\Acme\Component\Example\Administrator\Service\Provider\RouterFactoryProvider</classname>.</para>

      <programlisting language="php">&lt;?php
namespace \Acme\Component\Example\Administrator\Service\Provider;

<emphasis role="bold">use Acme\Component\Example\Administrator\Service\RouterFactory;</emphasis>
use Joomla\CMS\Categories\CategoryFactoryInterface;
use Joomla\CMS\Component\Router\RouterFactoryInterface;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\Database\DatabaseInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

class RouterFactoryProvider implements ServiceProviderInterface
{
  /**
   * The module namespace
   *
   * @since   4.0.0
   * @var  string
   *
   */
  private $namespace;

  /**
   * DispatcherFactory constructor.
   *
   * @param   string  $namespace  The namespace
   *
   * @since   4.0.0
   */
  public function __construct(string $namespace)
  {
    $this-&gt;namespace = $namespace;
  }

  /**
   * Registers the service provider with a DI container.
   *
   * @param   Container  $container  The DI container.
   *
   * @return  void
   *
   * @since   4.0.0
   */
  public function register(Container $container)
  {
    $container-&gt;set(
      RouterFactoryInterface::class,
      function (Container $container) {
        $categoryFactory = null;

        if ($container-&gt;has(CategoryFactoryInterface::class))
        {
          $categoryFactory = $container-&gt;get(CategoryFactoryInterface::class);
        }

        $routerFactory = new <emphasis role="bold">RouterFactory</emphasis>(
          $this-&gt;namespace,
          $categoryFactory,
          $container-&gt;get(DatabaseInterface::class)
        );

        <emphasis role="bold">$routerFactory-&gt;setMVCFactory($container-&gt;get(MVCFactoryInterface::class));</emphasis>

        return $routerFactory;
      }
    );
  }
}            </programlisting>

      <para>Our changes to the core code in Joomla are highlighted in bold
      type.</para>

      <para>Finally, we need to register this router factory service provider
      in our component's <code>services/provider.php</code> file.</para>

      <programlisting language="php">$container-&gt;registerServiceProvider(
  new \Acme\Component\Example\Administrator\Service\Provider\RouterFactoryProvider(
    '\\Acme\\Component\\Example'
  )
);</programlisting>
    </section>
  </section>

  <section xml:id="com-dashboard">
    <title>Dashboard</title>

    <para>There is a new feature starting with Joomla 4: Dashboards.</para>

    <para>Dashboards are sort of virtual pages, displayed by means of the
    com_cpanel core component, <link
    xlink:href="https://magazine.joomla.org/all-issues/april-2021/joomla-4-customising-admin-dashboards">which
    allow the developer and the site owners to publish modules to customise
    them</link>.</para>

    <bridgehead>Define a dashboard</bridgehead>

    <para>You can define one or more dashboards in your component's XML
    manifest file:</para>

    <programlisting language="xml">&lt;dashboards&gt;
  &lt;dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="none fa fa-beer"&gt;com_example.something&lt;/dashboard&gt;
&lt;/dashboards&gt;</programlisting>

    <note>
      <para><code>&lt;dashboards&gt;</code> is a top-level tag, directly under
      the <code>&lt;extension&gt;</code> root tag. Yes, even though it only
      applies in the component's administration (backend) section. If your
      Dashboard does not work first check that you have not accidentally put
      that tag under <code>&lt;administration&gt;</code>. It's the most common
      mistake!</para>
    </note>

    <para>The <code>title</code> attribute's value is a language string
    defined in your extension's backend INI language file. It's customary for
    its string to end with the word “Dashboard”, e.g.</para>

    <programlisting language="ini">COM_EXAMPLE_DASHBOARD_TITLE="Example Dashboard"</programlisting>

    <para>The value of the <code>icon</code> attribute is a CSS class which
    gives the dashboard page its icon. Joomla 4 loads FontAwesome 5 Free so
    you can use <link
    xlink:href="https://fontawesome.com/v5/search?o=r&amp;m=free">any of its
    icons</link>. Please remember that Joomla prefixes the value of the
    <code>icon</code> attribute with the string literal <code>icon-</code>.
    This does not let you use all FontAwesome icons. To work around that I use
    the value <code>none fa fa-beer</code> which results in the HTML attribute
    and value <code>class="icon-none fa fa-beer"</code>. Since
    <code>icon-none</code> does not display anything, the browser falls back
    to the next two CSS classes which render FontAwesome's beer mug
    icon.</para>

    <warning>
      <para>The Dashboard is not part of your component. It does not load any
      custom backend CSS you may have. As a result, you cannot display your
      logo or any custom image in the Dashboard. While you could do that by
      loading custom CSS in a module you set up in the dashboard, do keep in
      mind that the user can easily disable (unpublish) that module and then
      your CSS won't load anymore. If you opt for this trick it's a good idea
      to provide a fallback to a Joomla system icon class or a FontAwesome
      icon class to make sure that <emphasis>something</emphasis> is displayed
      as the Dashboard's title icon.</para>
    </warning>

    <para>The value inside the tag <emphasis>must</emphasis> be in the format
    <code>component.something</code> where component is the name of your
    component (e.g. <code>com_example</code>) and something is a unique
    identifier for the dashboard among all dashboards defined in your
    component. For example, we could have the dashboard
    <code>com_example.something</code>.</para>

    <important>
      <para>Your component manifest MUST ALSO follow the naming convention
      <filename>bareComponent.xml</filename> and be placed in the backend
      folder of your component. For example, <code>com_example</code>'s XML
      manifest MUST be called <filename>example.xml</filename> and be found in
      administrator/components/com_example/<filename>example.xml</filename>.</para>

      <para>Keep in mind that Joomla automatically copies your component's XML
      manifest to the backend of your site when installing the component. You
      will only ever have to do it manually — if ever — when developing a
      component locally.</para>
    </important>

    <para>The value of the tag after the dot is also important. All modules
    published to the module position
    <code>cpanel-<replaceable>com_example</replaceable>-<replaceable>something</replaceable></code>
    will appear in this dashboard <code>com_example.something</code>.</para>

    <bridgehead>Display a link to your dashboard in the component's
    submenu</bridgehead>

    <para>The dashboard is cool… but how do you even display it? As it turns
    out there are exactly two ways:</para>

    <itemizedlist>
      <listitem>
        <para>Put a link (e.g. a Toolbar link button) in your extension
        pointing the browser to
        <uri>index.php?index.php?option=com_cpanel&amp;view=cpanel&amp;dashboard=<replaceable>com_example.something</replaceable></uri>
        where <replaceable>com_example.something</replaceable> is your custom
        dashboard.</para>
      </listitem>

      <listitem>
        <para>Add a submenu item in your XML manifest, e.g.</para>

        <programlisting language="xml">&lt;menu&gt;COM_EXAMPLE&lt;/menu&gt;

&lt;submenu&gt;
<emphasis role="bold">  &lt;menu
    link="index.php?option=com_cpanel&amp;amp;view=cpanel&amp;amp;dashboard=<replaceable>com_example.something</replaceable>"&gt;
    <replaceable>COM_EXAMPLE_MENU_TITLE_DASHBOARD</replaceable>
  &lt;/menu&gt;</emphasis>

  &lt;!-- more submenu items --&gt;
&lt;/submenu&gt;</programlisting>

        <important>
          <para>Remember that the
          <replaceable>COM_EXAMPLE_MENU_TITLE_DASHBOARD</replaceable> language
          string must be defined in your component's
          <filename>.sys.ini</filename> language file.</para>
        </important>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Super ultra secret stuff!</emphasis> Tell
        Joomla to display a Dashboard link next to your component's top-level
        menu entry. In your XML manifest you need to modify your top level
        menu item like so:</para>

        <programlisting language="xml">&lt;menu&gt;
  <emphasis role="bold">&lt;params&gt;
    &lt;dashboard&gt;com_example.something&lt;/dashboard&gt;
  &lt;/params&gt;</emphasis>
  COM_EXAMPLE
&lt;/menu&gt;

&lt;submenu&gt;
  &lt;!-- your submenu items here… --&gt;
&lt;/submenu&gt;</programlisting>

        <para>The contents of the <code>params</code> menu subkey in the XML
        manifest goes through Joomla's Registry object and ends up, serialised
        as JSON, in the <database>#__menu</database> table record's
        <database>params</database> column. The <code>dashboard</code> key
        tells Joomla to display a dashboard link next to the menu item's text.
        Its value tells Joomla <emphasis>which</emphasis> dashboard to link
        to.</para>
      </listitem>
    </itemizedlist>

    <para>It is actually a good idea using a combination of the methods above.
    The toolbar link can help lost users find their way back to the dashboard.
    While the <code>params</code> trick is cool, it only works in the default
    components side menu. If the user has customised the menu, uses an
    alternative presentation or simply visits the Components Dashboard they
    won't see the link to your component's custom dashboard, therefore you may
    need the second method (the submenu link to your dashboard) to cater for
    these use cases. What can I say? Joomla is customisable. Maybe even a bit
    <emphasis>too</emphasis> customisable.</para>

    <bridgehead>A custom menu preset for your dashboard</bridgehead>

    <para>You may have noticed that all core dashboards seem to have an
    “immutable” area at the top. This is not immutable; it's just a plain old
    module of the type <code>mod_submenu</code> set to display in the module
    style <code>none</code> (that's why you don't see the cogs button to edit
    it in the dashboard). You can of course edit this module like any other
    module in Content, Administrator Modules.</para>

    <para>It's useful that we can also do the same for our own component and
    its dashboard. However, you may notice that mod_submenu only has presets
    for core components. What about our custom component? Well, as it turns
    out, there are no hardcoded presets! Everything you see available in
    mod_submenu is, in fact, file on your site and yes, we can do the same
    thing for our own component!</para>

    <para>We need to create a custom menu preset for our component by creating
    an XML file under the
    <filename>administrator/components/com_example/presets</filename> folder.
    To get an idea of what you can do, take a look at a core preset such as
    <filename>administrator/components/com_users/presets/users.xml</filename>.</para>

    <para>The name of your menu preset XML file MUST be unique across all
    components installed in Joomla. For this reason it's recommended to name
    it after your extension. For example, com_example's menu preset would be
    <filename>administrator/components/com_example/presets/example.xml</filename>.</para>

    <para>If you need multiple presets in your component it's strongly
    recommended that their file names follow the pattern
    <filename>component_something.xml</filename>, e.g.
    <filename>administrator/components/com_example/presets/example_alternate.xml</filename>.</para>

    <tip>
      <para>Per-component menu presets can be overridden in the same way as
      view templates. For example, if you want to override the default core
      Users menu preset
      (<filename>administrator/components/com_users/presets/users.xml</filename>),
      copy it to
      <filename>administrator/templates/atum/html/com_menus/presets/users.xml</filename>
      and edit away!</para>

      <para>Since all overrides live under the same
      <filename>com_menus/presets</filename> override folder you now
      understand why their name needs to be unique across all components
      installed on your site.</para>
    </tip>

    <para>Here is a sample preset, let's say it's
    <filename>administrator/components/com_example/presets/example.xml</filename>
    (this means the preset name is <code>example</code>) .</para>

    <programlisting language="xml">&lt;?xml version="1.0"?&gt;
&lt;menu
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="urn:joomla.org"
  xsi:schemaLocation="urn:joomla.org menu.xsd"
&gt;
  &lt;menuitem
    title="COM_EXAMPLE_MENUS_CONTENT"
    type="heading"
    icon="none fa-feather-alt"
  &gt;
    &lt;menuitem
      title="JCATEGORIES"
      type="component"
      element="com_categories"
      link="index.php?option=com_categories&amp;amp;view=categories&amp;amp;extension=com_example"
      quicktask="index.php?option=com_categories&amp;amp;extension=com_example&amp;amp;task=category.add"
      quicktask-title="COM_EXAMPLE_MENUS_NEW_CATEGORY"
    /&gt;

    &lt;menuitem
      title="COM_EXAMPLE_MENUS_ITEMS"
      type="component"
      element="com_example"
      link="index.php?option=com_example&amp;amp;view=items"
      quicktask="index.php?option=com_example&amp;amp;task=item.add"
      quicktask-title="COM_EXAMPLE_MENUS_NEW_ITEM"
    /&gt;
  &lt;/menuitem&gt;
&lt;/menu&gt;</programlisting>

    <para>Here are some <emphasis role="bold">practical</emphasis>
    tips:</para>

    <itemizedlist>
      <listitem>
        <para>The icon attribute sets the CSS class for the heading by
        combining the literal string <code>icon-</code> with the value of the
        attribute. The number of icons available that way is minuscule
        compared to the plethora of icons available in FontAwesome 5 Free.
        This is why I use values for this attribute in the form <code>none
        fa-something</code>. This results in the CSS class being set to
        <code>icon-none fa-something</code>. There is no such thing as an
        <code>icon-none</code> CSS class, so that part does nothing. The next
        part, the <code>fa-something</code>, is where I tell the browser to
        use one of the available FontAwesome icons.</para>
      </listitem>

      <listitem>
        <para>The <code>quicktask</code> and <code>quicktask-title</code>
        attributes set up the little quick action icon next to the menu item
        text. By default, this is a plus icon, implying that you can add an
        item. You can customise that icon using the attribute
        <code>menu-quicktask-icon</code> which works in the exact same way as
        a heading's <code>icon</code> attribute.</para>

        <para>Why would you want to customise it? Well, let's say you have a
        security component with a view called Automatically Blocked IP
        Addresses. It would not make sense to manually add a new entry — since
        they are <emphasis>automatically</emphasis> blocked — but it would
        totally make sense to have a quick action to
        <emphasis>unblock</emphasis> an accidentally blocked IP address. In
        this case a more appropriate icon would be
        <code>fa-unlock</code>.</para>
      </listitem>
    </itemizedlist>

    <bridgehead>Creating and publishing the custom dashboard menu module,
    automatically</bridgehead>

    <para>All right. We have a dashboard. We have a menu item to access it. We
    have a custom menu to display in a mod_submenu module inside the
    dashboard. But how exactly do we get to create this kind of module? We
    can't possibly ask our users to create it manually, that would
    suck!</para>

    <para>The answer is that Joomla gives us ALMOST everything we need to
    create that module in our component's installation script.</para>

    <para>First, let's make sure our component does use an installation
    script. In the XML manifest we need to add a line like this, as we're
    familiar from Joomla 3:</para>

    <programlisting language="xml">&lt;scriptfile&gt;script.example.php&lt;/scriptfile&gt;</programlisting>

    <para>The <code>script.example.php</code> will contain our component
    installation script. You are familiar with that; it's been around since
    Joomla 1.0.</para>

    <para>What you may not have picked up is that since Joomla 3.6 there's a
    superclass our installation script can extend from. In Joomla 3 it was
    called <classname>JInstallerScript</classname>, in Joomla 4 it's
    <classname>Joomla\CMS\Installer\InstallerScript</classname> (the old name
    will work up to and including Joomla 5.3). We'll get into more detail on
    it <link linkend="com-installation-script">in the installation script
    section</link>.</para>

    <para>Joomla's InstallerScript provides a handy method called
    <methodname>addDashboardMenu</methodname> which creates a
    <code>mod_submenu</code> module to a specific dashboard using a specific
    menu preset. However, the way it is written it assumes that it will only
    ever be executed once, the first time you install a component. What about
    hundreds of third party components which have been around long before
    Joomla 4? Don't worry, we have a solution! We will install the module if
    and only if it's missing, regardless of whether this is a new installation
    or an update.</para>

    <para>Here's how to do that:</para>

    <programlisting language="php">&lt;?php
defined('_JEXEC') || die;

use Joomla\CMS\Factory;
use Joomla\CMS\Installer\Adapter\PackageAdapter;
use Joomla\CMS\Installer\InstallerScript;

class <emphasis role="bold">Com_ExampleInstallerScript</emphasis> extends InstallerScript
{
  /**
   * Called after any type of installation / uninstallation action.
   *
   * @param   string          $type    Which action is happening (install|uninstall|discover_install|update)
   * @param   PackageAdapter  $parent  The object responsible for running this script
   *
   * @return  bool
   * @since   1.0.0
   */
  public function postflight(string $type, PackageAdapter $parent): bool
  {
    // Do not run on uninstall.
    if ($type === 'uninstall')
    {
      return true;
    }

    // Install the dashboard module if necessary
    $this-&gt;conditionalInstallDashboard(<emphasis role="bold">'com-example-example', 'example'</emphasis>);

    return true;
  }

  private function conditionalInstallDashboard(string $dashboard, string $preset): void
  {
    $position = 'cpanel-' . $dashboard;

    /** @var \Joomla\Database\DatabaseDriver $db */
    $db = Factory::getContainer()-&gt;get('DatabaseDriver');
    $query = $db-&gt;getQuery(true)
      -&gt;select('COUNT(*)')
      -&gt;from($db-&gt;quoteName('#__modules'))
      -&gt;where([
        $db-&gt;quoteName('module') . ' = ' . $db-&gt;quote('mod_submenu'),
        $db-&gt;quoteName('client_id') . ' = ' . $db-&gt;quote(1),
        $db-&gt;quoteName('position') . ' = :position',
      ])
      -&gt;bind(':position', $position);

      $modules = $db-&gt;setQuery($query)-&gt;loadResult() ?: 0;

      if ($modules == 0)
      {
        $this-&gt;addDashboardMenu($dashboard, $preset);
      }
    }
  }</programlisting>

    <para>The <methodname>postflight</methodname> method is called whenever
    Joomla has finished trying to install <emphasis>or uninstall</emphasis>
    (in Joomla 3 it was only after installation!) our component and before it
    cleans up. At this point we can check if there is a module already
    installed. If not, we let Joomla's code install it.</para>

    <para>The only two things you need to change above are the parts in bold
    type: the class name to match your component's name and the parameters to
    the <methodname>conditionalInstallDashboard</methodname> method. The
    parameters are fairly obvious: the name of the dashboard (replacing the
    underscore and dot with a dash!) and the name of your menu preset which
    typically is the same as your component's name without the
    <code>com_</code> prefix.</para>

    <tip>
      <para>You can publish modules to your Dashboards by assigning them to a
      module position named something like
      <code>cpanel-com-<replaceable>example</replaceable>-<replaceable>something</replaceable></code>
      where <replaceable>example</replaceable> is the name of your component
      without <code>com_</code> and <replaceable>something</replaceable> is
      the name of your custom dashboard without the component prefix. The
      aforementioned example module corresponds to the dashboard
      <code>com_example.something</code>.</para>

      <para>Likewise, Quick Icon modules can be assigned to a custom dashboard
      by publishing them to the module position
      <code>icon-com-<replaceable>example</replaceable>-<replaceable>something</replaceable></code>
      following the same convention as above (you just replace
      <code>cpanel</code> with <code>icon</code>). Remember that Quick Icon
      modules are displayed <emphasis>above</emphasis> the other dashboard
      modules.</para>
    </tip>
  </section>

  <section xml:id="com-installation-script">
    <title>The installation script</title>

    <para>We touched a bit on the installation script when talking about <link
    linkend="com-dashboard">Dashboards</link>. But what is an installation
    script?</para>

    <para>When Joomla is installing an extension it gives us, the developers
    of the extension, the opportunity to run some custom PHP code at different
    phases of the installer execution using the different methods provided in
    our installer script (you can see all available methods in the
    <interfacename>\Joomla\CMS\Installer\InstallerScriptInterface</interfacename>
    interface):</para>

    <variablelist>
      <varlistentry>
        <term>public function preflight(string $type, InstallerAdapter
        $adapter): bool;</term>

        <listitem>
          <para>Runs before the component is installed, updated or
          uninstalled.</para>

          <para>This is where you make basic environment checks and make sure
          that the installer can proceed. Return boolean false to stop the
          installer, causing to display an error like “Extension
          <replaceable>something</replaceable>: Custom install routine
          failure.”</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>public function install(InstallerAdapter $adapter): bool;</term>

        <listitem>
          <para>Runs after your extension has been installed. This only
          happens on a clean installation, i.e. your extension was not
          previously installed.</para>

          <para>This is where you can run code which only applies to a clean
          installation, e.g. publishing modules and plugins necessary for your
          component to work.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>public function update(InstallerAdapter $adapter): bool;</term>

        <listitem>
          <para>Runs after your extension has been updated.</para>

          <warning>
            <para>“Updated” is a term used <emphasis>very loosely</emphasis>
            by Joomla. It merely means that a different version than the one
            which was previously installed on the site has been installed. It
            might be <emphasis>the same</emphasis> version (refresh) or even
            an earlier version (downgrade).</para>
          </warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>public function uninstall(InstallerAdapter $adapter):
        bool;</term>

        <listitem>
          <para>Runs after your extension has been successfully
          uninstalled.</para>

          <para>Use this to perform any necessary cleanup which could not be
          performed by Joomla removing the files and folders of your extension
          and running the uninstallation SQL files.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>public function postflight(string $type, InstallerAdapter
        $adapter): bool;</term>

        <listitem>
          <para>This runs at the very last end, before Joomla cleans up. It
          runs after the extension has been installed, updated or
          uninstalled.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>In the above methods you can see one or two parameters:</para>

    <variablelist>
      <varlistentry>
        <term>string $type</term>

        <listitem>
          <para>Whenever present it tells us which kind of operation is taking
          place:</para>

          <itemizedlist>
            <listitem>
              <para><code>install</code>. The extension is being installed
              from a package uploaded via the browser, a package downloaded
              from an HTTP/HTTPS source, the Install via Web feature or from a
              directory. This is a normal installation from scratch. The
              extension had not been previously installed.</para>
            </listitem>

            <listitem>
              <para><code>discover_install</code>. The extension is being
              installed using the Discover feature. This means that the files
              are already placed on the site but there's no guarantee that
              some files are not missing! Also note that you cannot install a
              package extension like that. If your component is part of a
              package it should return <code>false</code> in the preflight
              method to prevent a broken, non-updatable installation of your
              component to persist on the site.</para>
            </listitem>

            <listitem>
              <para><code>update</code>. Another version of your extension
              (NOT necessarily older!) was already installed on the site and
              the user is trying to install a different version.</para>
            </listitem>

            <listitem>
              <para><code>uninstall</code>. Your extension is being
              uninstalled.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>InstallerAdapter $adapter</term>

        <listitem>
          <para>This is an instance of the
          <classname>\Joomla\CMS\Installer\InstallerAdapter</classname>
          subclass handling the installation, update or uninstallation of your
          extension. For components, that's actually an instance of the
          <classname>\Joomla\CMS\Installer\Adapter\ComponentAdapter</classname>
          class.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>To use an installation script you have to declare it in your
    extension's XML manifest. For example:</para>

    <programlisting language="xml">&lt;scriptfile&gt;script.example.php&lt;/scriptfile&gt;</programlisting>

    <para>The file must be included with your extension's XML manifest at the
    archive's root.</para>

    <para>The <code>script.example.php</code> file will contain our extension
    installation script. You are familiar with that; it's been around since
    Joomla 1.0.</para>

    <para>Since Joomla 3.6 there's a superclass our installation script can
    extend from. In Joomla 3 it was called
    <classname>JInstallerScript</classname>, in Joomla 4 it's
    <classname>Joomla\CMS\Installer\InstallerScript</classname> (the old name
    will work up to and including Joomla 5.3). When your script extends from
    this class you can unlock a lot of useful functionality.</para>

    <note>
      <para>This class is actually a fork of the <link
      xlink:href="https://github.com/akeeba/fof/blob/fof-2.x/fof/utils/installscript/installscript.php">F0FUtilsInstallscript
      class</link> I had introduced in FOF since 2014 and maintained until
      2021, when FOF officially became obsolete and I moved all my development
      to Joomla core MVC. The fork was contributed by George Wilson in 2016 —
      he had already asked me for permission to fork some useful bits of FOF 2
      as it was going to be EOL in June that year. Just an aside, so that you
      know that Joomla and 3PDs have a symbiotic relationship; <emphasis>we
      help each other survive</emphasis>.</para>
    </note>

    <bridgehead>Minimum Joomla and PHP versions</bridgehead>

    <para>The installation script can automatically enforce a minimum Joomla
    and / or PHP version for your extension. If the minimum requirements are
    not met the installation or upgrade will abort with the aforementioned
    error. You can do that by setting the relevant properties in your
    class:</para>

    <programlisting language="php">// The extension will only install on PHP 8.0.0 or later
protected $minimumPhp = '8.0.0';

// The extension will only install on Joomla 4.2.0 or later
protected $minimumJoomla = '4.2.0';</programlisting>

    <bridgehead>Handling downgrades</bridgehead>

    <para>As mentioned earlier, Joomla uses the term “upgrade” very loosely.
    If you install any version of your extension while another (or the same!)
    version is already installed Joomla will happily oblige and call it an
    “upgrade”. However, most extensions cannot <emphasis>downgrade</emphasis>
    cleanly, i.e. going from version 2.0.0 to version 1.9.3 may not work at
    all. This makes perfect sense. You cannot possibly travel back in time to
    update the installation script of your extension's older versions to make
    a downgrade possible — if it's even at all possible. Therefore, <emphasis
    role="bold">by default, the installation script will prevent
    downgrades</emphasis>. Users can only install the same or a newer version
    of your software.</para>

    <warning>
      <para>Preventing downgrades will only work properly if your extension
      uses <link xlink:href="https://semver.org">Semantic Versioning
      (SemVer)</link>. Your development / nightly releases must additionally
      follow <link
      xlink:href="https://www.php.net/manual/en/function.version-compare.php">PHP's
      versioning rules</link>. That is to say, a development / nightly release
      coming after the official release of version 1.2.3 must be named
      something like 1.2.<emphasis
      role="bold">4</emphasis>-dev-20220914.</para>
    </warning>

    <para>There are cases where you might not want to do that. Simpler
    extensions may support downgrades, or you may have implemented some
    solution which allows you to perform downgrades (e.g. you may have added a
    custom file in every new release to handle downgrades to a previous
    version). Or you may just not use semantic versioning and you'd rather
    implement your custom logic to determine when something is a downgrade or
    not. In this case set this in your installer class:</para>

    <programlisting language="php">protected $allowDowngrades = true;</programlisting>

    <bridgehead>Removing obsolete folders and files</bridgehead>

    <para>As we progress through versions of our software we have to contend
    with the fact that some code becomes obsolete and needs to be removed,
    Joomla has changed leading to moved files, or we might even need to
    refactor code and move things around. This means that we have files and
    folders which need to be removed on upgrade.</para>

    <para>Joomla will automatically remove folders and files explicitly listed
    in the XML manifest of the installed version but not on the new version's
    XML manifest. This means that only, for example, top level component
    folders are removed on update. If you have a few specific files, e.g. some
    obsolete view template files, or folders deeper inside the directory
    structure they will not be automatically removed.</para>

    <para>The $deleteFiles and $deleteFolders properties allow you to specify
    which files and folders need to be removed, if they exist, on
    update.</para>

    <para>Please remember that you need to call the
    <methodname>removeFiles</methodname> method directly from your
    <methodname>postflight</methodname> method.</para>

    <para>Example for setting these variables:</para>

    <programlisting language="php">protected $deleteFiles = [
  'components/com_example/tmpl/welcome/default_donate.php',
  'administrator/components/com_example/tmpl/item/default_phpwarning.php',
];

protected $deleteFolders = [
  'media/com_example/icons',
];</programlisting>
  </section>

  <section xml:id="com-menus">
    <title>Component menus</title>

    <para>When we are talking about component menus, what comes in mind?
    Usually it's just the user's ability to create menu items to specific
    views of your component in the frontend of the site.</para>

    <para>Joomla components are much more than that. To begin with, the XML
    manifest defines the default component menu and its submenu items. As
    we've already learned, this can be augmented with customisable Dashboards
    (introduced in Joomla 4.0) to help site integrators tailor the backend
    experience of their clients as they wish. Ever <link
    xlink:href="https://www.joomla.org/announcements/release-news/5664-joomla-3-6-is-here.html">since
    Joomla 3.6</link> it's possible to apply permissions (ACL rules) to
    backend menu items to modify the submenu items in a way which makes more
    sense depending on who is logged in.</para>

    <para>Moreover, ever <link
    xlink:href="https://www.joomla.org/announcements/release-news/5703-joomla-3-7-is-here.html">since
    Joomla 3.7</link>, it is possible to have a custom backend menus. This is
    one more way for site integrators to fully customise the backend
    experience of their clients, using menu titles which make sense in the
    business context they are going to be used instead of the much drier,
    purely functional and very technical language core Joomla and us third
    party developers use.</para>

    <para>All these features are linked to and defined by the components
    installed on the site, core and third party. Let's see how you can make
    the magic happen.</para>

    <section xml:id="com-menus-component">
      <title>The default component menu</title>

      <para>The default component menu is what appears in Joomla's main menu
      (the sidebar) under the Components menu item. You define this menu in
      your component's XML manifest, under the
      <code>&lt;administration&gt;</code> section. Joomla <link
      xlink:href="https://docs.joomla.org/Manifest_files#Menu_Links_and_Submenus">has
      some partial documentation</link> on how that works.</para>

      <para>At the very least, every component needs to have the top level
      item, a <code>&lt;menu&gt;</code> tag directly under the
      <code>&lt;administration&gt;</code> section. This controls how your
      component will appear in the <guimenu>Components</guimenu> menu.</para>

      <para>If you want a sub-menu under your top level item you need to also
      add a <code>&lt;submenu&gt;</code> tag at the same level as the
      <code>&lt;menu&gt;</code> tag. Unlike the menu tag, this one does not
      have any attributes. However, it can contain one or more
      <code>&lt;menu&gt;</code> tags, one per sub-menu item.</para>

      <important>
        <para>If you define a sub-menu then the top level menu item becomes a
        toggle for the sub-menu and cannot be clicked. For this reason you
        will have to duplicate the top level link as a sub-menu item.</para>
      </important>

      <note>
        <para>It is possible to have third (or more) level sub-menus by
        nesting <code>&lt;menu&gt;</code> tags. <emphasis>Just because you can
        doesn't mean you should</emphasis>. Multi-level menus are
        user-hostile, especially when the available width to display their
        label is ever shrinking the deeper you go into the menu
        structure.</para>

        <para>If you find yourself even considering a multi-level menu, you're
        doing something wrong. Try creating a dashboard instead or otherwise
        group the functionality of your component so it doesn't rely on a
        byzantine menu structure.</para>
      </note>

      <para>A very simple extension menu would look like this in your XML
      manifest (as per the Joomla documentation):</para>

      <programlisting language="xml">&lt;menu&gt;COM_EXAMPLE&lt;/menu&gt;
&lt;submenu&gt;
  &lt;!--
  Note that all &amp; must be escaped to &amp;amp; for the file to be valid
  XML and be parsed by the installer
  --&gt;
  &lt;menu link="anoption=avalue&amp;amp;anoption1=avalue1"&gt;COM_EXAMPLE_SUBMENU_ANOPTION&lt;/menu&gt;
  &lt;menu view="viewname"&gt;COM_EXAMPLE_SUBMENU_VIEWNAME&lt;/menu&gt;
&lt;/submenu&gt;</programlisting>

      <para>This does not tell you the whole truth and is actually a partial,
      confusing and harmful representation of what Joomla can do. Here is a
      more realistic example:</para>

      <programlisting language="xml">&lt;menu&gt;
  &lt;params&gt;
    &lt;dashboard&gt;com_example.something&lt;/dashboard&gt;
  &lt;/params&gt;
  COM_EXAMPLE
&lt;/menu&gt;

&lt;submenu&gt;
&lt;!--
Note that all &amp; must be escaped to &amp;amp; for the file to be valid
XML and be parsed by the installer
--&gt;
  &lt;menu view="welcome"&gt;COM_EXAMPLE_MENUS_WELCOME&lt;/menu&gt;

  &lt;menu link="index.php?option=com_categories&amp;amp;extension=com_example"&gt;
    &lt;params&gt;
      &lt;menu-permission&gt;core.manage;com_categories&lt;/menu-permission&gt;
      &lt;menu-quicktask&gt;index.php?option=com_categories&amp;amp;task=category.add&amp;amp;extension=com_example&lt;/menu-quicktask&gt;
      &lt;menu-quicktask-title&gt;COM_EXAMPLE_MENUS_ADD_CATEGORY&lt;/menu-quicktask-title&gt;
      &lt;menu-quicktask-permission&gt;core.create;com_categories&lt;/menu-quicktask-permission&gt;
    &lt;/params&gt;
    JCATEGORIES
  &lt;/menu&gt;

  &lt;menu view="items"&gt;
    &lt;params&gt;
      &lt;menu-permission&gt;core.manage;com_example&lt;/menu-permission&gt;
      &lt;menu-quicktask&gt;index.php?option=com_example&amp;amp;task=item.add&lt;/menu-quicktask&gt;
      &lt;menu-quicktask-title&gt;COM_EXAMPLE_MENUS_ADD_ITEM&lt;/menu-quicktask-title&gt;
      &lt;menu-quicktask-permission&gt;core.create;com_example&lt;/menu-quicktask-permission&gt;
    &lt;/params&gt;
    COM_EXAMPLE_MENUS_ITEMS
  &lt;/menu&gt;
&lt;/submenu&gt;</programlisting>

      <para>Woah! It's pretty substantially different. This is a better
      example because it shows you all the interesting and insanely powerful
      things you can do with the humble component menu. Let's take it easy,
      break it down to individual bits and pieces and it will all become
      crystal clear, I promise!</para>

      <bridgehead>An x-ray of the <code>&lt;menu&gt;</code> tag</bridgehead>

      <para>Every <code>&lt;menu&gt;</code> tag consist of:</para>

      <itemizedlist>
        <listitem>
          <para>Zero or more attributes. These determine what kind of link the
          rendered menu item will produce.</para>
        </listitem>

        <listitem>
          <para>A single, but optional ,<code>&lt;params&gt;</code> element
          with one or more child elements. These are menu parameters which are
          used to define menu item access (ACL permissions), whether the menu
          item should display a Dashboard link and whether the menu item
          should display a quick action button next to it.</para>
        </listitem>

        <listitem>
          <para>Text content, e.g. <code>COM_EXAMPLE_MENUS_WELCOME</code>.
          This is a language string which is used to translate the menu item's
          title in the user's language.</para>

          <note>
            <para>The language strings for the component menu items' titles
            are in the backend system language file, i.e.
            <filename>com_example.sys.ini</filename> for a
            <code>com_example</code> component.</para>
          </note>

          <warning>
            <para>Do <emphasis role="bold">not</emphasis> use
            <code>&lt;img&gt;</code> or <code>&lt;span&gt;</code> tags in your
            language strings to display icons. <emphasis>Some major Joomla
            extension developers should know better than do that, and
            yet…</emphasis></para>

            <para>There are the <code>menu_icon</code> and
            <code>menu_image</code> parameters to do that correctly, if you
            really need to. Using a tag at the beginning of your language
            string breaks alphabetical sorting of the Components menu, making
            it much harder for end users to navigate it. Finally, as we will
            see further below, using iconography in menus is a bad idea
            anyway.</para>
          </warning>
        </listitem>
      </itemizedlist>

      <bridgehead>The <code>&lt;menu&gt;</code> attributes</bridgehead>

      <para>Each menu tag can have a combination of the following
      attributes:</para>

      <variablelist>
        <varlistentry>
          <term>type</term>

          <listitem>
            <para>Normally not set. You can set it to <code>separator</code>.
            In this case do <emphasis role="bold">not</emphasis> set a
            <code>link</code> or <code>view</code> attribute; the text content
            of the menu item will be rendered as a non-linked header in the
            menu structure.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>target</term>

          <listitem>
            <para>Only applies if you are using the <code>link</code>
            attribute. Corresponds to the <code>&lt;a&gt;</code> HTML tag's
            <code>target</code> attribute. Useful if you want to create a menu
            item linking to an external site and you'd like to open it in a
            new tab / window; in this case set
            <code>target="_blank"</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>link</term>

          <listitem>
            <para>A link the browser will navigate to. You should ideally only
            use this to point to pages of components other than yours, e.g.
            <uri>index.php?option=com_categories&amp;extension=com_example</uri>
            to display the categories management interface through Joomla's
            <code>com_categories</code> core component.</para>

            <para>Note that a link pointing to another page in the site's
            backend is relative to <uri>/administrator</uri>. <emphasis>Do
            not</emphasis> put <uri>/administrator</uri> in front, though;
            this would break the menu for sites which are installed in
            subdirectories.</para>

            <para>This attribute is mutually exclusive with <code>view</code>.
            If both are set, <code>link</code> will be applied.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>view</term>

          <listitem>
            <para>The view of the current component you want to link
            to.</para>

            <para>For example, if we are in the XML manifest of the
            <code>com_example</code> component and you set
            <code>view="welcome"</code> it's the same as if you had used
            <code>link="index.php?option=com_example&amp;view=welcome"</code>.</para>

            <para>This attribute is mutually exclusive with <code>link</code>.
            If both are set, <code>link</code> will be applied.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>ajaxbadge</term>

          <listitem>
            <para>While you will normally only see that in menu presets used
            in Dashboards, this is perfectly supported in the component's menu
            as well.</para>

            <para>When set, a badge will appear next to the title. Joomla will
            perform an AJAX request to the URL provided in the value of this
            attribute. This URL is supposed to return a JSON document with the
            following keys:</para>

            <programlisting language="json">{
  "success": true,
  "error": "",
  "data": "something"
}</programlisting>

            <para>If the <code>success</code> key is true Joomla will take the
            <code>data</code> key's value, sanitise its HTML (only allowing a
            subset of tags and attributes you can find in the
            <filename>build/media_source/system/js/core.es6.js</filename> file
            in Joomla's repository) and put that sanitised HTML in the
            badge.</para>

            <para>This is typically used to display the number of items which
            require attention.</para>

            <warning>
              <para>Do not go overboard with this feature! This AJAX request
              will run on every page of your site's backend, slowing
              everything down. I have not yet seen a
              <emphasis>practical</emphasis> use case where this is even
              remotely acceptable.</para>
            </warning>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Despite what the Joomla documentation wants you to believe, there
      is neither an <code>alt</code> nor an <code>img</code> attribute; these
      existed in Joomla 2.5 and earlier. But there are so many more attributes
      not mentioned in there.</para>

      <bridgehead>The &lt;menu&gt; parameters</bridgehead>

      <para>As we mentioned earlier, the <code>&lt;menu&gt;</code> tag can
      include an optional <code>&lt;params&gt;</code> tag which, in its turn,
      contains a number of tags. Everything under <code>&lt;params&gt;</code>
      is parsed as parameters to the menu item. The tag name is the parameter
      key and its contents is the parameter's value.</para>

      <para>Here are the supported tag names I've discovered by
      reverse-engineering the code of the backend <code>mod_menu</code>
      module:</para>

      <variablelist>
        <varlistentry>
          <term>dashboard</term>

          <listitem>
            <para>If set, it creates a dashboard icon next to the menu item's
            title, linking to the named dashboard.</para>

            <para>Example:
            <code>&lt;dashboard&gt;com_example.example&lt;/dashboard&gt;</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu-permission</term>

          <listitem>
            <para>The Joomla ACL permission the user needs to have to see this
            menu item (and all its sub-items, if any).</para>

            <para>To use global permissions (set in the Permissions tab of
            Global Configuration) use the format
            <code>&lt;menu-permission&gt;core.manage&lt;/menu-permission&gt;</code></para>

            <para>To use component-level permissions (set in the Permissions
            tab of a component) use the format
            <code>&lt;menu-permission&gt;core.manage;com_example&lt;/menu-permission&gt;</code></para>

            <para>You can NOT ask Joomla to combine multiple permissions i.e.
            you cannot ask it to only display a menu item if two or more
            permissions are simultaneously granted; or if one of several
            permissions is granted. The reason for that can be found in the
            code of
            <code>\Joomla\Module\Submenu\Administrator\Menu\Menu::preprocess</code>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu-quicktask</term>

          <listitem>
            <para>Menu items can have an optional “quick task” shown next to
            them. This is a small button with an icon and no visible text (the
            text is only made available to users of assistive technologies for
            accessibility reasons). The value of this parameter is the URL to
            visit when the quick task button is used. It follows the same
            rules as the <code>link</code> attribute.</para>

            <para>Example:
            <code>&lt;menu-quicktask&gt;index.php?option=com_example&amp;amp;task=item.add&lt;/menu-quicktask&gt;</code></para>

            <note>
              <para>While this is <emphasis>typically</emphasis> used to
              render a [+] icon button to add new items, this is not
              necessary. You can use whatever action feels right in context
              and whichever icon you think is appropriate for the
              action.</para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu-quicktask-icon</term>

          <listitem>
            <para>The icon class for the quick task. If it's not specified it
            will default to <code>plus</code>.</para>

            <para>The contents of this parameter are prefixed with the string
            literal <code>icon-</code> to create the HTML <code>class</code>
            attribute. For example,
            <code>&lt;menu-quicktask-icon&gt;cog&lt;/menu-quicktask-icon&gt;</code>
            will result in <code>class="icon-cog"</code> which displays a cog
            wheel icon.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu-quicktask-title</term>

          <listitem>
            <para>A language string which describes the quick task to users of
            assistive technologies (e.g. screen readers, Braille displays, …).
            If not defined, the language string
            <code>MOD_MENU_QUICKTASK_NEW</code> (New Item) will be
            used.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu-quicktask-permission</term>

          <listitem>
            <para>Equivalent to menu-permission but applies to the quick task
            instead. Use this to limit who should be able to view the quick
            task icon.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu_image</term>

          <listitem>
            <para>The (relative) URL to an image file to use for the menu
            item.</para>

            <para>This is mutually exclusive with the <code>menu-icon</code>
            parameter.</para>

            <note>
              <para>It is generally bad form using images for menu
              items.</para>

              <para>Images, especially raster (bitmap) images, may not display
              very well and make the backend of the site look cheap and
              unprofessional.</para>

              <para>Images, unlike language strings, are untranslatable and
              cannot be replaced for different languages and cultures.
              Iconography with vector images may have radically different
              meanings depending on the cultural context and personal
              circumstances. For example, an open palm facing the user with
              fingers spread out means "stop" in the USA but is a vulgar
              gesture in Greece and Cyprus (it literally means “I spread feces
              on your face”). A beer mug is a relatively inoffensive icon
              unless you're putting that in front of Muslims who are required
              to abstain from alcohol per their religion or recovering
              alcoholics (or those who've lost a loved one to a DUI fatal
              accident) who may find that iconography triggering.</para>

              <para>You <emphasis role="bold">MUST NOT</emphasis> use an icon
              instead of human-readable text content for the title of the menu
              item. This is inaccessible to people with disabilities such as
              hard-of-seeing or blind people, people with cognitive
              disabilities etc.</para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>menu_icon</term>

          <listitem>
            <para>When provided it will set the menu item's icon class to the
            string literal <code>class-</code> followed by the contents of
            this parameter. For example,
            <code>&lt;menu-image&gt;cog&lt;menu-image&gt;</code> will result
            in <code>class="icon-cog"</code> being applied to the menu item's
            icon <code>&lt;span&gt;</code> tag.</para>

            <para>This is mutually exclusive with the <code>menu_image</code>
            parameter.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>text_separator</term>

          <listitem>
            <para>Only applies when the <code>type="separator"</code>
            attribute is used. When set to 1 it will render the separator as
            an <code>&lt;hr&gt;</code> tag instead of text.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section xml:id="com-menus-backend">
      <title>Backend menu items</title>

      <para>Joomla 3.7 and later allow site integrators to create custom
      backend menus. This lets them fully customise the backend experience of
      Joomla for their clients, e.g. using terms which are more in-line with
      the purpose the menu items will be used instead of the more functional
      and technical terms the Joomla core and us third party developers
      use.</para>

      <para>If you do not do anything else, Joomla will simply list all of
      your <link linkend="com-menus-component">component's default menu
      items</link>, as they are defined in your XML manifest. This is the
      simplest way to do things, but it's not very configurable. Menu items
      created like that just take the user to the relevant view of your
      component.</para>

      <para>The other option you have is to create menu item configuration XML
      files in your backend <filename>tmpl</filename> folder's sub-folders.
      This is a lot like managing <link linkend="com-menus-frontend">frontend
      menu items</link>, with a few extra features.</para>

      <bridgehead>View XML files location and name</bridgehead>

      <para>Your view XML files are placed in the sub-folders of your
      <filename>tmpl</filename> folder and they are named after the view
      template file. For example, if you have a component
      <code>com_example</code>, a view named <code>welcome</code> and a view
      template for that view named <code>default</code> the view XML file
      would be
      <filename>administrator/components/com_example/tmpl/welcome/default.xml</filename>.</para>

      <bridgehead>View XML file structure</bridgehead>

      <para>A view XML file has the following overall structure:</para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;metadata&gt;
  &lt;layout title="COM_EXAMPLE_WELCOME_VIEW_DEFAULT_TITLE"&gt;
    &lt;message&gt;COM_EXAMPLE_WELCOME_VIEW_DEFAULT_DESC&lt;/message&gt;
  &lt;/layout&gt;
  &lt;!-- Add fields to the request variables for the layout. --&gt;
  &lt;fields name="request"&gt;
    &lt;fieldset
      name="request"
    &gt;
      &lt;field
        name="something"
        type="text"
        label="COM_EXAMPLE_WELCOME_VIEW_OPTION_SOMETHING_LABEL"
        description="COM_EXAMPLE_WELCOME_VIEW_OPTION_SOMETHING_DESC"
        /&gt;
    &lt;/fieldset&gt;
  &lt;/fields&gt;
  &lt;fields name="params"&gt;
    &lt;fieldset name="basic"&gt;
      &lt;field
        name="menu-quicktask"
        type="radio"
        label="MOD_MENU_FIELD_SHOWNEW"
        layout="joomla.form.field.radio.switcher"
        &gt;
          &lt;option value=""&gt;JHIDE&lt;/option&gt;
          &lt;option value="index.php?option=com_example&amp;amp;task=item.add"&gt;JSHOW&lt;/option&gt;
      &lt;/field&gt;

      &lt;field
        name="menu-quicktask-title"
        type="hidden"
        default="COM_EXAMPLE_MENUS_NEW_ITEM"
        /&gt;
    &lt;/fieldset&gt;
  &lt;/fields&gt;
&lt;/metadata&gt;            </programlisting>

      <para>The root tag of the XML document is always
      <code>&lt;metadata&gt;</code>. The <code>&lt;layout&gt;</code> section
      is mandatory. The <code>&lt;fields&gt;</code> sections are
      optional.</para>

      <bridgehead>The <code>&lt;layout&gt;</code> section</bridgehead>

      <para>This section tells Joomla how to display the available menu item
      type to the site integrator when they are creating a custom backend menu
      item.</para>

      <para>The <code>title</code> attribute contains a language string which
      appears as the title of the menu type selector and in the <guilabel>Menu
      Item Type</guilabel> option of the menu item's edit page. Keep it short
      and to the point. Do not include the component's name in it unless it's
      absolutely necessary for disambiguation. In this case, you may want to
      use something like “Clear Cache (Example)”, i.e. put the component's
      name in parentheses after the view title.</para>

      <note>
        <para>When writing messages keep in mind the constraints of the human
        working memory. Short, to the point messages work best. There's less
        for the human operator to keep in their working memory. Put the
        important part first (message front-loading). That's why it makes
        sense to put the component name in parentheses at the end of the
        title; it's not as important as <emphasis>what the menu item
        does</emphasis>.</para>
      </note>

      <para>The content of the <code>&lt;layout&gt;</code> tag can either be
      empty or contain exactly one <code>&lt;message&gt;</code> tag with a
      text content which is also a language string key<footnote>
          <para>Core components put the language string key inside a
          <code>&lt;![CDATA[…]]&gt;</code> wrapper. This is not necessary
          since Joomla 1.6. Language string keys are meant to only consist of
          uppercase, unaccented Latin letters without diacritics and
          underscores. These characters are allowed as the text value of an
          XML node. The CDATA wrapper is a leftover from Joomla 1.5 when the
          language string key was an entire English phrase, possibly
          containing characters not allowed in an XML document without being
          converted to entities.</para>
        </footnote>. This is a slightly longer description of what the view
      does. It is displayed in the view type selector right under the title.
      If you need to provide a description keep it short and do not repeat
      what can already be obviously inferred by reading the view title.</para>

      <bridgehead>The request &lt;fields&gt; section</bridgehead>

      <para>The XML file can have one or more <code>&lt;fields&gt;</code>
      sections. The first section we see in the example above are the request
      fields, wrapped in a <code>&lt;fields name="request"&gt;</code> tag.
      These define configuration parameters which will be present in the menu
      item's URL as GET parameters (i.e. part of the URL itself). The name of
      the URL parameter is the <code>name</code> attribute of the field tag
      and its value will be the URL parameter's value as well.</para>

      <para>This section contains exactly one <code>&lt;fieldset&gt;</code>
      tag with <code>name="request"</code>. The fields in this set will be
      displayed in the <guilabel>Details</guilabel> tab of the menu item edit
      page.</para>

      <para>Remember that if you do not define any fields or omit this section
      altogether the resulting link will be
      <uri>index.php?option=com_example&amp;view=something&amp;layout=default</uri>
      where <code>com_example</code> is the name of your component,
      <code>something</code> is the name of the view (the name of the
      subfolder the XML file is in) and <code>default</code> is the name of
      the XML file without the .xml extension.</para>

      <tip>
        <para>If you want to provide GET URL parameters the user cannot modify
        use field tags with <code>type="hidden"</code>.</para>
      </tip>

      <bridgehead>The parameters &lt;fields&gt; section</bridgehead>

      <para>The next optional section is wrapped in a <code>&lt;fields
      name="params"&gt;</code> tag and has one or more
      <code>&lt;fieldset&gt;</code> tags, rendered as tabs in the menu item
      edit page. If you do not specify a title and name your field set
      <code>basic</code> it will render as a tab labelled
      <guilabel>Options</guilabel>.</para>

      <para>While the request fields modify the URL generated by the menu
      link, the parameter fields modify how Joomla will display the menu item
      itself in the backend menu. The are the same as the
      <code>&lt;params&gt;</code> tags in the component's menu and, in fact,
      have the same names — so we're not copying the documentation here
      again.</para>
    </section>

    <section xml:id="com-menus-frontend">
      <title>Frontend menu items</title>

      <para>Creating menu item types for frontend menus is pretty much the
      same <link linkend="com-menus-backend">as with backend menus</link> with
      a few key differences:</para>

      <itemizedlist>
        <listitem>
          <para>The files go into the frontend view templates' directories
          e.g.
          <filename>components/com_example/tmpl/welcome/default.xml</filename>.</para>
        </listitem>

        <listitem>
          <para>The frontend menu item parameters do not control the display
          of the menu item, they are passed to the View object and have
          component-specific meaning.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section xml:id="com-data-to-frontend">
    <title>Passing data from the backend to the JavaScript on the page</title>

    <para>Back in the early Joomla 3 days we used to send data to the frontend
    JavaScript code using inline JavaScript fragments. For example:</para>

    <programlisting language="php">JFactory::getDocument()-&gt;addScriptDeclaration(&lt;&lt;&lt;JS
  var comExampleSomething = "{$foobar}";
JS
);</programlisting>

    <para>On the client side (JavaScript) you'd just use this JavaScript
    variable.</para>

    <para>This is bad for a number of reasons. To begin with, the inline
    script declaration must definitely be parsed before any other code —
    including JavaScript files — which make use of it. Back when all scripts
    were loaded in the document's <code>&lt;head&gt;</code> that was a given.
    However, this code broke spectacularly when met with any plugin or third
    party solution (such as CloudFlare RocketLoader) which moved the scripts
    at the bottom of the HTML <code>&lt;body&gt;</code> or lazy-loaded them.
    There was no guaranteed script execution anymore.</para>

    <para>The variable being passed (in our example, <code>$foobar</code>)
    would have to be properly escaped to make it valid JavaScript or the
    client-side could break or, worse, we'd introduce a security
    vulnerability!</para>

    <para>Moreover, this solution pollutes the JavaScript global scope and
    slows down the page as the browser has to stop parsing the DOM and
    rendering the page to evaluate the JavaScript.</para>

    <para>Ever since Joomla 3.5 you had the option to instead push script
    options through the document:</para>

    <programlisting language="php">\Joomla\CMS\Factory::getDocument()-&gt;addScriptOptions(
  'com_example',
  [
    'foo' =&gt; $foobar,
    'bar' =&gt; SOME_CONSTANT,
  ]
);</programlisting>

    <para>This embeds a JSON document into the HTML which does not need to be
    parsed by the browser as JavaScript. Instead, when the core JavaScript
    loads it will parse it and make it available to our client-side
    code:</para>

    <programlisting language="javascript">var comExampleOptions = Joomla.getOptions('com_example');
var distance = comExampleOptions.foo * comExampleOptions.bar;</programlisting>

    <para>But how can we be sure that our code loads after the core Joomla
    JavaScript? Well, this is trivial in Joomla 4 and later by using the <link
    linkend="concepts-webassetmanager">WebAssetManager</link> and adding
    <code>core</code> as a dependency. We also need to set our script to have
    the option <code>"defer": true</code> in our
    <filename>joomla.asset.json</filename> file so it loads deferred, i.e.
    after the browser parses the DOM — just like the core JavaScript does.
    This way we can be sure that our file executes after
    <code>Joomla.getOptions</code> is available in JavaScript and we no longer
    need to add special code to execute our code after the page has finished
    loading; both conditions are guaranteed.</para>
  </section>

  <section xml:id="com-lang">
    <title>Language files</title>

    <para>The Joomla language files have not really changed much since Joomla
    1.0. Joomla is using the <link
    xlink:href="https://en.wikipedia.org/wiki/INI_file">INI format</link> with
    a few twists:</para>

    <itemizedlist>
      <listitem>
        <para>The keys must always be in UPPERCASE. You cannot have keys in
        lowercase or MixedCase.</para>
      </listitem>

      <listitem>
        <para>The values to the right of the equals sign must be enclosed in
        double quotes (<code>"</code>).</para>
      </listitem>

      <listitem>
        <para>If you want to use double quotes inside your values you need to
        escape them as <code>\"</code>.</para>
      </listitem>

      <listitem>
        <para>Some language strings are used in JavaScript code using a legacy
        method. They do not support escaped double quotes. Use single quotes
        (<code>'</code>) instead, even for HTML attributes (yes, HTML allows
        you to do things like <code>&lt;a
        href='https://www.example.com'&gt;example&lt;/a&gt;</code> even though
        attribute values <emphasis>should</emphasis> use double quotes for
        compatibility with XHTML). If you want to put quotes around
        human-readable text you can also use calligraphic quotes: <code>“ ” ‘
        ’</code> and so on.</para>
      </listitem>

      <listitem>
        <para>You can comment a line by putting a semicolon (<code>;</code>)
        as its first character. Do not put semicolons at the end of strings,
        they might be parsed as part of the value.</para>
      </listitem>
    </itemizedlist>

    <bridgehead>No more language tags in filenames</bridgehead>

    <para>There is a pretty big change for language file
    <emphasis>naming</emphasis> in Joomla 4 and beyond: <emphasis
    role="bold">you must not use the language prefix</emphasis>.</para>

    <para>In Joomla 1.5 to 3.10 inclusive language files were named like
    <filename>en-GB.com_example.ini</filename> (British English),
    <filename>de-DE.com_example.ini</filename> (German, Germany) and
    <filename>de-AT.com_example.ini</filename> (German, Austria).</para>

    <para>However, that naming was highly redundant as starting with Joomla
    1.6 in 2010 the language files had to be placed in a folder whose name was
    the language tag itself! Inside a language folder you'd have the relative
    filepaths <filename>en-GB/en-GB.com_example.ini</filename>,
    <filename>de-DE/de-DE.com_example.ini</filename> and
    <filename>de-AT/de-AT.com_example.ini</filename>. Having the same language
    tag appear twice in a pathname didn't make sense. Therefore in Joomla 4
    and beyond we no longer use the language tag prefix!</para>

    <para>The files are now simply named similar to
    <filename>com_example.ini</filename>. The language of the file is inferred
    from the folder name it's in. For example, the filepath
    <filename>en-GB/com_example.ini</filename> obviously refers to British
    English.</para>

    <bridgehead>Component language files</bridgehead>

    <para>A component has multiple different language files. The base name of
    all files is the name of the Joomla component extension, e.g.
    <code>com_example</code>:</para>

    <itemizedlist>
      <listitem>
        <para>Backend <filename>com_example.sys.ini</filename> — System
        language file. Required. Used to render the backend menu items and
        menu item types (for both front- and backend menu items).</para>
      </listitem>

      <listitem>
        <para>Backend <filename>com_example.ini</filename> — Backend language
        file. Required. Used to render the backend interface and the
        component's Options page.</para>
      </listitem>

      <listitem>
        <para>Frontend <filename>com_example.ini</filename> — Frontend
        language file. Optional (only if your component has a frontend
        part).</para>
      </listitem>

      <listitem>
        <para>API <filename>com_example.ini</filename> — API application
        language file. Optional (only if your component has an API application
        integration).</para>
      </listitem>
    </itemizedlist>

    <para>The language files are placed in the respective application's
    <filename>language</filename> subdirectory. For example, the backend
    language files for British English are placed in
    <filename>administrator/language/en-GB</filename>. Moreover, Joomla will
    fall back to the language subdirectory under your component. For example,
    the backend language files for British English are also sought for in
    <filename>administrator/components/com_example/language/en-GB</filename>.
    If files exist in both locations then <emphasis>only</emphasis> the one in
    the application's directory will be loaded.</para>

    <bridgehead>Language file autoloading</bridgehead>

    <para>Unlike previous versions of Joomla, you do NOT have to load your
    language files manually. Joomla loads your component's language files
    automatically.</para>

    <para>Since Joomla 3.3 (based on my recollection, +/- 1 minor version…)
    Joomla will load language files in this order:</para>

    <itemizedlist>
      <listitem>
        <para>(Only if Debug Language is disabled). The language file for the
        site's default language (<code>en-GB</code>, unless a third party
        extension has changed it).</para>
      </listitem>

      <listitem>
        <para>The currently active language's normative INI file (e.g.
        <code>com_example.ini</code>) or legacy INI file (e.g.
        <code>en-GB.com_example.ini</code>).</para>
      </listitem>
    </itemizedlist>

    <para>Joomla will first look in the current application's language folder
    i.e. <filename>administrator/language</filename> for the backend,
    <filename>language</filename> for the frontend and
    <filename>api/language</filename> for the API application.</para>

    <para>If neither the current language's, nor the default language's files
    have been found Joomla will fall back to your component's
    <filename>language</filename> directory. That is to say, your component's
    language directory is a last resort and not guaranteed to be used!</para>

    <para>You may wonder: why does Joomla load both the default language
    (British English in most cases) <emphasis>and</emphasis> my current
    language (e.g. Canadian French) files? The reason is simple. All
    components are required to provide a complete language file for the
    default language which for Joomla is British English<footnote>
        <para>Joomla started as a fork of another CMS called Mambo back in
        2005. Mambo was originally developed by an Australian company.
        Australian and British English use the same spelling and are mostly
        the same, so that company chose to make British English the default
        language for Mambo. When Joomla forked off Mambo it retained the
        default language despite the fact that the majority of its co-founders
        were not even native English speakers.</para>

        <para>For the longest time Joomla's default language files were a mix
        of British, American and mangled English (most contributors are NOT
        native English speakers) but as of Joomla 3.9 a lot of effort has been
        put in British English being actually <emphasis>British</emphasis>
        English. There are separate language packages for US American English
        (for those who prefer ‘colored trash cans’ to ‘coloured rubbish bins’,
        for example) and other English spellings / dialects.</para>
      </footnote> (<code>en-GB</code>). Translation to other languages are
    optional and often incomplete. Sometime around 2012 we decided that it
    makes far more sense to show an English, human-readable string to
    non-English speakers they can look up in the dictionary or their favorite
    translation tool than an incomprehensible language key like
    <code>COM_EXAMPLE_ITEMS_SELECT_CATEGORY_DEFAULT_LABEL</code>. Of course
    this makes it harder for translators. That's why the Debug Language
    feature was simultaneously introduced. When enabled, the default language
    is not enabled and untranslated strings are marked clearly in the
    output.</para>

    <bridgehead>Defining language files in your XML manifest</bridgehead>

    <para>Your XML manifest needs one set of <tag>&lt;languages&gt;</tag> tags
    per target application.</para>

    <para>For the backend language files, you need to list them under the
    <tag>&lt;administration&gt;</tag> tag:</para>

    <programlisting language="xml">&lt;administration&gt;
  &lt;!-- … --&gt;
  &lt;languages folder="languages/admin"&gt;
    &lt;language tag="en-GB"&gt;en-GB/com_example.ini&lt;/language&gt;
    &lt;language tag="en-GB"&gt;en-GB/com_example.sys.ini&lt;/language&gt;
    &lt;language tag="de-DE"&gt;de-DE/com_example.ini&lt;/language&gt;
    &lt;language tag="de-DE"&gt;de-DE/com_example.sys.ini&lt;/language&gt;
  &lt;/languages&gt;
  &lt;!-- … --&gt;
&lt;/administration&gt;</programlisting>

    <para>This copies the files from the <filename>languages/admin</filename>
    folder in your package to Joomla's admin language folder, e.g. the
    <filename>languages/admin/en-GB/com_example.ini</filename> file in your
    package to
    <filename>administrator/language/en-GB/com_example.ini</filename> file on
    your site.</para>

    <para>For the frontend language files, if you have any, you need to list
    them directly under the <tag>&lt;extension&gt;</tag> tag:</para>

    <programlisting language="xml">&lt;extension&gt;
  &lt;!-- … --&gt;
  &lt;languages folder="languages/site"&gt;
    &lt;language tag="en-GB"&gt;en-GB/com_example.ini&lt;/language&gt;
    &lt;language tag="de-DE"&gt;de-DE/com_example.ini&lt;/language&gt;
  &lt;/languages&gt;
  &lt;!-- … --&gt;
&lt;/extension&gt;</programlisting>

    <para>This copies the files from the <filename>languages/site</filename>
    folder in your package to Joomla's site language folder, e.g. the
    <filename>languages/site/en-GB/com_example.ini</filename> file in your
    package to <filename>language/en-GB/com_example.ini</filename> file on
    your site.</para>

    <para>For the API application language files, if you have any, you need to
    list them under the <tag>&lt;api&gt;</tag> tag:</para>

    <programlisting language="xml">&lt;api&gt;
  &lt;!-- … --&gt;
  &lt;languages folder="languages/api"&gt;
    &lt;language tag="en-GB"&gt;en-GB/com_example.ini&lt;/language&gt;
    &lt;language tag="de-DE"&gt;de-DE/com_example.ini&lt;/language&gt;
  &lt;/languages&gt;
  &lt;!-- … --&gt;
&lt;/api&gt;</programlisting>

    <para>This copies the files from the <filename>languages/api</filename>
    folder in your package to Joomla's api language folder, e.g. the
    <filename>languages/api/en-GB/com_example.ini</filename> file in your
    package to <filename>api/language/en-GB/com_example.ini</filename> file on
    your site.</para>

    <bridgehead>Languages and CLI</bridgehead>

    <para>CLI commands do <emphasis>not</emphasis> load any language files
    automatically. You can either supply your language strings in the
    <code>console</code> plugin which registers the commands or, more
    commonly, include them in your backend language file and have the plugin
    load that language file when registering the commands.</para>

    <bridgehead>Custom language files</bridgehead>

    <para>Beyond the regular <filename>.ini</filename> /
    <filename>.sys.ini</filename> files you can have any other language file
    you want. For example, you could have a
    <filename>com_example.alt.ini</filename> file which is only loaded when a
    specific option is enabled in your component. You can do that in your
    component's <link linkend="com-dispatcher">Dispatcher</link>. For
    example:</para>

    <programlisting language="php">$this-&gt;app-&gt;getLanguage()-&gt;load($this-&gt;option . '.alt', JPATH_BASE)
  || $this-&gt;app-&gt;getLanguage()-&gt;load($this-&gt;option . '.alt', JPATH_COMPONENT)</programlisting>

    <bridgehead>Language overrides</bridgehead>

    <para>Language overrides are loaded <emphasis>before</emphasis> any of
    your language files, at the initialisation of the CMSApplication object,
    namely when the Language object is constructed. They are stored in the
    file
    <filename>language/overrides/<replaceable>LANGUAGE_TAG</replaceable>.override.ini</filename>
    under the application's root (site root for the frontend,
    <filename>administrator</filename> for the backend,
    <filename>api</filename> for the API application) where
    <replaceable>LANGUAGE_TAG</replaceable> is the current language's tag,
    e.g. <code>en-GB</code> for British English.</para>

    <para>The way it works is that your language file is loaded and then the
    <emphasis>overridden</emphasis> strings are replaced into the language
    file <emphasis>if and only if</emphasis> they are already defined in the
    language file.</para>

    <caution>
      <para>This means that the language overrides cannot be used for language
      keys not defined in your language files, unlike Joomla 3.</para>

      <para>Since this was a widely popular “trick” to allow your users to
      customise the display of your components you now have to take that
      explicitly into account. For example, given an item with an alias
      <code>foobar</code> you might be looking for the language string
      <code>COM_EXAMPLE_ITEM_OVERRIDE_FOOBAR_TITLE</code> to override the
      title field of your item for display in different languages. This worked
      in Joomla 3 but will NOT work in Joomla 4 or later.</para>

      <para>You will need to provide an alternative mechanism for your users
      to provide custom translations. Remember the custom files I described
      just above? That's the alternative mechanism you can provide. DO NOT
      ship that file with your component. Just tell users to create it under
      their language folder and put their custom translations in there. It's
      far less user friendly than language overrides, unless of course you
      provide your own user interface for managing the contents of this
      file.</para>
    </caution>
  </section>

  <section xml:id="com-mailtemplates">
    <title>Mail Templates</title>

    <para>Joomla 4 introduced a new core component, Mail Templates
    (<code>com_mails</code>). You can access it from the System
    dashboard.</para>

    <para>This component allows you to manage email templates used by the
    different components which make use of Joomla's new Mail Templates
    feature. The user can choose to customise the plain text email's contents
    or even provide a full HTML email — or both. This is a much better user
    experience than language overrides, especially when it comes to HTML
    email.</para>

    <para>Using this feature is recommended, but not required. If you decide
    to use it for your components there's a bit of trouble you need to get
    through.</para>

    <bridgehead>Installing mail templates</bridgehead>

    <para>Mail templates live in the database, in the
    <database>#__mail_templates</database> table. The fields for each mail
    template are as follows:</para>

    <variablelist>
      <varlistentry>
        <term><database>template_id</database></term>

        <listitem>
          <para>The unique identifier of your mail template in the form
          <code>com_example.<replaceable>something</replaceable></code> where
          <code>com_example</code> is your component and
          <replaceable>something</replaceable> is a key consisting of just
          lowercase alphanumeric characters and underscores (a-z, 0-9 and _).
          This is a hard requirement; language string keys will be created
          using the <database>template_id</database>. This ID is what you will
          use when you want to send emails with this email template.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>language</database></term>

        <listitem>
          <para>The language tag of the mail template, e.g. <code>en-GB</code>
          for British English.</para>

          <important>
            <para>The default mail template should have an empty string as its
            language to apply to all languages. This is very different from
            literally everything else in Joomla which uses a <code>*</code> as
            the catch-all language.</para>
          </important>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>subject</database></term>

        <listitem>
          <para>The language string with the subject line of the email. The
          content of the language string can use variables (see
          <database>params</database> below).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>body</database></term>

        <listitem>
          <para>The language string with the body of the plain text version of
          the email. The content of the language string can use variables (see
          <database>params</database> below).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>htmlbody</database></term>

        <listitem>
          <para>The language string with the body of the HTML version of the
          email. The content of the language string can use variables (see
          <database>params</database> below).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>attachments</database></term>

        <listitem>
          <para/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>extension</database></term>

        <listitem>
          <para>The name of your extension, e.g.
          <code>com_example</code>.</para>

          <note>
            <para>You may wonder, if my template_id already contains this why
            is this a separate column? You are right, it doesn't make sense.
            Joomla could have just used an index on the template_id column
            with the same performance results or, if it was actually concerned
            about performance, use the numeric extension ID in this column. It
            doesn't make anysense; it is what it is.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><database>params</database></term>

        <listitem>
          <para>A JSON-serialised object with the parameters to the mail
          template. What is most important for us is its <code>tags</code>
          property. For example, you may have this <database>params</database>
          content:</para>

          <programlisting language="json">{
  "tags": [
    "FOO", "BAR", "BAZ"
  ]
}</programlisting>

          <para>This tells Mail Templates that you can use the variables
          <code>{FOO}</code>, <code>{BAR}</code> and <code>{BAZ}</code> in the
          subject, body and HTML body of the mail templates — and let users
          know that in the user interface. When sending emails via the Mail
          Templates feature you will have to provide the values for these
          variables. The variable names MUST always consist of uppercase
          letters, dashes, underscores and colons.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Moreover, you will need to supply a few language strings in you
    backend INI language file (e.g.
    <filename>administrator/languages/en-GB/com_example.ini</filename>).</para>

    <para>You need to provide a language string whose key is the uppercase
    version of your extension name, e.g.</para>

    <programlisting language="ini">COM_EXAMPLE="Example component"</programlisting>

    <para>This is used in the Mail Templates drop-down for selecting a
    component to filter by.</para>

    <para>For each email template you will need to provide a few “magic”
    language strings <emphasis>on top of</emphasis> the language strings you
    defined in the <database>subject</database>, <database>body</database>,
    and <database>htmlbody</database> columns. Assuming a
    <database>template_id</database> <code>com_example.foo_bar</code> you will
    need to provide the following language strings:</para>

    <variablelist>
      <varlistentry>
        <term><code><replaceable>COM_EXAMPLE</replaceable>_MAIL_<replaceable>FOO_BAR</replaceable>_TITLE</code></term>

        <listitem>
          <para>A long title for your email template, displayed in the user
          interface. The content of this language string should be something
          similar to “My Component Name: When This Mail Template Is
          Sent”.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><code><replaceable>COM_EXAMPLE</replaceable>_MAIL_<replaceable>FOO_BAR</replaceable>_SHORT</code></term>

        <listitem>
          <para>A short title for your email template. I am not sure when this
          is used.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><code><replaceable>COM_EXAMPLE</replaceable>_MAIL_<replaceable>FOO_BAR</replaceable>_DESC</code></term>

        <listitem>
          <para>A short description of your email template, displayed in the
          user interface.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <bridgehead>Using mail templates</bridgehead>

    <para>The Mail Templates feature does NOT send emails. It only provides
    you with a pre-configured Joomla Mailer object you will use to send emails
    with.</para>

    <para>This is how you use it:</para>

    <programlisting language="php">/**
 * @var string $templateId The template ID you want to use, e.g. com_example.foo_bar
 * @var string $langTag The language tag for your email, e.g. 'en-GB'
 */
$template = new \Joomla\CMS\Mail\MailTemplate($templateId, $langTag);

// Add the contents of your variables here
$template-&gt;addTemplateData([
  'FOO' =&gt; 'Contents of the {FOO} variable',
  'BAR' =&gt; 'Contents of the {BAR} variable',
  'BAZ' =&gt; 'Contents of the {BAZ} variable',
]);

/**
 * @var string $emailAddress The email address of the recipient, e.g. jane@example.com
 * @var string $recipientName The full name of your recipient, e.g. "Jane Doe"
 */
$template-&gt;addRecipient($emailAddress, $recipientName);

// Send the email
$template-&gt;Send();</programlisting>

    <para>If you want to customise the Joomla Mailer object used by the
    <classname>MailTemplate</classname> class —for example to set custom
    headers, add inline images or attachments which cannot be handled by
    MailTemplate, etc— you can pass it as the third parameter to its
    constructor, e.g.</para>

    <programlisting language="php">$mailer = \Joomla\CMS\Factory::getMailer();
$mailer-&gt;addCustomHeader('X-Vanity-Header', 'Joomla! Rocks');

$template = new \Joomla\CMS\Mail\MailTemplate($templateId, $langTag, $mailer);</programlisting>

    <para>Do keep in mind that each email template may have its own
    configuration about the sender address and sending method (e.g. SMTP
    information). These settings will override the same settings in your
    custom mailer object when you call <methodname>Send()</methodname>.</para>

    <tip>
      <para>The above will error out if MailTemplate cannot find a suitable
      template. You can check if a suitable template exists by doing this
      before any of the code above:</para>

      <programlisting language="php">$template = Joomla\CMS\Mail\MailTemplate::getTemplate($templateId, $langTag);</programlisting>

      <para>If $template is empty do NOT go through MailTemplate. You can
      simply not send the email, provide an alternative, throw an error or
      otherwise handle this condition in a way appropriate for your
      application.</para>
    </tip>

    <bridgehead>Caveats</bridgehead>

    <para>Users can, and <emphasis>will</emphasis>, mess up the Mail
    Templates. If they just mess up the subject, plain text body or HTML body
    they can recover easily by using the respective reset button in the user
    interface.</para>

    <para>If they create a specific language version of a mail template they
    cannot remove it without messing with the database.</para>

    <para>If you update a mail template, adding more tags (variables) in its
    parameters you will need to write update SQL which updates all entries
    with the relevant template_id <emphasis role="bold">BUT</emphasis> you
    should note that by overwriting the contents of the
    <database>params</database> column you will be resetting the user's
    preferences about the mailer itself (sender, sending method, credentials
    etc). Therefore updating mail templates <emphasis>actually</emphasis>
    requires writing PHP code in your extension's installation script to run
    on update, read all mail templates with the affected
    <database>template_id</database>, decode the <database>params</database>,
    update the tags and write everything back to the database. It's a big old
    pain in the posterior.</para>

    <para>A final word of caution. The MailTemplate class has some static
    methods such as <methodname>createTemplate</methodname> and
    <methodname>updateTemplate</methodname>. <emphasis role="bold">Don't use
    them</emphasis>. They will error out.</para>
  </section>

  <section xml:id="com-cli">
    <title>The CLI application</title>

    <para>In Joomla 3 we could create CLI scripts for Joomla by extending the
    <classname>JApplicationCli</classname> class (later renamed to
    <classname>Joomla\CMS\Application\CliApplication</classname>) in a new
    file which we'd place in Joomla's <filename>cli</filename> directory.
    While that was a useful way to get access to all Joomla resources and API
    from our CLI it created a problem: there were too many files in the
    <filename>cli</filename> directory and it was not always clear which
    component they belong to. It also put a burden on third party developers
    like us to provide a <code>files</code> package with these CLI scripts and
    make sure that it gets updated together with our main extension package.
    There was also a lot of boilerplate code that had to go into each file,
    potentially different for each Joomla version we supported.</para>

    <para>In Joomla 4 we can still do that (but it's deprecated) or we can use
    the new <emphasis role="bold">Joomla CLI Application</emphasis>. This
    lives in <filename>cli/joomla.php</filename>. It is an extensible
    application using a CMSApplication class which uses the Symfony Console —
    much like Composer, WP-CLI and Drush. Unlike the aforementioned
    applications, it is not standalone. It is part of your site, making it the
    fourth official Joomla application bundled with the Joomla CMS (the other
    three being the frontend a.k.a. site application, the backend a.k.a.
    administrator application and the API application).</para>

    <section xml:id="com-cli-commands">
      <title>Command classes</title>

      <para>Like all Symfony Console applications, the Joomla CLI Application
      is extended with Command classes. The Joomla command classes need to
      extend from the
      <classname>\Joomla\Console\Command\AbstractCommand</classname>
      class.</para>

      <para><bridgehead>Where do command classes live?</bridgehead></para>

      <para>There are no hard rules about where you should put your command
      classes. There are two possibilities which make the most sense, as far
      as I can see.</para>

      <orderedlist>
        <listitem>
          <para>Inside the <code>console</code> plugin which registers the
          commands to the Joomla CLI Application.</para>

          <para>It makes sense because the plugin contains the code to the
          commands and registers them to the CLI application. However, it is
          possible that someone may disable or uninstall your component but
          not the console plugin. This would mean that the commands, or even
          their registration, will fail due to the component no longer being
          bootable. You will need to add special code to address that.
          Furthermore, there's the small but real risk that the user ends up
          with a console plugin that's older or newer than the installed
          component version, potentially causing havoc when the CLI commands
          are used.</para>
        </listitem>

        <listitem>
          <para>Inside the backend part of your component.</para>

          <para>This is the way I prefer to do things and what I will show
          you. The commands are in the <code>CliCommand</code> leaf namespace
          of my component. For example, with a component that has the
          namespace prefix <code>Acme\Component\Example</code> I would put my
          commands in the
          <code>Acme\Component\Example\Administrator\CliCommand</code>
          namespace i.e. the folder
          <code>administrator/components/com_example/src/CliCommand</code>.</para>

          <para>The plugin does not need to check if the component is
          bootable; if it's not, the PSR-4 autoloader for its namespace won't
          be loaded and the command classes cannot be found. Therefore I just
          need to check if the command classes exist. Mixing the versions of
          the plugin and the component is not a problem either; the plugin
          will load the command classes it knows of and if some of them do not
          exist (the plugin is from a newer version) we simply skip it
          over.</para>
        </listitem>
      </orderedlist>

      <bridgehead>A sample command class</bridgehead>

      <programlisting language="php">&lt;?php
namespace Acme\Component\Example\Administrator\CliCommand;

defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;
use Joomla\CMS\MVC\Model\DatabaseAwareTrait;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

class ItemsList extends \Joomla\Console\Command\AbstractCommand
{
  use MVCFactoryAwareTrait;
  use DatabaseAwareTrait;

  /**
   * The default command name
   *
   * @var    string
   */
  protected static $defaultName = 'example:items:list';

  /**
   * @var   SymfonyStyle
   */
  private $ioStyle;

  /**
   * @var   InputInterface
   */
  private $cliInput;

  /**
   * @inheritDoc
   */
  protected function doExecute(InputInterface $input, OutputInterface $output): int
  {
    // Configure the Symfony output helper
    $this-&gt;configureSymfonyIO($input, $output);

    // Collect the options
    $search = $input-&gt;getOption('search') ?? null;

    // Get the items, using the backend model
    /** @var \Joomla\CMS\MVC\Model\BaseDatabaseModel $itemsModel */
    $itemsModel = $this-&gt;getMVCFactory()-&gt;createModel('Items', 'Administrator');

    if ($search)
    {
      $itemsModel-&gt;setState('filter.search', $search);
    }

    $items = $itemsModel-&gt;getItems();

    // If no items are found show a warning and set the exit code to 1.
    if (empty($items))
    {
      $this-&gt;ioStyle-&gt;warning('No items found matching your criteria');

      return 1;
    }

    // Reshape the items into something humans can read.
    $items = array_map(
      function (object $item): array
      {
        return [
          $item-&gt;id,
          $item-&gt;title,
          $item-&gt;published ? Text::_('JYES') : Text::_('JNO')
        ];
      },
      $items
    );

    // Display the items in a table and set the exit code to 0
    $this-&gt;ioStyle-&gt;table(
      [
        Text::_('COM_EXAMPLE_FIELD_HEADER_ID'),
        Text::_('JGLOBAL_TITLE'),
        Text::_('JPUBLISHED'),
      ],
      $items
    );

    return 0;
  }

  /**
   * Configure the command.
   *
   * @return  void
   */
  protected function configure(): void
  {
    $this-&gt;setDescription(Text::_('COM_EXAMPLE_CLI_ITEMS_LIST_DESC'));
    $this-&gt;setHelp(Text::_('COM_EXAMPLE_CLI_ITEMS_LIST_HELP'));

    $this-&gt;addOption('search', 's', InputOption::VALUE_OPTIONAL, Text::_('COM_EXAMPLE_CLI_CONFIG_SEARCH'));
  }

  /**
   * Configure the IO.
   *
   * @param   InputInterface   $input   The input to inject into the command.
   * @param   OutputInterface  $output  The output to inject into the command.
   *
   * @return  void
   */
  private function configureSymfonyIO(InputInterface $input, OutputInterface $output)
  {
    $this-&gt;cliInput = $input;
    $this-&gt;ioStyle  = new SymfonyStyle($input, $output);
  }

}</programlisting>

      <para><bridgehead>The command name
      (<code>$defaultName</code>)</bridgehead></para>

      <para>A command class needs to provide a name for the command being
      executed. In Joomla 4 ,third party extensions should use the convention
      <option>component:command</option> and
      <option>component:command:subcommand</option> where
      <replaceable>component</replaceable> is the name of the component
      without <command>com_</command>. The command part is the name of your
      command. If you need to implement subcommands you can add a third,
      fourth etc part in your command name, all separated with colons. For
      example we could have the following names:</para>

      <itemizedlist>
        <listitem>
          <para><command>example:email</command> Process an email queue</para>
        </listitem>

        <listitem>
          <para><command>example:items:list</command> Produce a list of
          items</para>
        </listitem>

        <listitem>
          <para><command>example:items:delete</command> Delete an item</para>
        </listitem>
      </itemizedlist>

      <para>The name of the command goes into the command class'
      <code>$defaultName</code> static property.</para>

      <para><bridgehead>Command configuration</bridgehead></para>

      <para>Each command needs a bit of configuration so that Joomla knows how
      to display it in a list of commands (<code>php joomla.php list</code>),
      provide help for a command (e.g. <code>php joomla.php example:items:list
      --help</code>) and parse the arguments and options to the command. This
      is done in the <methodname>configure()</methodname> method.</para>

      <para>Calling setDescription sets the short help text which appears next
      to the command in the list of available commands.</para>

      <para>Calling setHelp sets the longer help text which appears in the
      per-command help page.</para>

      <para>The rest of the method body defines the arguments and options to
      the commands, whether they are required or optional, their default
      values and their associated help text. This is explained in detail in
      the Symfony Console documentation article “<link
      xlink:href="https://symfony.com/doc/current/console/input.html">Console
      Input (Arguments &amp; Options)</link>”.</para>

      <para><bridgehead>Command implementation</bridgehead></para>

      <para>The implementation of your command, the code which executes when
      you call it, is in the <methodname>doExecute</methodname> method.</para>

      <para>The first thing we do is get a SymfonyStyle object to facilitate
      the formatting our command's output. It has all sorts of useful things,
      from titles and success / warning / error blocks to progress bars and
      tables. You can read more about it in the Symfony Console documentation
      article <link
      xlink:href="https://symfony.com/doc/current/console/style.html">How to
      Style a Console Command</link>.</para>

      <para>The rest of the code is pretty straightforward; it's standard
      Joomla stuff. What you need to note is that we always return an integer.
      This MUST be an integer from 0 to 255 (inclusive). It is used as the
      command line application's <link
      xlink:href="https://www.redhat.com/sysadmin/linux-shell-command-exit-codes">exit
      code</link>. It is very strongly recommended that you use a different
      exit code for each result state of your command <emphasis>and document
      it</emphasis>. This can be used in automation scenarios, e.g. someone
      using your CLI commands in an Ansible playbook or a custom shell
      script.</para>

      <note>
        <para>You may see that I've used the MVCFactoryAwareTrait and
        DatabaseAwareTrait traits. We will be using these traits to pass our
        component's MVCFactory and the Joomla database object when creating
        objects out of our command classes, before registering them to the
        Joomla CLI application, in our <code>console</code> plugin.</para>

        <para>While we could skip that and just fetch these
        <emphasis>dependencies</emphasis> directly in our console class,
        please do keep in mind that Joomla is trying to get us to use
        <emphasis>dependency injection</emphasis>, i.e. the object should be
        pushed the dependencies into it rather than having it to pull them
        from somewhere else. If there's a big architectural change in Joomla
        it's far easier to change things at the singular injection point
        rather than hunting down all places where we might be pulling
        dependencies. That's one of the many reasons Dependency Injection is
        used: it makes refactoring easier.</para>
      </note>
    </section>

    <section xml:id="com-cli-plugins">
      <title>Console plugins</title>

      <para>The Joomla CLI Application needs to somehow know about our custom
      CLI command classes. The way Joomla decided to implement this is with
      <emphasis>plugins</emphasis>. This makes perfect sense! The “One True
      Joomla Way” for implementing extensible features is with plugins.</para>

      <para>We need to create a new plugin in the <code>console</code> group
      which will register our commands to the Joomla CLI application. This
      plugin must follow the Joomla 4 conventions<footnote>
          <para>We'll learn more about creating plugins in the <link
          linkend="plg">Plugins</link> section of this book.</para>
        </footnote> as it will be handling an event.</para>

      <bridgehead>The service provider</bridgehead>

      <para>Joomla 4 plugins do need a service provider. We are going to use
      the service provider to also get ahold of the MVCFactory object of our
      component, pass it to the plugin object which can then pass it to our
      command class.</para>

      <programlisting language="php">defined('_JEXEC') || die;

use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Extension\Service\Provider\MVCFactory;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use Joomla\Plugin\Console\ATS\Extension\ATS;

return new class implements ServiceProviderInterface {
  public function register(Container $container)
  {
    $container-&gt;registerServiceProvider(new MVCFactory('Acme\\Component\\Example'));

    $container-&gt;set(
      PluginInterface::class,
      function (Container $container) {
        $config     = (array) PluginHelper::getPlugin('console', 'example');
        $subject    = $container-&gt;get(DispatcherInterface::class);
        $mvcFactory = $container-&gt;get(MVCFactoryInterface::class);
        $plugin     = new Example($subject, $config)

        $plugin-&gt;setMVCFactory($mvcFactory);

        return $plugin;
      }
    );
  }
};</programlisting>

      <bridgehead>The plugin class</bridgehead>

      <para>The plugin class only listens to one event, the
      <classname>\Joomla\Application\ApplicationEvents::BEFORE_EXECUTE</classname>
      one. This event is an
      <classname>\Joomla\Application\Event\ApplicationEvent</classname> which
      is raised by the Joomla CLI Application before it tries to execute the
      user's instructions.</para>

      <para>To make things easier, and our example reusable in the real world
      with minimal modifications, we have a private static variable which
      lists the class names of the command classes to register. The
      <methodname>registerCLICommands</methodname> method iterates through
      them, creates a command object and adds it to the CLI
      application.</para>

      <programlisting language="php">&lt;?php
namespace Joomla\Plugin\Console\Example\Extension;

defined('_JEXEC') or die;

use Acme\Component\Example\Administrator\CliCommand\ItemsList;
use Joomla\Application\ApplicationEvents;
use Joomla\Application\Event\ApplicationEvent;
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use Throwable;

class Example extends CMSPlugin implements SubscriberInterface
{
  use MVCFactoryAwareTrait;

  private static $commands = [
    ItemsList::class,
  ];

  protected $autoloadLanguage = true;

  public static function getSubscribedEvents(): array
  {
    return [
      ApplicationEvents::BEFORE_EXECUTE =&gt; 'registerCLICommands',
    ];
  }

  public function registerCLICommands(ApplicationEvent $event)
  {
    foreach (self::$commands as $commandFQN)
    {
      try
      {
        if (!class_exists($commandFQN))
        {
          continue;
        }

        $command = new $commandFQN();

        if (method_exists($command, 'setMVCFactory'))
        {
          $command-&gt;setMVCFactory($this-&gt;getMVCFactory());
        }

        $this-&gt;getApplication()-&gt;addCommand($command);
      }
      catch (Throwable $e)
      {
        continue;
      }
    }
  }
}</programlisting>

      <para>As you can see, after creating the command object we push the
      MVCFactory into it — if it supports that feature, i.e. it is using the
      <classname>MVCFactoryAwareTrait</classname> itself.</para>

      <para>We could do the same for the database object. We'll let you figure
      it out. For the solution, you can read the footnote<footnote>
          <para>At the top of the plugin object define the <code>$db</code>
          property to let Joomla push the database object into the plugin
          object.</para>

          <programlisting language="php">protected $db;</programlisting>

          <para>In the registerCLICommand method, right after pushing the
          MVCFactory, push the database object:</para>

          <programlisting language="php">if (method_exists($command, 'setDbo'))
{
  $command-&gt;setDbo($this-&gt;db);
}</programlisting>
        </footnote>.</para>

      <para>Remember to not just install this plugin, but also publish it. You
      can publish the plugin automatically in the <code>install</code> section
      of your package's installation script. Remember, that code only runs on
      a new installation. If you want to enable this plugin also on updates
      you will need to do the same in the <code>update</code> section as well.
      Yes, it's a bit of a kludge but in practice it works very well.</para>
    </section>
  </section>

  <section xml:id="com-api">
    <title>The API application</title>

    <para>Joomla version 1, 2 and 3 had no good, universal way of adding a
    <link
    xlink:href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</link>
    <link xlink:href="https://en.wikipedia.org/wiki/JSON">JSON</link> API to a
    component. There was a hodgepodge of solutions (ab)using Joomla's routing
    to essentially end up with a format=json request query parameter post-SEO
    parsing and some basic logic to convert HTTP verbs into respective
    Controller tasks, sometimes with rudimentary support for <link
    xlink:href="https://en.wikipedia.org/wiki/Hypertext_Application_Language">HAL</link>
    or similar <link
    xlink:href="https://en.wikipedia.org/wiki/HATEOAS">HATEOAS</link>
    solutions. In plain English: we had no good way to write JSON APIs which
    didn't suck royally!</para>

    <para>Joomla 4 addresses this problem with the introduction of a new
    official Joomla application, the API application which lives in the
    <filename>api</filename> folder of your site.</para>

    <section xml:id="com-api-overview">
      <title>Overview</title>

      <para>The API application uses a set of plugins in the
      <literal>webservices</literal> group to determine which of the installed
      API components will be responding to requests. These plugins are also
      responsible for determining the routes (URLs) for the respective
      component's JSON API. While having a plugin control whether a particular
      component provides an API may sound odd, it makes sense. Depending on
      the site, you don't always want to expose everything under the sun in a
      JSON API. For example, if you do not have a use case for listing the
      extensions over the JSON API it makes more security sense having that
      feature unpublished.</para>

      <para>Beyond the plugin, your component needs an API part just like it
      does for the frontend (site) and the backend (administrator)
      applications. The difference is that you only have Controllers, Models
      and Views. You do not have view templates. The Views descend from
      <classname>\Joomla\Component\Banners\Api\View\Banners\JsonapiView</classname>
      which manages the data conveyed through a
      <classname>\Joomla\CMS\Document\JsonDocument</classname> as a JSON
      formatted response.</para>

      <para>As for who can access the API… we'll see about that in the next
      section.</para>
    </section>

    <section xml:id="com-api-access">
      <title>Access and Authentication</title>

      <para>In theory, the Joomla API application is only available to Super
      Users in Joomla 4. The idea is that this is a new and very powerful (a
      bit <emphasis>too </emphasis>powerful, maybe?) way to access the site,
      therefore the Joomla project felt that it should only be available to
      Super Users.</para>

      <para>Authentication for Super Users does not normally take place with a
      username and password but with a token<footnote>
          <para>The token is much safer than using a username and password.
          Joomla stores some of the information required to construct the
          token in the database (the <database>#__user_profiles</database>
          table) and some of it in the filesystem (the
          <varname>$secret</varname> in
          <filename>configuration.php</filename>). These two pieces of
          information are cryptographically combined to create the token,
          therefore SQL injections cannot be used to steal it. If it's
          compromised it can be quickly disabled or reset. A better solution
          would be a true OAuth2 flow but nobody has written the code for it
          (yet?).</para>
        </footnote>. You can find your token by editing your (Super User)
      profile in the back- or frontend of the site, as long as the
      <guilabel>User - Joomla API Token</guilabel> plugin is published.
      Authenticating with the token requires the API <guilabel>Authentication
      - Web Services Joomla Token</guilabel> plugin to be published as well.
      You pass the token in a standard Authentication HTTP header following
      <link
      xlink:href="https://datatracker.ietf.org/doc/html/rfc6750#page-5">RFC
      6750</link> for bearer tokens:</para>

      <programlisting>Authorization: Bearer c2hhMjU2OjcwOjg5NWQ5MDM3MjA1NTY2MzM2OWFmYjc0YTg1MGFmYWFjNTAyMGYyZTU2MjQ3OTkxZjMwNDE1MTNkNDQ2NjhjN2Y=</programlisting>

      <para>Alternatively, the token can be sent in the custom HTTP header
      with the name X-Joomla-Token:</para>

      <programlisting>X-Joomla-Token: c2hhMjU2OjcwOjg5NWQ5MDM3MjA1NTY2MzM2OWFmYjc0YTg1MGFmYWFjNTAyMGYyZTU2MjQ3OTkxZjMwNDE1MTNkNDQ2NjhjN2Y=</programlisting>

      <para>Practically speaking, use the latter header as the Authorization
      header may not be passed correctly by the server.</para>

      <tip>
        <para>When making requests to the Joomla API remember to send the HTTP
        header <literal>Accept</literal> with the content
        <literal>application/vnd.api+json</literal> (not just
        <literal>application/json</literal>). Otherwise you will get an HTTP
        406 response.</para>
      </tip>

      <para>However, that is not the entire truth — nothing is ever that
      simple when you're talking authentication.</para>

      <para>It is perfectly possible to use Joomla's API application for a
      publicly accessible JSON API which does not perform any kind of
      authentication! This is, in fact, what Joomla's Media Manager
      (<code>com_media</code>) does. Counter-intuitively, the implementation
      for public routes is set up in the <emphasis
      role="bold">plugin</emphasis>, not the API component part. We'll see how
      in the <link linkend="com-api-plugin">web services plugin</link>
      section.</para>

      <para>This also means that you can do custom authentication using your
      own authentication mechanism by setting the routes to be public and
      performing authentication and access control in your API controllers.
      This is not entirely safe and I don't recommend it but, you know, the
      option does exist if you really need it and you really know what you are
      doing.</para>
    </section>

    <section xml:id="com-api-component">
      <title>The API part of your component</title>

      <para>Starting with Joomla 4, your component has another
      optional<footnote>
          <para>A component <emphasis>must</emphasis> have a backend
          (administrator) part. The frontend (site) and api parts are
          optional. And, yes, this means that you can absolutely have a
          backend-only component but not a frontend-only or api-only
          component. The necessity for a backend part comes from the fact that
          the XML manifest, the configuration (config.xml) and the permissions
          (access.xml) files are present only in the backend directory of the
          component. The former is necessary for a component to be able to be
          installed, updated and uninstalled. Moreover, Joomla always creates
          a backend menu item for the component, meaning that the component
          must have a backend part with a default view even if it's just to
          display a message that there is nothing to do with this component in
          the backend.</para>
        </footnote> part: the <literal>api</literal> part. Just like the
      component's frontend (site) and backend (administrator) it has its own
      Controllers, Views, and Models to render not HTML pages but JSON result
      sets.</para>

      <para>The namespace suffix for the API application is
      <classname>Api</classname>. This means that a component with the
      namespace prefix <classname>Acme\Component\Example</classname> defined
      in its XML manifest will have the namespace prefix
      <classname>Acme\Component\Example\Api</classname> for all of its API
      application classes.</para>

      <section xml:id="com-api-component-manifest">
        <title>Adding it to your XML manifest</title>

        <para>If you are implementing an integration with the Joomla API
        application your XML manifest needs to have an <tag>&lt;api&gt;</tag>
        section under the <tag>&lt;extension&gt;</tag> root node, defining the
        files and folders included in your component's api part. Typically, it
        looks like this:</para>

        <programlisting language="xml">&lt;api&gt;
  &lt;files folder="api"&gt;
  &lt;folder&gt;src&lt;/folder&gt;
&lt;/files&gt;
&lt;/api&gt;</programlisting>

        <para>Yes, typically you only have one folder,
        <filename>src</filename>, containing your Controllers, Views and
        Models.</para>
      </section>

      <section xml:id="com-api-component-controllers">
        <title>Controllers</title>

        <para>The API controllers all extend from the core
        <classname>\Joomla\CMS\MVC\Controller\ApiController</classname> class.
        The API controllers will, by default, implement CRUD (Create, Read,
        Update, Delete). Do note that Read in this context means both
        returning a single item <emphasis>and</emphasis> returning a list of
        items.</para>

        <para>At a minimum, you need to override the
        <property>$contentType</property> and
        <property>$default_view</property> properties.</para>

        <para>The <property>$contentType</property> property is used as the
        context to the <literal>onGetApiAttributes</literal> and
        <literal>onGetApiRelation</literal> events. The former is used to
        modify the data of the JSON response. The latter is used to add
        related data to the JSON response.</para>

        <note>
          <para>Unfortunately, the content type is <emphasis>a very bad
          choice</emphasis> for context in these events because it's not
          unique across components and the component's name is not given in
          the event arguments. For example, the type <literal>groups</literal>
          is already duplicated in the core, for <literal>com_fields</literal>
          and <literal>com_users</literal>.</para>

          <para>For this reason, you may want to provide your extension's
          <property>$contentType</property> in the format
          <literal>com_example.item</literal>, i.e. prefix your content type
          with the name of your component and a dot. It's a far cry from being
          intuitive, especially since consumers will have to remove the prefix
          to find out the API route which gives them access to this content
          type, but at least it provides a valid, unique context for the
          events.</para>
        </note>

        <para>In most cases you do not want to change the
        <methodname>displayItem</methodname> (read one),
        <methodname>displayList</methodname> (read many),
        <methodname>delete</methodname> (remove), <methodname>add</methodname>
        (create), and <methodname>edit</methodname> (update) methods. When you
        do, it's mostly so you can set a filter state in the view's Model.
        Joomla's core components do that a lot in their api application
        part.</para>

        <para>You will most likely need to override one or more of the
        following methods for most real world components:</para>

        <itemizedlist>
          <listitem>
            <para><methodname>allowEdit</methodname>. Is the current user
            allowed to edit (update) the item? By default, it only checks the
            <literal>core.edit</literal> privilege of the current user for
            your component. The method is passed the data and the table's
            primary key in case you need to do more fine grained access
            control. For example, a forum component will very reasonably only
            allow the user who posted a specific post and the forum
            administrators to edit a post, not any random person who can post
            into the forum.</para>
          </listitem>

          <listitem>
            <para><methodname>allowAdd</methodname>. Is the current user
            allowed to add (create) a new item? By default, it only checks if
            the currently logged in user has the
            <literal>core.create</literal> privilege for your component or
            they have the <literal>core.create</literal> privilege in any
            categories which belong to your component (assuming you are
            integrating with Joomla's com_categories). The method is passed
            the data to be created in case you need to perform more
            fine-grained access control. For example, a helpdesk component
            would only allow the user who owns a support ticket and the
            support staff to post replies to a specific ticket. The view
            handling replies would check the ticket ID in the data to
            determine if this is the case before allowing a new post to be
            created.</para>
          </listitem>

          <listitem>
            <para><methodname>preprocessSaveData</methodname>. This is
            executed after allowEdit and allowAdd, but before handling tags
            and saving the data into the database. This is your last chance to
            make any modifications to the data before committing it to the
            database. For example, you may want to perform additional
            validation and cleanup of HTML content, or you may want to
            automatically fill in missing information which would cause a
            validation error when the Model tries to save the data.</para>
          </listitem>
        </itemizedlist>
      </section>

      <section xml:id="com-api-component-models">
        <title>Models</title>

        <para>You do not <emphasis>need</emphasis> to have API-specific Models
        in your component. If you do not provide a Model, the API application
        will use the Administrator models instead. This is usually what you
        want to do. There are very few cases where the API application needs a
        different model to both the Administrator and the Site model.</para>

        <para>If you do need to create Models, follow the same conventions as
        you'd do for Models in the Administrator part of your application. The
        only difference is that the namespace prefix uses
        <classname>Api</classname> instead of
        <classname>Administrator</classname>.</para>
      </section>

      <section xml:id="com-api-component-views">
        <title>Views</title>

        <para>View classes in the API application are the biggest change to
        what you are used to doing in Joomla components.</para>

        <para>All these years you have been writing components with a backend
        and frontend part. Most of the time you had a View class whose purpose
        was to generate HTML using view templates. Quite rarely some of you
        may have used a raw, XML or JSON view to output something else such as
        INI data, binary data (e.g. an image), and XML document or a JSON
        string. In all cases you were more or less constructing the data as a
        string and had your view return that string.</para>

        <para>The API application views extend from
        <classname>\Joomla\CMS\MVC\View\JsonApiView</classname> which is a
        special version of the good, old, reliable
        <classname>\Joomla\CMS\MVC\View\JsonView</classname> we had for years.
        Its biggest difference is that you are no longer constructing and
        return a <emphasis>string</emphasis>. Instead, you have a
        <classname>\Joomla\CMS\Serializer\JoomlaSerializer</classname> object
        which figures out how to best convert your raw data to a JSON
        representation. Moreover, you have separate methods for displaying a
        single item (<methodname>displayItem</methodname>) versus displaying a
        list of items (<methodname>displayList</methodname>).</para>

        <para>The two methods need to know which of the fields returned by
        your Model's <methodname>getItem</methodname> and
        <methodname>getItems</methodname> methods, respectively, needs to be
        output in the JSON document. You can do that by setting two string
        array properties, <property>$fieldsToRenderItem</property> and
        <property>$fieldsToRenderList</property>. The former lists all the
        fields to be output when rendering a single item view (the
        <methodname>displayItem</methodname> method in the Controller) and the
        latter lists all the fields to be output when rendering a view which
        returns multiple items (the <methodname>displayList</methodname>method
        in the Controller).</para>

        <note>
          <para>At first glance this sounds tedious, if not pointless, but it
          does make sense when you start thinking about it. When listing tree
          entries, like menu items, there is no point in outputting the
          internal fields <literal>lft</literal>, <literal>rgt</literal>,
          <literal>level</literal> and so on which are only used to manage the
          tree. Moreover, and assuming you implement your own access control,
          you may want to return different fields depending on the user's
          privileges. For example, a helpdesk component's user may get access
          to their ticket information but not the internal notes on it kept by
          the support staff; <emphasis>that</emphasis> would only be available
          to the support staff. Do not discount everything Joomla does as
          silly. More often than not there's method to its madness.</para>
        </note>

        <para>The hidden gem of the API view is another string array property,
        <property>$relationship</property>. In that view you list all the
        field names returned by your model which refer to <emphasis>related
        data</emphasis>. Now, this is where things get interesting! A contact
        has, for example, a user ID. The user ID tells us nothing. However,
        the user ID is not a standalone thing; it's a reference to the
        <emphasis>related</emphasis> user record. Therefore listing
        <literal>user_id</literal> in the <code>$relationship</code> array
        tells the <classname>JsonapiView</classname> that it needs to fetch
        that related record and include it in the returned JSON document along
        with information which tells the consumer that this embedded JSON
        document refers to that <literal>user_id</literal> — and the URL to
        use to get more information about it.</para>

        <para>There is a catch to using relations: you need a custom
        Serializer object which extends
        <classname>\Joomla\CMS\Serializer\JoomlaSerializer</classname> and
        adds one public method named after each relationship field. Each
        method returns a <classname>\Tobscure\JsonApi\Relationship</classname>
        object which is used to output the relationship links in the JSON
        document. The custom Serialiser object is assigned to the
        <property>serializer</property> property of your JsonapiView in its
        constructor. This sounds very abstract and confusing; it's best if you
        observe it in real world code. I recommend taking a look at Joomla's
        own
        <classname>\Joomla\Component\Content\Api\View\Articles\JsonapiView</classname>
        and
        <classname>\Joomla\Component\Content\Api\Serializer\ContentSerializer</classname>
        to get a feeling of how you can add relationships in JSON API
        views.</para>
      </section>
    </section>

    <section xml:id="com-api-plugin">
      <title>Web services plugin</title>

      <para>The second thing required for your component to integrate with the
      Joomla API application is a <literal>webservices</literal> plugin. This
      plugin serves a dual role.</para>

      <para>On one hand it lets the user determine which components will
      participate in the Joomla API application — if they do not have a use
      case for your component's JSON API they can and should disable the
      plugin.</para>

      <para>On the other hand the plugin implements routing for your API
      application. That's right; there is no such thing as a Router service
      for the API application since the URL structure is meant to be
      predefined and predictable<footnote>
          <para>As opposed to being defined by the site's owner and limited by
          that person's ability to create a sensible menu structure —
          something which, according to my experience working on thousand of
          sites' backends, is most definitely not a given. At some point I
          will probably have to write a series of blog posts or yet another
          book on how to realistically build Joomla sites…</para>
        </footnote>. As a matter of fact, the only event handler we implement
      in this plugin is <literal>onBeforeApiRoute</literal>.</para>

      <para>The <literal>onBeforeApiRoute</literal> event handler takes
      exactly one argument, an object instance of
      <classname>\Joomla\CMS\Router\ApiRouter</classname>. This is a subclass
      of Joomla's <classname>\Joomla\Router\Router</classname> class,
      optimised for use in the API application.</para>

      <para>There are two ways to add routes for your component's API
      application integration, both using the router object.</para>

      <para>The first way is calling the object's
      <methodname>createCRUDRoutes</methodname> method. This methods creates
      five routes (named after the respective HTTP verbs):</para>

      <itemizedlist>
        <listitem>
          <para>A <literal>GET</literal> route which returns a list of
          records.</para>
        </listitem>

        <listitem>
          <para>A <literal>GET</literal> route with an <literal>id</literal>
          parameter which returns a single record.</para>
        </listitem>

        <listitem>
          <para>A <literal>POST</literal> route to add a new record.</para>
        </listitem>

        <listitem>
          <para>A <literal>PATCH</literal> route with an <literal>id</literal>
          parameter which updates (“edits”) an existing record.</para>
        </listitem>

        <listitem>
          <para>A <literal>DELETE</literal> route with an
          <literal>id</literal> parameter which deletes an existing
          record.</para>
        </listitem>
      </itemizedlist>

      <para>As you may have intuited, these are the five CRUD (Create, Read,
      Update, Delete) operations supported by Joomla's controllers and more
      specifically the ApiController. The HTTP verbs for each CRUD operation
      are those specified in the REST specification. So, yes, Joomla lets us
      <emphasis>easily</emphasis> create RESTful JSON APIs, as promised. Neat,
      huh?!</para>

      <para>This method takes four arguments:</para>

      <itemizedlist>
        <listitem>
          <para><parameter>$baseName</parameter>. The base name of our route.
          The recommended format is similar to <uri>v1/example</uri> (for the
          default API route of your component) or
          <uri>v1/example/items</uri>.</para>

          <para>The <literal>v1</literal> part is used for versioning your
          API. Start with v1 for the first version of your component's API. If
          you make a backwards incompatible change bump it to v2, then v3 and
          so on.</para>

          <para>The next part <emphasis>should</emphasis> be your component's
          name without the <literal>com_</literal> prefix.</para>

          <para>Some components manage more than one content type. For example
          a helpdesk component will have at the very least a ticket and a
          reply content type, the former being a representation of all the
          metadata of the ticket (title, date, owner, …) and the latter being
          a representation of the actual posts sent by the participants. In
          these cases the secondary, tertiary etc content items get their own
          route by adding one more level in the base name of the route.</para>
        </listitem>

        <listitem>
          <para><parameter>$controller</parameter>. The <emphasis
          role="bold">name (string)</emphasis> of your component's controller
          which will be handling the request. This must be in all
          lowercase.</para>
        </listitem>

        <listitem>
          <para><parameter>$defaults</parameter>. This is an array of URL
          parameters which are added by default when parsing the route. At the
          very least it should be something like <code>['component' =&gt;
          '<replaceable>com_example</replaceable>']</code> where
          <replaceable>com_example</replaceable> is your component's
          name.</para>

          <para>If you are using Joomla's category management the API route to
          manage the categories for your component will be using the following
          defaults: <code>['component' =&gt; 'com_categories', 'extension'
          =&gt; '<replaceable>com_example</replaceable>']</code> where
          <replaceable>com_example</replaceable> is your component's
          name.</para>
        </listitem>

        <listitem>
          <para><parameter>$publicGets</parameter>. This is a boolean. By
          default it's false which means that only authenticated users will be
          allowed to list items using GET. If you set it to true then anyone
          who figures out the URL can use GET to get a list of items and read
          all items.</para>

          <warning>
            <para>If you set <varname>$publicGets</varname> to true you most
            likely have to override the <methodname>displayItem</methodname>
            and <methodname>displayList</methodname> methods in the respective
            controller to perform custom access control appropriate to your
            component. Most likely the items you want to show publicly are not
            <emphasis>all</emphasis> the items (including unpublished, deleted
            and possibly access-controlled) your component knows about.</para>
          </warning>

          <caution>
            <para>If you have a public route you MUST think about which fields
            you'll be including in your JsonapiView object. Not all fields are
            suitable for public display; that could lead to a security
            vulnerability known as information disclosure.</para>

            <para>For example, your forum component may be saving the IP
            address alongside the user ID and creation date and time of a
            forum post. DO NOT make the IP address and user ID available to
            the public. This combination is considered Personally Identifiable
            Information and can result in fines! Just the user ID may be
            privileged information depending on the context of the site
            (remember that usernames are not privileged information, but the
            internal user IDs are).</para>
          </caution>
        </listitem>
      </itemizedlist>

      <para>The second way to add routes to the ApiRouter is, of course, using
      its <methodname>addRoute</methodname> or
      <methodname>addRoutes</methodname> methods, just like any standard
      Joomla router object. The former accepts a single
      <classname>\Joomla\Router\Route</classname> object whereas the latter
      accepts an array of Route objects.</para>

      <para>The constructor of the <classname>\Joomla\Router\Route</classname>
      object accepts five arguments:</para>

      <itemizedlist>
        <listitem>
          <para><parameter>$methods</parameter>. This is an array of strings
          consisting of the HTTP verbs this route will be handling. The HTTP
          verbs must be in uppercase, e.g. <code>['GET']</code>,
          <code>['POST', 'PUT']</code>, or <code>['PUT', 'PATCH']</code> to
          mention three of the most practical examples.</para>
        </listitem>

        <listitem>
          <para><parameter>$pattern</parameter>. This is the same as the
          <parameter>$baseName</parameter> of the
          <methodname>createCRUDRoutes</methodname> method with an added
          feature. If you want to include parameters, e.g. an ID, you will
          define it as <code>:something</code> (note the colon in the front).
          This may be very familiar to those of you who've written routes for
          Symfony or Laravel applications. For example, the pattern
          <uri>v1/example/items/:id</uri> tells Joomla that this route will
          <emphasis>only</emphasis> match if the <uri>v1/example/items</uri>
          route is followed by <emphasis>something</emphasis> which will be
          made available as the request parameter named <literal>id</literal>.
          If that <emphasis>something</emphasis> does not exist the route does
          not match and Joomla won't use it. What that something must look
          like for the route to match? See <parameter>$rules</parameter>
          below!</para>
        </listitem>

        <listitem>
          <para><parameter>$controller</parameter>. This is <emphasis
          role="bold">different</emphasis> to the
          <parameter>$controller</parameter> of the
          <methodname>createCRUDRoutes</methodname> method in that it needs to
          have both the controller and the task, in all lowercase, separated
          by a dot. For example: <code>item.add</code>.</para>
        </listitem>

        <listitem>
          <para><parameter>$rules</parameter>. If your route pattern has
          parameters you will provide a Regular Expression pattern the value
          must match for the route to match. For example <code>['id' =&gt;
          '(\d+)']</code> tells Joomla that the <literal>id</literal>
          parameter (which was defined as <literal>:id</literal> in the
          pattern) must be an integer consisting of one or more digits —
          including the value <literal>0</literal>.</para>

          <tip>
            <para>This comes in very handy if you want to have the exact same
            GET route accept either a numeric ID or a text slug — assuming
            your component enforces unique slugs. In this case you would
            define two routes like this:</para>

            <programlisting>$router-&gt;addRoutes([
  new Route(['GET'], 'v1/example/items/:id', 'item.displayItem',
    ['id' =&gt; '(\d+)'], ['option' =&gt; 'com_example']),
  new Route(['GET'], 'v1/example/items/:slug', 'item.displayItem',
    ['slug' =&gt; '(.*)'], ['option' =&gt; 'com_example']),
]);</programlisting>

            <para>If the parameter is numeric the first route matches and the
            parameter is made available as the <literal>id</literal> request
            parameter. Otherwise, the parameter matches the second route and
            the parameter is made available as the <literal>slug</literal>
            request parameter. Your overridden
            <code>ItemController::displayItem</code> method would first check
            if the <literal>id</literal> request parameter exists and
            non-empty. If not, it would look for a non-empty
            <literal>slug</literal> request parameter and find the correct ID
            of the record to display by making a database query.</para>
          </tip>
        </listitem>

        <listitem>
          <para><parameter>$defaults</parameter>. This is the same as the
          <parameter>$defaults</parameter> of the
          <methodname>createCRUDRoutes</methodname> method with one addition.
          If you have a GET route and you want it to be accessible by
          unauthenticated users you need to add <code>['public' =&gt;
          true]</code> to the <parameter>$defaults</parameter> array. If you
          want it to only be accessible by authenticated users you need to add
          <code>['public' =&gt; false]</code>.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section xml:id="com-scheduled-tasks">
    <title>Integration with Scheduled Tasks</title>

    <para>Joomla 4.1 and later have an amazingly useful new feature called
    Scheduled Tasks. This is not really part of a component, it's just a
    plugin type, but since it is often used in conjunction with a component it
    makes sense to mention it here. You can read more about plugins in general
    in the <link linkend="plg">Plugins</link> chapter of this book.</para>

    <para>Scheduled Tasks allow the user to define repeated, unattended tasks
    which run on a schedule. It's like CRON jobs but without necessarily
    needing a CRON server on the site's server. They can be triggered with
    CRON jobs, with a special URL (e.g. using web-based pseudo-CRON services
    such as WebCRON.org), or automatically based on the site's traffic in what
    is called Lazy Scheduling.</para>

    <para>The best way to understand how a Scheduled Task plugin works is
    looking at the demo tasks plugin under
    <filename>plugins/task/demotasks</filename> folder on your site; it is
    part of Joomla itself.</para>

    <para>You create a plugin which provides one or more scheduled tasks in
    the <literal>task</literal> plugins folder. The plugin extension must
    implement <classname>\Joomla\Event\SubscriberInterface</classname>. It
    also needs to make use of the
    <classname>\Joomla\Component\Scheduler\Administrator\Traits\TaskPluginTrait</classname>.
    The trait provides all the magic.</para>

    <para>You need to handle three events:</para>

    <itemizedlist>
      <listitem>
        <para><literal>onTaskOptionsList</literal>. This is set to be handled
        by the <methodname>advertiseRoutines</methodname> method implemented
        in the <classname>TaskPluginTrait</classname>. This tells Joomla to
        add task types based on the contents of the
        <constant>TASKS_MAP</constant> constant of your plugin.</para>
      </listitem>

      <listitem>
        <para><literal>onExecuteTask</literal>. This is handled by the
        <methodname>standardRoutineHandler</methodname> method implemented in
        the <classname>TaskPluginTrait</classname>. When a scheduled task type
        the plugin can handle is being executed, this method will call your
        respective plugin method, as defined in the
        <constant>TASKS_MAP</constant> constant of your plugin.</para>
      </listitem>

      <listitem>
        <para><literal>onContentPrepareForm</literal>. This is handled by the
        <methodname>enhanceTaskItemForm</methodname> method implemented in the
        <classname>TaskPluginTrait</classname>. It tells the Scheduled Tasks
        manager to use the XML forms which define each task type's options
        when the user creates a scheduled task with this task type.</para>
      </listitem>
    </itemizedlist>

    <para>The <constant>TASKS_MAP</constant> constant is the most important
    part of the plugin. It is an array with task definitions like this:</para>

    <programlisting>private const TASKS_MAP = [
  'exampleTask.foobar' =&gt; [
    'langConstPrefix' =&gt; 'PLG_TASK_EXAMPLE_TASK_FOOBAR',
    'method'          =&gt; 'foobar',
    'form'            =&gt; 'foobar',
  ],
];</programlisting>

    <para>Do note that in this example we define one task type. It is possible
    and most of the times desirable for a task plugin to define more than one
    task types. In this case the <constant>TASKS_MAP</constant> array will
    have more than one elements.</para>

    <para>The outermost key for each entry, in our example
    <literal>exampleTask.foobar</literal>, tells Joomla what is the internal
    name of the task type we are defining. The convention is to use
    <literal><replaceable>something</replaceable>Task.<replaceable>taskName</replaceable></literal>
    where <replaceable>something</replaceable> is the name of our plugin and
    <replaceable>taskName</replaceable> is a fairly short name for the task
    type. This will be stored in the database; you must not change it between
    different versions of your task plugin.</para>

    <para>In the innermost array we have three keys:</para>

    <itemizedlist>
      <listitem>
        <para><literal>langConstPrefix</literal>. Required. The common prefix
        of the language strings used for this task type. The convention is to
        use the format
        <literal>PLG_TASK_<replaceable>SOMETHING</replaceable>_TASK_<replaceable>TASKNAME</replaceable></literal>
        where <replaceable>something</replaceable> is the name of our plugin
        and <replaceable>taskName</replaceable> is a fairly short name for the
        task type. The plugin's language INI file will have to define at least
        two language strings:</para>

        <itemizedlist>
          <listitem>
            <para><literal>PLG_TASK_<replaceable>SOMETHING</replaceable>_TASK_<replaceable>TASKNAME</replaceable>_TITLE</literal>.
            The title of the task type, displayed to the user. Keep it very
            short and descriptive.</para>
          </listitem>

          <listitem>
            <para><literal>PLG_TASK_<replaceable>SOMETHING</replaceable>_TASK_<replaceable>TASKNAME</replaceable>_DESC</literal>.
            A longer description of the task type, displayed to the user. Try
            to keep it under 50 words.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><literal>method</literal>. Required. The name of the plugin
        method which will be handling the task type. It's customary to name it
        after the <replaceable>taskName</replaceable> you used in the previous
        keys.</para>
      </listitem>

      <listitem>
        <para><literal>form</literal>. Optional. The filename, without the
        .xml extension, of the XML form file which adds the configuration
        parameters to the task type when the user is editing the definition of
        a task. This file is placed in the <filename>forms</filename> folder
        of the plugin.</para>
      </listitem>
    </itemizedlist>

    <para>The method which handles each task type has the following
    signature:</para>

    <programlisting>public function foobar(
  \Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent $event
): int</programlisting>

    <para>The <parameter>$event</parameter> parameter is a standard Joomla
    event object. To get the task definition from the event you need to
    do</para>

    <programlisting>$task = $event-&gt;getArgument('subject');</programlisting>

    <para>This gives you a
    <classname>\Joomla\Component\Scheduler\Administrator\Task\Task</classname>
    object.</para>

    <para>To get the configuration parameters of the task, as a simple
    <classname>stdClass</classname> object, you can do:</para>

    <programlisting>$params = $event-&gt;getArgument('params');</programlisting>

    <para>Your method does NOT set a result value to the
    <parameter>$event</parameter> object; it's not an event handler per se. It
    instead returns an integer value which must be one of the constants
    defined in
    <classname>\Joomla\Component\Scheduler\Administrator\Task\Status</classname>.
    You should realistically only use the following constants as return
    values:</para>

    <itemizedlist>
      <listitem>
        <para><constant>KNOCKOUT</constant>. An error occurred. The task
        execution will appear failed. The task will be rescheduled normally
        for its next execution according to its configured schedule.</para>
      </listitem>

      <listitem>
        <para><constant>OK</constant>. Success. The task execution will appear
        successful. The task will be rescheduled normally for its next
        execution according to its configured schedule.</para>
      </listitem>

      <listitem>
        <para><constant>WILL_RESUME</constant>. Temporary pause. The task has
        more work to do but halted execution to avoid a timeout. The task
        execution will appear to be ongoing. The task is rescheduled to resume
        execution as soon as possible i.e. the next time Joomla is asked to
        check whether any tasks need to execute. Please note that if your task
        is being resumed the following will return true:</para>

        <programlisting>$resuming = $event
  -&gt;getArgument('subject')
  -&gt;get('last_exit_code', Status::OK) === Status::WILL_RESUME;</programlisting>

        <para>Resumable tasks are great for long operations, like resizing
        hundreds of images or sending a newsletter to thousands of recipients,
        which might otherwise time out if you tried executing them in a single
        run. Split your work into small batches and/or check how much time has
        elapsed since you started doing some work. If a batch is complete
        and/or you have spent more than a configured maximum amount of time
        (typically useful values are 3, 5, 10, 20 and 30 seconds) return a
        Status::WILL_RESUME. Next time your task runs checks if the
        last_exit_code parameter is Status::WILL_RESUME and continue your work
        where you left off.</para>
      </listitem>
    </itemizedlist>

    <para>Earlier, we talked about having an XML form file to add parameters
    to the Scheduled Task type. The contents of the file look like
    this:</para>

    <programlisting>&lt;?xml version="1.0" encoding="utf-8" ?&gt;
&lt;form&gt;
  &lt;fields name="params"&gt;
    &lt;fieldset name="task_params"&gt;
      &lt;field
        name="my_parameter"
        type="text"
        label="PLG_TASK_EXAMPLE_TASK_FOOBAR_MY_PARAMETER_LABEL"
        description="PLG_TASK_EXAMPLE_TASK_FOOBAR_MY_PARAMETER_DESC"
        default=""
      /&gt;
    &lt;/fieldset&gt;
  &lt;/fields&gt;
&lt;/form&gt;        </programlisting>

    <para>The <tag>form</tag> tag has a <tag>fields</tag> tag whose name is
    <literal>params</literal> and inside it there is a <tag>fieldset</tag> tag
    whose name is <literal>task_params</literal>. The fields inside the
    <tag>fieldset</tag> are rendered in the task definition page.</para>

    <para>There is a special case where you can have a <tag>fieldset</tag> tag
    outside the <tag>fields</tag> tag; if you want your task to only be
    available for execution when Scheduled Tasks are executed through a Joomla
    CLI application command. This can be very useful if you have a very long
    running operation you do not want to (or cannot reasonably) break into
    smaller sub-tasks to make it a resumable task. In this case, we will add
    another <tag>fieldset</tag> tag whose name is <literal>aside</literal> and
    place a special hidden field in it. See below, highlighted in bold
    type:</para>

    <para><programlisting>&lt;?xml version="1.0" encoding="utf-8" ?&gt;
&lt;form&gt;
  <emphasis role="bold">&lt;fieldset name="aside"&gt;
    &lt;field name="cli_exclusive" type="hidden" default="1" /&gt;
  &lt;/fieldset&gt;</emphasis>
  &lt;fields name="params"&gt;
    &lt;fieldset name="task_params"&gt;
      &lt;field
        name="my_parameter"
        type="text"
        label="PLG_TASK_EXAMPLE_TASK_FOOBAR_MY_PARAMETER_LABEL"
        description="PLG_TASK_EXAMPLE_TASK_FOOBAR_MY_PARAMETER_DESC"
        default=""
      /&gt;
    &lt;/fieldset&gt;
  &lt;/fields&gt;
&lt;/form&gt;        </programlisting>That's really all there is to it! Since
    this is a regular Joomla plugin and assuming your component is native
    Joomla 4 (therefore its classes can autoload from anywhere in Joomla) you
    can of course pass your component's <classname>MVCFactory</classname>
    instance to the plugin and use it to get access to your component's Models
    and Tables. Therefore, your tasks can reuse your component's code.
    Remember that you write good software by staying DRY (Don't Repeat
    Yourself — reuse your objects and traits instead of copying and pasting
    the same code all over the place).</para>
  </section>

  <section xml:id="com-fields">
    <title>Custom fields</title>

    <para>Implementing custom fields is relatively simple. For starters, your
    component extension must implement the
    <interfacename>Joomla\CMS\Fields\FieldsServiceInterface</interfacename>.
    The two methods defined in the interface are implemented a lot like this
    in most cases:</para>

    <programlisting>public function validateSection($section, $item = null)
{
  if (!in_array($section, ['categories', 'item'])) {
    return null;
  }

  return $section;
}

public function getContexts(): array
{
  Factory::getApplication()-&gt;getLanguage()-&gt;load('com_example', JPATH_ADMINISTRATOR);

  return [
    'com_example.item'       =&gt; Text::_('COM_EXAMPLE_TITLE_ITEMS'),
    'com_example.categories' =&gt; Text::_('JCATEGORY'),
  ];
}</programlisting>

    <para>The former method makes sure that a context's section (the stuff
    after the dot) is a valid section where you expect custom fields to exist.
    In this example we expect two sections, <literal>categories</literal> and
    <literal>item</literal>.</para>

    <para>The latter method returns a list of contexts for our component where
    custom fields can be defined. We defined the two contexts corresponding to
    the sections we accept in the <methodname>validateSection</methodname>
    method. The return values will be used by <literal>com_fields</literal> to
    render the drop-down which lets the user select the section for which they
    define custom fields for your component.</para>

    <para>Your XML manifest must, of course, include two links to the Joomla
    Fields component, one for the Fields and one for the Fields group. Use one
    of the contexts you returned in the <methodname>getContexts</methodname>
    method above. Do NOT use the context for categories.</para>

    <programlisting>&lt;menu link="option=com_fields&amp;amp;view=fields&amp;amp;context=com_example.item"&gt;
  JGLOBAL_FIELDS
  &lt;params&gt;
    &lt;menu-quicktask&gt;&lt;![CDATA[index.php?option=com_fields&amp;view=field&amp;layout=edit&amp;context=com_example.item]]&gt;&lt;/menu-quicktask&gt;
    &lt;menu-quicktask-title&gt;COM_EXAMPLE_SUBMENU_FIELDS_NEW&lt;/menu-quicktask-title&gt;
    &lt;menu-quicktask-permission&gt;core.create;com_fields&lt;/menu-quicktask-permission&gt;
  &lt;/params&gt;
&lt;/menu&gt;

&lt;menu link="option=com_fields&amp;amp;view=groups&amp;amp;context=com_example.item"&gt;
  JGLOBAL_FIELD_GROUPS
  &lt;params&gt;
    &lt;menu-quicktask&gt;&lt;![CDATA[index.php?option=com_fields&amp;view=group&amp;layout=edit&amp;context=com_example.item]]&gt;&lt;/menu-quicktask&gt;
    &lt;menu-quicktask-title&gt;COM_EXAMPLE_SUBMENU_FIELD_GROUPS_NEW&lt;/menu-quicktask-title&gt;
    &lt;menu-quicktask-permission&gt;core.create;com_fields&lt;/menu-quicktask-permission&gt;
  &lt;/params&gt;
&lt;/menu&gt;</programlisting>

    <para>Your backend item edit pages <emphasis>should</emphasis> display the
    custom fields automatically — as long as you render all of the form's
    fieldset without looking for specific names. For example, something
    similar to this code:</para>

    <programlisting>&lt;?php
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Router\Route;
?&gt;
&lt;form action="&lt;?= Route::_('index.php?option=com_example&amp;view=item&amp;layout=edit&amp;id=' . $this-&gt;item-&gt;id) ?&gt;"
  aria-label="&lt;?= Text::_('COM_ATS_TITLE_TICKETS_EDIT', true) ?&gt;"
  class="form-validate"
  id="adminForm"
  method="post"
  name="adminForm"
&gt;
  &lt;input name="task" type="hidden" value=""&gt;
  &lt;?= HTMLHelper::_('form.token') ?&gt;

  &lt;?php foreach ($this-&gt;form-&gt;getFieldsets() as $fieldSet): ?&gt;

  &lt;div class="card mb-2"&gt;
    &lt;h3 class="card-header bg-info text-white"&gt;
      &lt;?= Text::_($this-&gt;form-&gt;getFieldsets()[$fieldSet]-&gt;label) ?&gt;
    &lt;/h3&gt;
    &lt;div class="card-body"&gt;
      &lt;?php echo $this-&gt;form-&gt;renderFieldset($fieldSet); ?&gt;
    &lt;/div&gt;
  &lt;/div&gt;

  &lt;?php endforeach; ?&gt;

&lt;/form&gt;</programlisting>

    <para>Joomla handles loading and saving the values of custom fields
    automatically as long as the Content - Fields plugin is published.</para>

    <para>In the frontend, fields' contents are returned through the
    <literal>onContentAfterTitle</literal>,
    <literal>onContentAfterDisplay</literal> and
    <literal>onContentBeforeDisplay</literal> events. Typically, the
    implementation in your HtmlView class looks similar to this:</para>

    <programlisting>&lt;?php
use Joomla\CMS\Factory;
use Joomla\CMS\MVC\View\HtmlView as BaseHtmlView;
use Joomla\CMS\Plugin\PluginHelper;

class HtmlView extends BaseHtmlView
{
  /**
   * The item object details
   *
   * @var    \Joomla\CMS\Object\CMSObject
   *
   * @since  1.6
   */
  protected $item;

  // ... your code here ...

  /**
   * Execute and display a template script.
   *
   * @param   string  $tpl  The name of the template file to parse; automatically searches through the template paths.
   *
   * @return  void|boolean
   */
  public function display($tpl = null)
  {
    $app        = Factory::getApplication();
    $state      = $this-&gt;get('State');
    $item       = $this-&gt;get('Item');
    $this-&gt;form = $this-&gt;get('Form');

    // ... your code here ...

    // Process the content plugins.
    PluginHelper::importPlugin('content');
    $offset = $state-&gt;get('list.offset');

    // Some plugins require a text attribute without checking if it exists
    $item-&gt;text = '';

    $app-&gt;triggerEvent('onContentPrepare', [
      'com_example.item', &amp;$item, &amp;$item-&gt;params, $offset
    ]);

    // Store the events for later
    $item-&gt;event = new \stdClass();

    $results = $app-&gt;triggerEvent('onContentAfterTitle', [
      'com_example.item', &amp;$item, &amp;$item-&gt;params, $offset,
    ]);
    
    $item-&gt;event-&gt;afterDisplayTitle = trim(implode("\n", $results));

    $results = $app-&gt;triggerEvent('onContentBeforeDisplay', [
      'com_example.item', &amp;$item, &amp;$item-&gt;params, $offset,
    ]);

    $item-&gt;event-&gt;beforeDisplayContent = trim(implode("\n", $results));

    $results = $app-&gt;triggerEvent('onContentAfterDisplay', [
      'com_example.item', &amp;$item, &amp;$item-&gt;params, $offset,
    ]);

    $item-&gt;event-&gt;afterDisplayContent = trim(implode("\n", $results));

    $this-&gt;item = $item;

    // ... your code here ...
  }
}</programlisting>

    <para>Your view template can then output
    <code>$this-&gt;event-&gt;afterDisplayTitle</code> etc in appropriate
    places.</para>

    <tip>
      <para>If you want to see how you can override Joomla's default custom
      field display to format it in a way that's more pleasant to the eye you
      can download Akeeba Ticket System Core (it's free of charge) and look at
      <classname>\Akeeba\Component\ATS\Site\View\Ticket\HtmlView</classname>.</para>

      <para>I have a method called
      <methodname>getCustomFieldsDisplay</methodname> which renders fields
      using custom layout overrides for the <literal>field.render</literal>
      and <literal>fields.render</literal> Joomla layouts. Ignore the section
      with the comment “Filter fields by ATS Private Display”, this is some
      special handling I use to make some fields invisible to the general
      public and only visible to the owner of the helpdesk ticket and the
      helpdesk personnel — this uses information from a custom plugin I ship
      with my software and is very specific to my use case.</para>

      <para>The two layout files
      (<filename>components/com_ats/layouts/field/render.php</filename> and
      <filename>components/com_ats/layouts/fields/render.php</filename>) are
      used to format the custom fields in a way which visually integrates more
      pleasantly than Joomla's default “word vomit” display style of nested
      unsorted lists.</para>

      <para>It goes without saying, my clients can of course choose to
      override these layout files OR the entire view template to render custom
      fields the way they see fit. For example, a site integrator might choose
      to have a custom field which is never displayed automatically, get its
      value using the field name and display it in a visually pleasant display
      in the view template. For instance, someone could have a custom field
      plugin which saves geographical coordinates. These could be displayed in
      the frontend of the site as an OpenStreetMap map. With custom fields,
      sky's the limit!</para>
    </tip>
  </section>
</chapter>