When building the navigation frame, vBulletin searches the includes/xml directory for files called cpnav_product.xml, where 'product' is replaced with the unique identifier for a product, for example cpnav_myproduct.xml.
An example cpnav XML file might look like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <navgroups product="myproduct"> <navgroup phrase="my_product" hr="true" permissions="canadminsettings" displayorder="1"> <navoption displayorder="10"> <phrase>my_product_manager</phrase> <link>myproduct.php?do=modify</link> </navoption> <navoption displayorder="20"> <phrase>add_new_item</phrase> <link>myproduct.php?do=add</link> </navoption> </navgroup> </navgroups>
Within the <navgroups> node resides any number (greater than one) of <navgroup> nodes. Each <navgroup> node has a number of attributes, some of which are optional while others are mandatory. The attributes are as follows:
phrase (mandatory) | The phrase attribute defines the name of the phrase used to display the text for the navigation group. This phrase should be a member of either the GLOBAL, Control Panel Global, or preferably the Control Panel Home Pages phrase group. The phrase should belong to the product being described. |
displayorder (mandatory) | The displayorder attribute is used to define the position of the navigation group relative to other navigation groups. A navigation group with a displayorder of 3 will appear before a group having displayorder 6 etc. Note that display order is distributed between all products, so if one product has two navgroups, with display order values of 10 and 30 respectively, while another product has a two navgroups with display order values of 20 and 40, the navgroups of the two products will appear interleaved in the navigation panel. |
text (optional) | The text attribute will be shown if the defined phrase does not exist. |
permissions (optional) | If a navigation group should be displayed only to administrators with specific permissions, the permissions attribute can be used to achieve this. As an example, if only administrators with Can Administer Styles permissions should be allowed to view a navigation group, you should add permissions="canadminstyles" to the <navgroup> tag. |
hr (optional) | If the hr attribute exists and has a value of true, an extra amount of space will be left underneath the navigation group in order to create logical groupings of navigation groups. |
<navoption displayorder="50"> <phrase>phrase_varname</phrase> <link>product.php?do=action</link> </navoption>
Navigation options have two child nodes, <phrase> and <link>. These are very simple nodes and perform an equally simple task. The <phrase> node contains the name of the phrase whose text will be displayed. As with the phrase attribute of the <navgroup> tag, this phrase should be defined within either the GLOBAL, Control Panel Global, or preferably the Control Panel Home Pages phrase groups, and should belong to the appropriate product. Secondly, the <link> node contains the relative URL to the script to which the option links.
vBulletin can support an unlimited number of cpnav_product.xml files, in order to allow any product to add to the default list of navigation links in the admin control panel.
Note:
For a fully-featured control panel navigation XML file example, see includes/xml/cpnav_vbulletin.xml