PDA

View Full Version : [How-To] Create Admin Help Topics For Your Product


Code Monkey
26 Nov 2005, 20:55
[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 (http://www.vbulletin.com/forum/showthread.php?t=149120).

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.


$db->query_write("DELETE FROM " . TABLE_PREFIX . "adminhelp
WHERE product = 'productname' AND volatile = 1");


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.

Marco van Herwaarden
26 Nov 2005, 23:06
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
26 Nov 2005, 23:08
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

Code Monkey
26 Nov 2005, 23:09
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.

Marco van Herwaarden
26 Nov 2005, 23:35
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/bugs35.php?do=view&bugid=928

Code Monkey
26 Nov 2005, 23:56
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.

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. :D

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

It's a one time effort.

Andreas
27 Nov 2005, 01:09
I would suggest a slightly different approach:

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

function adminhelp_xml_handler($xml)
{
global $product_details, $vbulletin;
if ($product_details)
{
// query topics
$helptopics = array();
$topics = $vbulletin->db->query_read("
SELECT * FROM " . TABLE_PREFIX . "adminhelp
WHERE volatile = 1
AND (product = '" . $vbulletin->db->escape_string($product_details['productid']) . "')
ORDER BY action, displayorder
");
while ($topic = $vbulletin->db->fetch_array($topics))
{
$helptopics["$topic[script]"][] = $topic;
}
unset($topic);
$vbulletin->db->free_result($topics);

require_once(DIR . '/includes/class_xml.php');
$adminhelp_xml = new XMLexporter();

$adminhelp_xml->add_group('helptopics', array('product' => $product_details['productid']));

ksort($helptopics);
foreach($helptopics AS $script => $scripttopics)
{
$adminhelp_xml->add_group('helpscript', array('name' => $script));
foreach($scripttopics AS $topic)
{
$attr = array('disp' => $topic['displayorder']);
if ($topic['action'])
{
$attr['act'] = $topic['action'];
}
if ($topic['optionname'])
{
$attr['opt'] = $topic['optionname'];
}
$adminhelp_xml->add_tag('helptopic', '', $attr);
}
$adminhelp_xml->close_group();
}
$adminhelp_xml->close_group();

$xmloutput = str_replace("\n</product>", "\n\t" . substr(str_replace("\n", "\n\t", $adminhelp_xml->output()), 0, -1) . "</product>", $xml);
header('Content-Length: ' . strlen($xmloutput));
return $xmloutput;
}
else
{
return $xml;
}
}


if ($_REQUEST['do'] == 'productexport')
{
ob_start('adminhelp_xml_handler');
}


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

preg_match('/(\t<helptopics.*<\/helptopics>)/s', $xml, $matches);
require_once(DIR . '/includes/adminfunctions_help.php');
$adminhelp = $matches[0];
xml_import_help_topics($adminhelp);


Done. No phpMyAdmin, manual importing or whatever :)

Code Monkey
27 Nov 2005, 01:56
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.

Andreas
27 Nov 2005, 02:18
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"?

Code Monkey
27 Nov 2005, 02:27
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.

Andreas
27 Nov 2005, 03:00
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 ;)

Code Monkey
27 Nov 2005, 03:24
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.

Andreas
27 Nov 2005, 03:50
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?

Code Monkey
27 Nov 2005, 04:14
How would I be sending that to you?

Andreas
27 Nov 2005, 04:16
andreas (at) vbulletin.com

akanevsky
27 Nov 2005, 13:45
Nice tutorial, added to the Tutorial List :)

Andreas
01 Aug 2007, 14:09
Important
vBulletin 3.6+ does not require any PHP code (see post #7): Admin help is automatically included in product XML and imported on the destination installation.