Creating component template XML files

Add to Menu is an administrator module that gives you the possibility to quickly add menu items of the item you are viewing at that particular moment.

Add to Menu supports a large number of page types by default. Of course the standard content types (sections, categories, articles, contacts, users, polls, etc) are supported. But also a selection of 3^rd party components like FLEXIcontent, K2, MyBlog and RedShop. More will be added in future releases.

If you need the functionality of Add to Menu for a component it does not yet support, you will have to make one or more component template files (xml) for Add to Menu. In this reference guide you will learn how you can do that.

File and folder structure

Once Add to Menu is installed, you can find a folder called 'components' in the Add to Menu module folder (administrator/modules/mod_addtomenu/components).
In this 'components' folder you will see several other folders for the different components. Every folder contains one or more template xml files which Add to Menu uses.

If you are viewing a page in your administrator interface, Add to Menu will search for a folder matching the component (option) of that page. If there is a folder, it will go through the template files contained in that folder. As soon as it finds one that passes the requirements as defined in the 'requirements' section, it will use that component template (and will stop looking further in the folder).

For example, when viewing the administrator url

index.php?option=com_categories&section=com_content

Add to Menu will search through the folder 'com_categories'. And when viewing

index.php?option=com_virtuemart&page=product.product_list

Add to Menu will search through the folder 'com_virtuemart'.

As for file names, it is not too important what you call these template files. You may label them using your own naming scheme, as long as they end in '.xml' (For example, 'category.xml' or 'addcategory.xml'). Add to Menu goes through the files in alphabetical order, so you can use the names to control the order.

Template files

The template file is an xml file containing all the information for Add to Menu to let it know when to show the Add to Menu button, what to show in the modal popup window and with what data it should create the menu item.

In this section all parts of the xml file are explained. There is an example.xml file (in administrator/modules/mod_addtomenu/components/example) which you might want to look into. Also take a look at the already available template files (like for com_content) to see how things are done.

Inside the main <addtomenu> tags you can find general information tags and the <params> tag. Only the information inside the <params> tag is used by Add to Menu. The general information is not necessary, but can help you understand what the template is for and who made it. This also holds the copyright information. Maybe this information can be used in future versions of Add to Menu.

Within the <params> tag, there are 7 sets of information, each affecting the different aspects of creating and storing a link when using the Add to Menu button.

1) Name <name>

This is displayed as the type of menu item in the header of the modal popup window (and in the tooltip). It is best to use the same name as is displayed as menu item type in the 'Select Menu Item Type' list (visible when adding a new menu item to a Joomla menu). But you can name this how you want.

<name>Standard Product Layout</name>

2) Adjust Height <adjust_height>

The height of the Add to Menu modal popup window is dependent on the number of (extra) options. If – for whatever reason – the modal popup window does not get the right size, you can use this tag to adjust it. Positive numbers will increase, negative numbers will decrease the height with so many pixels.

<adjust_height>12</adjust_height>

3) Requirements <required>

This set of values determines whether or not the template should be used on the page.
The parameters and values are checked against the available information. That information can be present in:

• Request GET (url)
• Request POST
• User states

Usually all request parameters are present in the url (GET). But some pages are opened via POST and you will only see index2.php as url. Then you will have to know/find out what parameters and values are passed on to the page. For instance by looking in the html source of the page before (form elements).
The user states are for example values from filters in the lists, like when you select a section from the select box in the article list.

This is the syntax for every parameter and value set.

<parameter>value</parameter>

Multiple values

If multiple values are possible to pass requirements, just separate the values with comma's.

<type>articles,items</type>

Any value

If any value is ok (except empty), use the wildcard '*'.

<cid>*</cid>

If any value except empty, 0 or false is ok, use the wildcard '+'.

<catid>+</catid>

Not present

If you want to check for pages that do not have a certain parameter set, just leave the value empty.

<task></task>

Requirements example

For example, if you want to match an url like:
index.php?option=com_categories&section=com_content&task=edit&cid[]=12
but also match:
index.php?option=com_categories&task=edit&cid[]=34
the requirements are:

• 'task' should be 'edit',
• 'section' should be 'com_content' or not set (empty),
• 'cid' should have some value

The required tag should be:

<required>
<task>edit</task>
<section>,com_content</section>
<cid>*</cid>
</required>

As you might have noticed, 'cid' is enough to match 'cid[]'.

4) Database select <dbselect>

The actual menu item that is created consists of the name, alias, url and extra parameters. The <dbselect> part searches for the name (and alias) that has to be used.

The name can be defined as a generic fixed word.

<dbselect>
<name>Article name</name>
</dbselect>

Add to Menu will create the alias based on the name the way you are familiar with in Joomla. If you want to use a different alias than one based on the name value, you can define it separately.

<dbselect>
<name>Article name</name>
<alias>art</alias>
</dbselect>

But it is of course much nicer if the name (and alias) is grabbed from the name or title of whatever item you are viewing. You can tell Add to Menu where to get this information from the database.

First define which database to search in.

<table>#__categories</table>

Then use the <where> tags to limit the search results to 1 item.
You can use any available parameter values (GET, POST, user states), by preceding it with a '$'. So if you want the id field in the database table to match the cid[] value in the url, use:

<where>
<id>$cid</id>
</where>

And then you can define what table field contains the name (and optionally what field contains the alias).

<name>title</name>
<alias>alias</alias>

So to wrap it up, the full <dbselect> tag in this example.

<dbselect>
<table>#__categories</table>
<where>
<id>$cid</id>
</where>
<name>title</name>
<alias>alias</alias>
</dbselect>

5) Extra options <extras>

This is where you can define extra options to display within the Add to Menu modal popup window. These extra values that the user can select can be used in the final url or in the extra parameters of the menu item.

Each extra option uses an <extra> tag inside the <extras> tag.

First define the label of the option in the <name> tag. This label will be placed before the form element.

<name>Layout</name>

Then set the type of the form element. You can choose from text, textarea, hidden, select and radio.

<type>select</type>

Then you have to define the parameter name. This name can be used later on in the url and extra parameters of the menu item.

<param>layout</param>

And finally you define the value(s) of the parameter.
For element types text, textarea, hidden only 1 value is possible.

<value>1</value>

For element types select and radio, place the <value> tags within a <values> tag. You can have one or multiple <value> tags. Each <value> tag has a name and value defined inside.

<values>
<value>
<name>Category Layout</name>
<value></value>
</value>
<value>
<name>Blog Layout</name>
<value>blog</value>
</value>
</values>

You can also use a <style> tag to add some custom styling to the element.

<style>width:50px;</style>

Here is a full example of what an extra 'Layout' select box would look like.

<extras>
<extra>
<name>Layout</name>
<type>select</type>
<param>layout</param>
<values>
<value>
<name>Category Layout</name>
<value></value>
</value>
<value>
<name>Blog Layout</name>
<value>blog</value>
</value>
</values>
</extra>
</extras>

In this case a Layout parameter will be available. You can use the value (which will either be empty or 'blog') via the variable $layout.

You can also hide/show certain extra fields depending on the value of another. So, for example, if you want to show an extra text field if the user selects 'Blog Layout' from the Layout select field, you can!

The syntax for this show/hide (toggler) option would in this case be:

<extra><type>toggler</type><param>layout</param><value>blog</value></extra>
<extra>
<name>Num Leading</name>
<type>text</type>
<param>num_leading_articles</param>
<value>1</value>
<style>width:50px</style>
</extra>
<extra><type>toggler</type></extra>

The first line is telling Add to Menu that the extra text field should be shown when the 'layout' variable has been assigned the value 'blog', or in other words, if 'Category Blog' has been selected in the select drop down menu. The last line closes the toggler area.

6) URL parameters <urlparams>

Here you can define how the url part of the menu item will be built up. You can use any available variables from the request (GET/POST), user states, but also from the extra options we just discussed.

So you can just define all url parameters (name + value) in the order you need them.

<urlparams>
<option>com_content</option>
<view>category</view>
<layout>$layout</layout>
<id>$cid</id>
</urlparams>

This will result in an url that looks like:

index.php?option=com_content&view=category&layout=blog&id=12

(where layout and id are variable)

7) Menu item parameters <menuparams>

The final part defines what other menu item parameters need to be set. Again, you can use all available variables from the request (GET/POST), user states and the extra options.

You'd need to find out the parameter names for the menu item and then assign the values in the same way as is done in the rest of the template.

The parameters you can set can be found in the xml file that of the actual component view. For example, in the folder components/com_content/views/category/tmpl, the parameters for the Standard Category layout are stored in the 'default.xml' file, while the ones for Category Blog layout are in the 'blog.xml' file.

Another way you can find the available parameters id to look in the html output of the menu item edit page.

The third option is to look in the menu table in the database. The parameters are stored in the params field.

An example of what the <menuparams> set might look like.

<menuparams>
<num_leading_articles>$num_leading_articles</num_leading_articles>
<num_intro_articles>$num_intro_articles</num_intro_articles>
<num_columns>$num_columns</num_columns>
<num_links>$num_links</num_links>
</menuparams>

You will find what parameters are available and the possible values you can assign to them for the component in the XML file of that component's view, as the params are actually the names given to each parameter in the XML file.