Hey Peter,

I'm a big fan of your extensions, particularly the ModuleAnywhere and AdminBar, but as I work with AddToMenu I can see it offers very powerful shortcuts to otherwise tedious multi-screen jobs. I especially like the fact that you can create your own custom templates for specific components, this is something I would like to take advantage of to create my own shortcuts for the components I use frequently.

I think I've managed to figure out how the parameters work within the template and what each section represents, but I'm having trouble understanding exactly how to get certain templates to apply to the AddtoMenu button on specific component content views. Let me share with you what I understand of how the template works so you can correct me or fill the gaps where required.

(Consider this post as part of the documentation that is missing for this plugin, my way of saying thanks as well as figuring out how this works... )


First off: Files and folders
As Peter said later in this thread, AddtoMenu goes through all the files in the folder that has the same name as the 'option' (in url) of the current page. It checks the requirements and if they pass, it uses that component template (and stops looking further in the folder).

So for example, since the Category component is referred to in the URL as "option=com_categories", you need to place any templates regarding this component in a folder called "com_categories". Similarly, if you want to create some templates for Virtuemart (for example), you would store them in a folder called "com_virtuemart", since that is how it is referred to in the URL (option=com_virtuemart).

As for file names, it is not too important what you call the templates, you may label then using your own naming scheme, as long as they end in ".php" (For example, "category.php" or "addcategory.php"). AddtoMenu goes through each template file that is stored in the folder named after the component Joomla is currently accessing, regardless of their filename, and checks to see if any of those files contains parameters in the "Requirements" section that match the parameters in the URL. If there's a match, AddtoMenu uses that template.


Building your templates
Within the brackets of the $component = array ( ) in each template, there are 7 sections with parameters to modify, each affecting the different aspects of creating and storing a link when using the AddtoMenu button (I'll use the Category menu item as example):

1) Name
This refers to the name of the menu item type as it is listed in the "Select Menu Item Type" list that displays when adding a new menu item to a Joomla menu. Names like "Standard Contact Layout", "Category Blog Layout", and "Standard Product Layout" are examples of what would be used for this parameter. For example,

'name' => 'Standard Product Layout'

This name also appears as the title of the AddtoMenu modal box, just as a reminder.



2) Adjust Height
This directly affects the height of the AddtoMenu modal window, as the tip says negative values will reduce size while positive numbers will add to the original size, so in case you need more or less room, you have this setting to control.



3) Requirements (get/post variables)
Here you set the parameters that will have to be present in the URL of the menu item's parameters page so that this particular template would be used by the AddtoMenu button to build the relevant link. For example, in this piece of code:

'required' => array(
'task' => 'edit',
'section' => array( '', 'com_content' ),
'cid' => '*',
),

the template that contains this code would be used by AddtoMenu when a URL contains the parameters "task=edit", "section=com_content" and "cid[]={something}" in its structure. For example, when editing a Category Layout page in the Articles section, the URL looks like this:

index.php?option=com_categories&section=com_content&task=edit&cid[]=25&type=content

If you have a template that has the following code present in the "requirements" section:

'required' => array(
'task' => 'edit',
'section' => array( '', 'com_content' ),
'cid' => '*',
'type' => 'content',
),

Since all the variables required by the template are present, the AddtoMenu button appears and uses that template to display the contents of the modal window and control how the menu link gets made.



4) Dabase select
This is where you define which information gets pulled from which table in Joomla's database and which fields the information will be coming from. This is also where you bind which fields from which table will be used to fill the fields in the jos_menu table when building the link. For example, in this piece of code:

'dbselect' => array(
'table' => '#__categories',
'where' => array(
'id' => '$cid'
),
'name' => 'title',
'alias' => 'alias',
),

the 'table' parameter refers to the "jos_categories" table in the Joomla database, and the 'where' parameter followed by the 'id' parameter in its array is referring to the "id" field in the "jos_categories" table that matches the cid in the URL (so AddtoMenu has a means of referring to the exact category record).

The 'name' and 'alias' parameters refer to the fields in the "jos_menu" table that need to be filled in for each record in order for the menu link to be saved correctly. The 'title' and 'alias' parameters referred to by 'name' and 'alias' are the fields from the "jos_categories" table record which AddtoMenu will pull data from to populate the 'name' and 'alias' fields in the "jos_menu" table.

To make this a little clearer, suppose we have a category that we have labelled "Test category", and the alias for the category (used in SEF and other areas) is auto-generated as "test-category". Using this code:

'name' => 'title',
'alias' => 'alias',

the title of the category, "Test category", will be used as the name of the menu link, as the alias "test-category" will be used as the alias for the menu link.



5) Extra select options
This is where you can define extra options to display within the AddtoMenu modal box that pops up when clicking on the AddtoMenu button. These options can directly affect the URL that is built for the menu link. For example, in this piece of code:

'extra' => array(
array(
'type' => 'select',
'name' => 'layout',
'label' => 'Layout',
'value' => array(
'' => 'Standard Category Layout',
'blog' => 'Category Blog Layout',
),
),
),

a new variable is being created just for this template that will let the user choose whether they'd like this menu link to the category to be created using a Standard Category layout or using the Category Blog layout. The 'type' parameter refers to what kind of input box you'd like to generate for the AddtoMenu modal box to offer, in this case 'select' will display a dropdown menu box. 'name' refers to the name of this variable that AddtoMenu will refer to later when building the link. 'label' refers to the label that will appear next to the dropdown box in the AddtoMenu modal box. The 'value' array creates the different options available in the dropdown box.

This code:
'' => 'Standard Category Layout',
'blog' => 'Category Blog Layout',

tells AddtoMenu that if 'Standard Category Layout' is selected from the dropdown box, the value of the 'layout' variable will be blank. Conversely, the layout variable will be assigned the value 'blog' if 'Category Blog Layout' is chosen. So look at it like this:

Selecting the 'Standard Category Layout' means $layout=''
Selecting the 'Category Blog Layout' means $layout='blog'



6) URL params
Here is where the you define the parameters that will be used to build the URL for the menu link. Let's use this code as an example:

'urlparams' => array(
'option' => 'com_content',
'view' => 'category',
'layout' => '$layout',
'id' => '$cid',
),

Suppose the id of the category you want to link to is 25, and 'Category Blog Layout' was selected from the dropdown box. The URL would be built to look like this:

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

Inversely, if 'Standard Category Layout' was selected instead, the URL would be built to look like this:

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

because the $layout variable has been assigned no value.



7) Menu item params
This lets you define what values you'd like to set for any additional parameters that are available in the menu item type's "Menu Parameters" section. You'd need to find out the names of the parameters for the menu item and then assign them values in the same way as is done in the rest of the template.

For example, one of the menu items that comes when you install Joomla's sample data is a link to the "Content Layouts" page. In that record in the jos_menu table, there is a list of parameters listed in the param field that include:

pageclass_sfx=
menu_image=-1
secure=0
show_noauth=0
link_titles=0
show_intro=1

just to name a few. To use these parameters and assign them specific values, you would use the following code:

'menuparams' => array(
'pageclass_sfx' => ' '
'menu_image' => '-1'
'secure' => '0'
'show_noauth' => '0'
'link_titles' => '0'
'show_intro' => '1'
),

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. For example, in the folder components\com_content\views\category\tmpl, the parameters for the Standard Category layout are stored in the "default.xml", while the ones for Category Blog layout are in the "blog.xml" file.

[edit:] Thanks to Peter for his help in clearing things up so that I could update this guide to be more thorough.


I'm working with a component called "redSHOP", a fairly new but feature-packed and very robust eCommerce extension for Joomla. I'd like to be able to create links quickly through AddtoMenu for products, categories and manufacturers, each of which have different parameters required when building links. If I can hack this, we can use the same idea to create AddtoMenu shortcuts for VM as well (I'm sure the VM fans out there would appreciate this feature. )


Looking forward to hearing from you about this!

Great, thanks... I'll read it when I have a few hours off

I wasn't expecting this to get "stickied", but thanks for doing that, it means other people interested in making their own templates will have more documentation to work with.

I'll be waiting to hear back from you about this "guide" and in particular about how to name the template filenames. It sounds like you have quite a bit on your plate, so I'll understand if it takes some time to go through and respond to. I've been working at this for the last week and have hit a wall, so I'm more than just a little anxious to crack it and finally get my own templates working...

(Side note, I notice forum members cannot edit their own posts. So if I have any amendments, I guess they'll have to go into a new post?)

Turned on post editing.
Also added a link on www.nonumber.nl/extensions/addtomenu to this thread.

The naming is as followed:
'Add to Menu' goes through all the files in the folder that has the same name as the 'option' (in url) of the current page. It checks the requirements and if they pass, it uses that component template (and stops looking furter in the folder).
So the file name itself is not very important, the folder name is.

Okay, so the component's name is com_redshop, so I created a folder in the "components" folder called "com_redshop".

There are also three separate template files, one for each view that I'd like AddtoMenu to appear on and allow me to make a shortcut for:
redSHOP Category - currently called "category.php"
redSHOP Product - currently called "products.php"
redSHOP Manufacturer - currently called "manufacturer.php"

I've configured each template to the best of my ability based on the parameters I have to work with in the URLs of both the front end page as well as the back end "edit" page, and by my logic they should be working. At the moment the AddtoMenu button appears on the Category and Manufacturer page, I can't seem to get it to appear on the Product page no matter what I do. In addition, clicking on the AddtoMenu button on either of those pages will bring up the template I made for the "manufacturer" page. I also tried to make a select dropdown menu with two options within the manufacturer template, similar to the one for the Category template, but I'm getting 3 text boxes instead each preceded by a letter that I'm not sure where is being pulled from...

In short, I'm still not 100% sure of what's going on.

Since it would take a long time to explain, would be possible to send you an email with screenshots and the templates I have made for you to take a look at? I realize you're busy, but if you can show me how to correct the templates so the AddtoMenu button appears and works properly on each of those three pages, it'll help me understand better, and of course I'd be very grateful... Should I send it to you via your contact page?

Yeah, you can send me the stuff via email. Also admin access to your site would be handy...

Thanks, I sent an email to peter @ nonumber.nl with an attachment containing everything you'll need.

Just a quick post to thank Peter for his assistance, I've updated the guide with more complete instructions. If anyone requires further clarification on anything, please don't hesitate to ask and one of us will help you accordingly.