PDA

View Full Version : [How-To] Add entries to AdminCP Navigation Menu


Andreas
08 Jun 2005, 22:34
The AdminCP Navigation is now controlled through XML files.
To add custom entries, you must create a new file cpnav_yourhack.xml and place it in directory includes/xml.

This XML-File constist of 6 important tags:

<navgroups>
This indicates that this is a XML File containing navgroups.
It has one parameter product that should be set to your product identifier or vbulletin if it does not belong to any product.
<navgroup>
This is the container for one Settings-Group, like Styles & Templates, vBulletin Options, etc.
It has three parameters: phrase/text, permissions and hr.
If you are using phrases, phrase must contain the variable name, if you are using hardcoded text then text must contain the label.
Parameter permissions (optional) can be used to check an administrator permission, like canadminoptions.
Parameter hr (optional) can be used to put a spacer below this navgroup.
<navoption>
This is one Menu-Entry.
<phrase> or <text>
This must contain the varname or hardcoded text for the menuetry.
<link>
Tag link must contain the URL.
You can use {$vbulletin->config[Misc][modcpdir]} to point to the ModCP directory here, no matter how it is actually called


Example

<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="vbulletin">
<navgroup phrase="demohack_settings" hr="true">
<navoption>
<phrase>demohack_foo</phrase>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<phrase>demohack_modcp</phrase>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
<navgroup text="Demohack Settings">
<navoption>
<text>Demohack Foo</text>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<text>Demohack ModCP</text>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
</navgroups>


Update for Beta 3
With Beta 3 a new parameter displayorder has been introduced. This parameter is valid for Tags navgroup and navoption.
This way it is possible to control in which order the Navgroups and Links will be displayed, and you can also add custom Links to existing Navgroups.
To do so, your navgroup must have them same displayorder and Phrase Varname as the existing group:


<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="vbulletin">
<navgroup phrase="forums_and_moderators" displayorder="60">
<navoption displayorder="1">
<text>Top-Link Forums &amp; Moderators</text>
<link>demohack.php?do=foo</link>
</navoption>
</navgroup>
</navgroups>


Then Top-Link Forums & Moderators will be the first link in Navgroup Forums & Moderators (Displayorder: 60).

To find out the Displayorder for existing groups, take a look at cpnav_vbulletin.xml.

This How-To is (C) 2005 by KirbyDE and you are not allowed to redistribute it in any way without my explicit consent.

Creative Suite
13 Jun 2005, 22:51
Thanks..

rjordan
13 Jun 2005, 23:20
So, in doing this, does this take care of the issues with no hooks being included in the AdminCP navigation menu? I know that it does not take care of not having hooks in the individual modules, just refering to the main selection menu.

feldon23
15 Jun 2005, 05:10
So, in doing this, does this take care of the issues with no hooks being included in the AdminCP navigation menu? I know that it does not take care of not having hooks in the individual modules, just refering to the main selection menu.
Site administrators upload the XML file prepared by the hack author and presto, new items appear in the AdminCP.

The bummer here is that hack authors can't specify which existing group to add a menu item under (for instance, adding a new PM-related funtion or feature under the existing PM AdminCP tree) nor can hack authors specify a group that their hack should appear above or below. A hack author might want to add "Clans" right below Usergroups or Promotions.

I'm guessing that new menus created with this XML technique appear way at the bottom?

Of course to add all the functionality I am talking about, the admincp XML file would need to be cached in a "merged" state.

stlmike
22 Jun 2005, 08:13
Thanks KirbyDE in how to do this...

Chris M
22 Jun 2005, 13:12
Site administrators upload the XML file prepared by the hack author and presto, new items appear in the AdminCP.

The bummer here is that hack authors can't specify which existing group to add a menu item under (for instance, adding a new PM-related funtion or feature under the existing PM AdminCP tree) nor can hack authors specify a group that their hack should appear above or below. A hack author might want to add "Clans" right below Usergroups or Promotions.

I'm guessing that new menus created with this XML technique appear way at the bottom?

Of course to add all the functionality I am talking about, the admincp XML file would need to be cached in a "merged" state.
They seem to appear at either the top or bottom, quite randomly...

It is bizzarre to be sure...

I hope the Devs listen to the requests and create some kind of display order feature for the CP Nav ;)

Satan

Andreas
22 Jun 2005, 13:16
They seem to appear at either the top or bottom, quite randomly...

They appear in the sort-order that is provided by the OS when you list cpnav_*.xml Files.

Chris M
22 Jun 2005, 13:18
Aha - Glad someone knows ;)

Satan

Dream
27 Jun 2005, 21:12
so kirby what changed in vb 3.5 beta 3? are you going to update this

Andreas
27 Jun 2005, 21:24
Updated :)

Dream
27 Jun 2005, 21:35
thanks

sv1cec
01 Jul 2005, 14:27
I have a problem with the xml file which describes the menu I want to appear in the AdminCP.

If one of the options contains a link, which includes as a character, the character &, the menu does not appear. For example:


<navoption displayorder="100">
<text>Statistics - Warnings Per User</text>
<link>admin_warn.php?act=viewwarnedusers&type=warnings</link>
</navoption>


Them the menu refuses to appear. Instead, an empty menu is shown.

If I replace the & character with a - or something, everything works.

Is this a bug in the way the xml is handled or is this character not allowed? If so, how can I pass a link, which includes such a character?

Thanks

Andreas
01 Jul 2005, 14:49
& is only allowed in CDATA (Character Data) Sections, otherwise you must use the entity &amp;

sv1cec
01 Jul 2005, 15:05
Thanks Kirby, much appreciated.

Any other characters that are not allowed, that I need to be aware of? As you can tell, I have no expertise in XML.

Thanks again.

Andreas
01 Jul 2005, 15:53
[ ] < > ' "

sv1cec
01 Jul 2005, 15:58
Thank you Sir!

Ranma2k
01 Jul 2005, 23:58
The AdminCP Navigation is now controlled through XML files.
To add custom entries, you must create a new file cpnav_yourhack.xml and place it in directory includes/xml.

This XML-File constist of 6 important tags:

<navgroups>
This indicates that this is a XML File containing navgroups.
It has one parameter product that should be set to vBulletin
<navgroup>
This is the container for one Settings-Group, like Stales & Templates, vBulletin Options, etc.
It has three parameters: phrase/text, permissions and hr.
If you are using phrases, phrase must contain the variable name, if you are using hardcoded text then text must contain the label.
Parameter permissions (optional) can be used to check an administrator permission, like canadminoptions.
Parameter hr (optional) can be used to put a spacer below this navgroup.
<navoption>
This is one Menu-Entry.
<phrase> or <text>
This must contain the varname or hardcoded text for the menuetry.
<link>
Tag link must contain the URL.
You can use {$vbulletin->config[Misc][modcpdir]} to point to the ModCP directory here, no matter how it is actually called


Example

<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="vBulletin">
<navgroup phrase="demohack_settings" hr="true">
<navoption>
<phrase>demohack_foo</phrase>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<phrase>demohack_modcp</phrase>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
<navgroup text="Demohack Settings">
<navoption>
<text>Demohack Foo</text>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<text>Demohack ModCP</text>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
</navgroups>


Update for Beta 3
With Beta 3 a new parameter displayorder has been introduced. This parameter is valid for Tags navgroup and navoption.
This way it is possible to control in which order the Navgroups and Links will be displayed, and you can also add custom Links to existing Navgroups.
To do su, your navgroup must hav them same displayorder and Phrase Varname as the existing group:


<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="vBulletin">
<navgroup phrase="forums_and_moderators" displayorder="60">
<navoption displayorder="1">
<text>Top-Link Forums & Moderators</phrase>
<link>demohack.php?do=foo</link>
</navoption>
</navgroup>
</navgroups>


Then Top-Link Forums & Moderators will be the first link in Navgroup Forums & Moderators (Displayorder: 60).

To find out the Displayorder for existing groups, take a look at cpnav_vbulletin.xml.


ok a Q about vb 3.5 beta 3 code
if we open <text> shouldn't we close it with </text >

why are we closing it as </phrase>
in your code you show
<navoption displayorder="1">
<text>Top-Link Forums & Moderators</phrase>
<link>demohack.php?do=foo</link>
</navoption>


i find it confusing .. or it's just a typo :D

merk
02 Jul 2005, 00:13
Its a typo.

Andreas
02 Jul 2005, 00:40
Jep. That happens when you just "blindly" write "Code" without testing it ;)
Fixed.

Cloudrunner
02 Jul 2005, 22:50
Is there a way with this XML to add a separator between navoptions to segregate different areas of the same navigation?

i.e.

*NAVGROUP TITLE*
view something
view somethingelse
*SEPARATOR*
edit something
edit somethingelse
*SEPARATOR*
delete something
delete somethingelse

Is this possible without having it get linked? I've already tried a single character in the link but it sends the navigation frame over into the main view if you accidentally click that....

Andreas
02 Jul 2005, 22:53
You can add separators between Navgroups, but AFAIK it's not possible to add Spearators between Nav Options.

Christine
02 Jul 2005, 23:24
Thanks Kirby. :)

I am SO happy to see this addition to Beta3. :D

Cloudrunner
03 Jul 2005, 00:23
You can add separators between Navgroups, but AFAIK it's not possible to add Spearators between Nav Options.
crap

sv1cec
03 Jul 2005, 06:41
This one is not directly related to the subject, but it also is, somehow.

In the past, I modified the AdminCP menu of a hack of mine, depending on a parameter the user entered, adding or removing a line in the menu. If the condition of this parameter was changed, then I forced a reload of admincp, by redirecting the program to admincp/index.php.

Obviously this method can no longer be used, and I have to have two different cpnav_xxx.xml files, one with the additional line and one with out it, and copy the one I need to the /includes/xml directory. However, my php knowledge is not that extensive, so can some one please tell me how I can do something like (in pseudo code):


if (parameter==1)
{
copy /temp/menu1.xml /includes/xml/cpnav_aws.xml
}
else
{
copy /temp/menu2.xml /includes/xml/cpnav_aws.xml
}



Thanks for your help.

Revan
03 Jul 2005, 23:54
I believe this can easily be solved by offering the else-excluded option anyways, and then have this parameter check before any other code in the section in the file, and print out a cp message in the event that the option would not have been shown on the old menu.

HakkieDEV
04 Sep 2005, 22:44
Great tutorial again, thanks mate.

Cap'n Steve
28 Sep 2005, 03:46
It would be really nice to be able to add options to existing groups. It's just much more organized than forcing every tiny little hack to have its own group. Any chance of this being added in the future?

Andreas
28 Sep 2005, 09:58
Already possible since Beta 3 ...

Nullifi3d
06 Oct 2005, 01:56
How do I add my own options into the modcp?

Andreas
06 Oct 2005, 02:37
Hook mod_index_navigation

cinq
07 Oct 2005, 09:11
Any ideas how to do the same, but to add to the navigation panel in the modcp Kirby ?

Andreas
07 Oct 2005, 11:54
Hook mod_index_navigation

Nullifi3d
07 Oct 2005, 12:34
Is it me or did the last two posts repeat themselves? lol

Andreas
07 Oct 2005, 12:47
No. I just posted the same answer twice, lol.

Allan
07 Oct 2005, 14:02
work with vB 3.5 Gold this ?

Andreas
07 Oct 2005, 17:24
Sure.

cinq
07 Oct 2005, 17:27
Hook mod_index_navigation

So I just place the code ( for e.g )

<navgroups product="vbulletin">
<navgroup phrase="demohack_settings" hr="true">
<navoption>
<phrase>demohack_foo</phrase>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<phrase>demohack_modcp</phrase>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
<navgroup text="Demohack Settings">
<navoption>
<text>Demohack Foo</text>
<link>demohack.php?do=foo</link>
</navoption>
<navoption>
<text>Demohack ModCP</text>
<link>../{$vbulletin->config[Misc][modcpdir]}/foobar.php</link>
</navoption>
</navgroup>
</navgroups>

as the hook code under plugins group ?

Andreas
07 Oct 2005, 17:27
No :)
Hooks are only for PHP Code, not for XMLs ...

WNxWakko
09 Oct 2005, 02:41
what about the modcp, what xml file is the master for that?

Nullifi3d
09 Oct 2005, 05:42
what about the modcp, what xml file is the master for that?There isn't one. As stated several time already in above posts:
Hook mod_index_navigation

Allan
12 Oct 2005, 00:42
Thanks Kirby for important informations :)

KW802
18 Oct 2005, 18:50
Kirby,

Thanks for the info, I was able to make use of it. :)

Kevin

Swindont
23 Oct 2005, 15:45
can u set permissions so only certain admins can see them?

Nullifi3d
26 Oct 2005, 16:23
can u set permissions so only certain admins can see them?

Yes, take a look at includes/xml/cpnav_vbulletin.xml for examples.
Take a look at the permissions parameter within the navgroup tags.

achtungbaby
07 Nov 2005, 05:33
Yes, take a look at includes/xml/cpnav_vbulletin.xml for examples.
Take a look at the permissions parameter within the navgroup tags.
Hello, thanks for the tip. Would "canrunqueries" be an acceptable permission?

HMBeaty
08 Nov 2005, 03:47
How can I make it so there are mutliple options in the menu? Like this.....

Links
-vBulletin
---vBulletin.org
---vBulletin.com
-Other
---Other.com

Any ideas? Or will that even work?

Andreas
08 Nov 2005, 04:34
You can't have sub-groups.

HMBeaty
08 Nov 2005, 04:36
You can't have sub-groups.
Well that...........bites. lol :(

Nullifi3d
08 Nov 2005, 22:40
Hello, thanks for the tip. Would "canrunqueries" be an acceptable permission?Yes that's a permission.

waza
03 Dec 2005, 15:52
Hey,
Why doesn't the code below work? I just get a blank tab.
I tried it with displayoptions but didn't work either.

<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="emotions">
<navgroup text="Moods" hr="true">
<navoption>
<text>Mood manager</text>
<link>image.php?do=modify&table=mood</link>
</navoption>
<navoption>
<text>Add new mood</text>
<link>image.php?do=add&table=mood</link>
</navoption>
<navoption>
<text>Upload mood</text>
<link>image.php?do=upload&table=mood</link>
</navoption>
</navgroup>
</navgroups>

Andreas
04 Dec 2005, 11:36
What do you mean with "blank tab"?
Also, do you have a product emotions?

waza
04 Dec 2005, 11:43
Hey,
yes I have a product emotions, I also tried it with: product="vbulletin" but it didn't work either I always get a blank entry, like in the attached screen.

If I look to the src code I see this for the blank entry:

<div style="margin-bottom:12px"></div>
<a name="grpemotions_0"></a>
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="navtitle" ondblclick="toggle_group('emotions_0'); return false;">
<tr>
<td><strong></strong></td>
<td align="right">
<a href="index.php?do=buildnavprefs&amp;nojs=0&amp;prefs=&amp;dowhat=expand&amp;id=emotions_0#grpemotions _0" target="_self"
onclick="toggle_group('emotions_0'); return false;"
oncontextmenu="toggle_group('emotions_0'); save_group_prefs('emotions_0'); return false"
><img src="../cpstyles/vBulletin_3_Silver/cp_expand.gif" title="Expand Group" id="button_emotions_0" alt="" border="0" /></a>
</td>

</tr>
</table>
<div id="group_emotions_0" class="navgroup" style="display:none">
<div class="navlink-normal" onclick="nav_goto('');" onmouseover="this.className='navlink-hover';" onmouseout="this.className='navlink-normal'"><a href=""></a></div>
</div>

Andreas
04 Dec 2005, 12:05
Your XML is invalid ;)


<?xml version="1.0" encoding="ISO-8859-1"?>
<navgroups product="emotions">
<navgroup text="Moods" hr="true">
<navoption>
<text>Mood manager</text>
<link>image.php?do=modify&amp;table=mood</link>
</navoption>
<navoption>
<text>Add new mood</text>
<link>image.php?do=add&amp;table=mood</link>
</navoption>
<navoption>
<text>Upload mood</text>
<link>image.php?do=upload&amp;table=mood</link>
</navoption>
</navgroup>
</navgroups>

waza
04 Dec 2005, 12:14
Oww I see & should be &amp;

Thx man, I tried like everything, was almost getting crazy :p.

Grz

zendiver
18 Dec 2005, 21:41
Yes, take a look at includes/xml/cpnav_vbulletin.xml for examples.
Take a look at the permissions parameter within the navgroup tags.
I can see where it you would put 'permissions="canadminsettings"' but that doesn't allow you to choose which Admins have the accessibility.

If you go to Admin Permissions, you are able to choose which Admin has what permissions to access. How would one go about adding this functionality?

Thanks

cclaerhout
23 Dec 2005, 22:02
I can see where it you would put 'permissions="canadminsettings"' but that doesn't allow you to choose which Admins have the accessibility.

If you go to Admin Permissions, you are able to choose which Admin has what permissions to access. How would one go about adding this functionality?

Thanks

I'm wondering the same thing...
Andreas ? ;)

Deviation
29 Dec 2005, 00:42
Just for reference, the vBulletin manual has a section on this.
http://www.vbulletin.com/docs/html/cpnav_xml

Very handy. :squareeyed:



<navgroups>
This indicates that this is a XML File containing navgroups.
It has one parameter product that should be set to vbulletin


Actually this should be set to the name of your product. ;)

Andreas
29 Dec 2005, 00:46
Before RC ... don't know which RC it was that introduced product management, this was correct.

Deviation
29 Dec 2005, 00:47
I can see where it you would put 'permissions="canadminsettings"' but that doesn't allow you to choose which Admins have the accessibility.

If you go to Admin Permissions, you are able to choose which Admin has what permissions to access. How would one go about adding this functionality?

Thanks
If you want to add your own permissions, you need to use bitfields.
See http://www.vbulletin.com/docs/html/bitfield_xml

^ Granted this is for 3.5.2..... Not sure about Beta.

Before RC ... don't know which RC it was that introduced product management, this was correct.
Have you done one for release? If not, you ought to. Your tutorials are very handy to have around. :glasses:

jim6763nva
27 Feb 2006, 12:35
Andreas,

Thank you very much for taking the time to put this tutorial together! Tutorials like this one are a huge help to new vBulletin Hack developers.
Kudos to you! Hopefully you will be adding more to this.

Best wishes,
Jim

Blackhat
30 Oct 2008, 13:04
so if I want to add entries to the user cp, is this something similar to that ?

Lynne
30 Oct 2008, 16:09
so if I want to add entries to the user cp, is this something similar to that ?
No, this is for adding stuff in the admin cp. You are probably thinking of profile fields which usually show up in the users cp.

Blackhat
30 Oct 2008, 16:31
Im thinking of attaching a file to a custom menu entry in the user cp where I can run my custom code inside

ptmuldoon
03 Nov 2008, 16:32
Thanks for the great How To and tip. I'm learning to create a new mod, and was wondering exactly how to add new items to the Admin Menu. Quick question....

When adding a new xml file to add to the menu, it shows the new menu item in vbulletin with a * and [] brackets. Is that normal? It is showing it as

*[My New Mod]*