Dionysopoulos.me

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.

If you do not do anything else, Joomla will simply list all of your component's default menu items, 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.

The other option you have is to create menu item configuration XML files in your backend tmpl folder's sub-folders. This is a lot like managing frontend menu items, with a few extra features.

View XML files location and name

Your view XML files are placed in the sub-folders of your tmpl folder and they are named after the view template file. For example, if you have a component com_example, a view named welcome and a view template for that view named default the view XML file would be administrator/components/com_example/tmpl/welcome/default.xml.

View XML file structure

A view XML file has the following overall structure:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
  <layout title="COM_EXAMPLE_WELCOME_VIEW_DEFAULT_TITLE">
    <message>COM_EXAMPLE_WELCOME_VIEW_DEFAULT_DESC</message>
  </layout>
  <!-- Add fields to the request variables for the layout. -->
  <fields name="request">
    <fieldset
      name="request"
    >
      <field
        name="something"
        type="text"
        label="COM_EXAMPLE_WELCOME_VIEW_OPTION_SOMETHING_LABEL"
        description="COM_EXAMPLE_WELCOME_VIEW_OPTION_SOMETHING_DESC"
        />
    </fieldset>
  </fields>
  <fields name="params">
    <fieldset name="basic">
      <field
        name="menu-quicktask"
        type="radio"
        label="MOD_MENU_FIELD_SHOWNEW"
        layout="joomla.form.field.radio.switcher"
        >
          <option value="">JHIDE</option>
          <option value="index.php?option=com_example&amp;task=item.add">JSHOW</option>
      </field>

      <field
        name="menu-quicktask-title"
        type="hidden"
        default="COM_EXAMPLE_MENUS_NEW_ITEM"
        />
    </fieldset>
  </fields>
</metadata>            

The root tag of the XML document is always <metadata>. The <layout> section is mandatory. The <fields> sections are optional.

The <layout> section

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.

The title attribute contains a language string which appears as the title of the menu type selector and in the Menu Item Type 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.

The content of the <layout> tag can either be empty or contain exactly one <message> tag with a text content which is also a language string key^[3]. 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.

The request <fields> section

The XML file can have one or more <fields> sections. The first section we see in the example above are the request fields, wrapped in a <fields name="request"> 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 name attribute of the field tag and its value will be the URL parameter's value as well.

This section contains exactly one <fieldset> tag with name="request". The fields in this set will be displayed in the Details tab of the menu item edit page.

Remember that if you do not define any fields or omit this section altogether the resulting link will be index.php?option=com_example&view=something&layout=default where com_example is the name of your component, something is the name of the view (the name of the subfolder the XML file is in) and default is the name of the XML file without the .xml extension.

The parameters <fields> section

The next optional section is wrapped in a <fields name="params"> tag and has one or more <fieldset> tags, rendered as tabs in the menu item edit page. If you do not specify a title and name your field set basic it will render as a tab labelled Options.

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 <params> tags in the component's menu and, in fact, have the same names — so we're not copying the documentation here again.