Work In Progress

This book is currently work in progress. Some sections are not yet written. Thank you for your understanding!

Backend menu items

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"?>
  <!-- Add fields to the request variables for the layout. -->
  <fields name="request">
  <fields name="params">
    <fieldset name="basic">
          <option value="">JHIDE</option>
          <option value="index.php?option=com_example&amp;task=item.add">JSHOW</option>


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.


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 what the menu item does.

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.


If you want to provide GET URL parameters the user cannot modify use field tags with type="hidden".

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.

[3] Core components put the language string key inside a <![CDATA[…]]> 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.