Register Members List Search Today's Posts Mark Forums Read

Reply
 
Article Options
[How-To] Create Admin Help Topics For Your Product
Code Monkey
Join Date: May 2004
Posts: 1,080

by Code Monkey Code Monkey is offline 26 Nov 2005

[How-To] Create Admin Help Topics For Your Product

Adding admin help topics to your products admin pages is easy and results in a cleaner and more professional interface. It takes a little work as there is no setup for this in product install/uninstall. If you would like to see this included in the default vbulletin then you can voice that in this thread.

The first thing you want to do is put your site (hopefully a dev site) in debug mode.

Once in debug mode, click on vBulletin Options in your ACP. There you will see a link to the "Admin Help Manager" or (AHM). This is not available unless debug mode is on. Clicking on that link will open the AHM of course.

Once in the AHM, click on the "add new topic" link at the top of the screen. This must be repeated for each help topic you wish to add.

Now, let's cover the input options.

Script: Here you will put the name of the script used for the admin page you want the help item to appear on. Script name minus the extension. So if your script is myproduct_admin.php, you will put myproduct_admin as the script.

Action: Here is where you need to make choices.

1. You can leave it blank and it will just be a general topic available when the help icon in the title bar is clicked. A general help will display on the overall page that lists all helps for that area of the admin page.

2. You can list one or more actions that will be associated with this help item. If you want it to appear on the section that loads when $_POST['do'] == 'insertsomething', then you would put insertsomething as the value here. If the same help item can be used in another section of the script such as "editsomething", and the verbiage of the help would be the same, then you can take care of both with the same item. To do this you would put insertsomething,editsomething as the value.

Product: Make sure you choose the name of the product you are working on and want this help topic to be included with.

Option: This refers to the individual element on the page. You can determine this by hovering over the input elements. The option name will appear in the tool tip that appears as name="XXXXXX". Where XXXXXX is the input item's name.

So, if you want the help item next to a text input for user id, you would hover over that input box and the option name will pop up (while in debug).
This is what you type in here, for the user id example it would most likely be userid.

Display Order: Choose what order you want it displayed when viewing the overall page with all help topics for that section.

Title:The title of the help item. I would recommend it being the same as the title of the input or section you are creating it for. To avoid confusion.

Text: The text of the help you wish to add. Html is allowed, phrases don't seem to work here.

vBulletin Default: Click yes.

Click save and then view the admin section you created it for. You should see a help icon in the header as well as next to the item you created it for.

Continue this for all items you wish to create a help topic for.


When you create a help topic, vBulletin does several things.

1. It creates a new phrase for that item title. The title of this phrase will be a merger of the script name, the actions chosen, the option, and the word title all separated by a _ .

So the example above would create myproduct_admin_insertsomething_editsomething_userid_title as the title phrase.

2. It also creates a new phrase for the text of the help item. Which for the above example would be myproduct_admin_insertsomething_editsomething_userid_text.

3. vBulletin also inserts a new row in the adminhelp table. This consists of columns for script name, action (comma delineated), option, display order, volatile (should = 1), and the product name.

Creating the install/uninstall for the product.

Once you have entered all the help items for your product the phrases will be available when you export your product xml. This is the easy part. Just add that phrase group to your product xml and the phrases will install/uninstall as all phrases do with a product.

In the install section of your product.

EDIT:The database entries in adminhelp can be done using Andreas' code below in post #7.

In the uninstall section you would put.


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

It would be nicer if the product import/export functions would take care of this, but until then, there is nothing stopping you from giving your product a useful new feature.

Last edited by Code Monkey; 27 Nov 2005 at 16:16..
Views: 4381
Reply With Quote
Comments
  #2  
Old 26 Nov 2005, 23:06
Marco van Herwaarden Marco van Herwaarden is offline
 
Join Date: Jul 2004
While in debug mode there is [Download / Upload Admin Help] link available to export your help. No need for manually doing this.

When someone want to install your helpfile, they will either have to be running debug mode to get to the same page, or just directly link to http://www.myboard.com/admincp/help.php?do=files
__________________
Marco van Herwaarden
Ex vBulletin.org Coordinator
Reply With Quote
  #3  
Old 26 Nov 2005, 23:08
Marco van Herwaarden Marco van Herwaarden is offline
 
Join Date: Jul 2004
Originally Posted by JumpD
1. You can leave it blank and it will just be a general topic available when the help icon in the title bar is clicked. A general help will display on the overall page that lists all helps for that area of the admin page.
This is not really true. It will just mean that it will be loaded regardless of the $_POST['do'] value.

Setting this is mostly usefull if your scrit have more then 1 'action' that display the same variable, and want to show a different help text depending on the action
__________________
Marco van Herwaarden
Ex vBulletin.org Coordinator
Reply With Quote
  #4  
Old 26 Nov 2005, 23:09
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
Originally Posted by MarcoH64
While in debug mode there is [Download / Upload Admin Help] link available to export your help. No need for manually doing this.

When someone want to install your helpfile, they will either have to be running debug mode to get to the same page, or just directly link to http://www.myboard.com/admincp/help.php?do=files
You're missing the whole point of having it install/uninstall automatically with the product. That is what this How-To is for.
Reply With Quote
  #5  
Old 26 Nov 2005, 23:35
Marco van Herwaarden Marco van Herwaarden is offline
 
Join Date: Jul 2004
Once you started about phpMyAdmin, i stopped reading, since exporting them and adding a second file is much less work for me then to even open phpMyAdmin.

PS I already filed a bugreport for the missing Admin Help in the product files months ago, and it is flagged for future version: http://www.vbulletin.com/forum/bugs3...view&bugid=928
__________________
Marco van Herwaarden
Ex vBulletin.org Coordinator
Reply With Quote
  #6  
Old 26 Nov 2005, 23:56
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
Thanks for the link.

However, in the meantime, if you want to add admin help to your product in a way that requires no effort on the part of the end user, this is how you can do it for now. Works real good and requires no effort on the part of the end user. And we know how much effort they are willing to give.

This is for product developers.

Originally Posted by MarcoH64
Once you started about phpMyAdmin, i stopped reading, since exporting them and adding a second file is much less work for me then to even open phpMyAdmin.
LOL, pull up a coach and take a break then.

Obviously, it's nowhere near as much work as creating the whole product.

It's a one time effort.

Last edited by Code Monkey; 26 Nov 2005 at 23:58. Reason: Automerged Doublepost
Reply With Quote
  #7  
Old 27 Nov 2005, 01:09
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
I would suggest a slightly different approach:

Create a Plugin for Hook admin_global (not attached to the product, only for the dev machine!)

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

When creating your product, include the following as part of your install code

Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Done. No phpMyAdmin, manual importing or whatever
Reply With Quote
  #8  
Old 27 Nov 2005, 01:56
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
Yep that works great. However, you can get the xml to add into your product xml by just exporting the product help files in the admin help manager. No need for the plugin. The less ugly code I can get from the screwed up plugin exporter with it's broken line endings the better.

The pregmatch code for the install is awsome though. Hopefully that's in the next vb update.

Thanks.
Reply With Quote
  #9  
Old 27 Nov 2005, 02:18
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
Sure, you can manually copy the adminhelp XML into the product XML, but I prefer it to be automatic - less work
What do you mean with "broken line endings"?
Reply With Quote
  #10  
Old 27 Nov 2005, 02:27
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
When I export a product (linux server) it has trailing spaces instead of line endings so it's all one line basically. I have to go through and fix it. It doesn't effect the parts with code. Just the areas where the tags are.

Someone who is wanting to add help to an existing product would only need to export it from the help manager, remove the bit about vbulletin version, and add it to the product xml.

Someone working on a new product, or while doing major updates would be better off using your plugin and exporting the whole thing.

EDIT: I should clarify. The data within tags has it's line endings and looks normal. It's after all the closing tags that there is a problem.

Last edited by Code Monkey; 27 Nov 2005 at 02:35. Reason: Automerged Doublepost
Reply With Quote
  #11  
Old 27 Nov 2005, 03:00
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
On UN*X-type systems, \n is used for newline, while windows uses \r\n for newline.
The XML exporter always uses \n for newline.

=> unix2dos "fixes" that, or use a decent editor
Reply With Quote
  #12  
Old 27 Nov 2005, 03:24
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
It's only the vb product exporter that does that. The help exporter is fine. It's a bug.

The editor has nothing to do with it.
Reply With Quote
  #13  
Old 27 Nov 2005, 03:50
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
It's always the same code that is being used when XMLs are exported.
Can you send me a copy of a "broken" product XML, and some instructions on how to reproduce the problem?
Reply With Quote
  #14  
Old 27 Nov 2005, 04:14
Code Monkey's Avatar
Code Monkey Code Monkey is offline
 
Join Date: May 2004
How would I be sending that to you?
Reply With Quote
  #15  
Old 27 Nov 2005, 04:16
Andreas's Avatar
Andreas Andreas is offline
 
Join Date: Jan 2004
Real name: Andreas
andreas (at) vbulletin.com
Reply With Quote
Reply



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Article Options

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off


New To Site? Need Help?

All times are GMT. The time now is 20:50.

Layout Options | Width: Wide Color: