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:
This block of XML defines a navigation group containing two links, as seen here:
<?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>
The root node in the XML file is <navgroups>, which also has an attribute of product, which should correspond to the name of the product in the filename - so for example, cpnav_myproduct.xml should have a root group of <navgroups product="myproduct">.
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:
|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.|
|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.
|The text attribute will be shown if the defined phrase does not exist.|
|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.
|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.|
Much like the <navgroup> tag, the displayorder attribute here controls the order of the links within the navgroup. A link with displayorder = 10 will be displayed before a link with displayorder = 20.
<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.
For a fully-featured control panel navigation XML file example, see includes/xml/cpnav_vbulletin.xml