Modify the toplinks menu

Draft form! Still needs testing!

This describes modifying the "Top Links" menu which spans the top of the screen directly below the header. PGV offers built-in features for two menu modifications: you can add a new menu item with optional submenu, or you can add a submenu to the Welcome menu item. Both modifications work the same way.

First let's get the nomenclature right:

Most of those menu items have subitems: for instance, the Lists menu has subitems for Family, Individual, Multimedia, etc. The illustration shows the submenu (with submenu items) for the Search menu. In this article, Menu item refers to a main heading like "Lists", and Submenu item refers to a link on the submenu such as "Individual".

The process goes like this:

• Decide what you want the new menu and submenu items to do (section 1)
• Optional: create language-specific labels for each item (section 2)
• Change the code in one or two special files to create the menu items (sections 3 and 4)
• Optional: create and link custom graphics for them (section 6)

This example adds two submenu links (for Sourceforge.net and PGVthemes.com) to the Welcome menu item and also creates a new menu item with a submenu containing links to different genealogy sites. This example will create language support for the first item only, to illustrate both methods.

Define the menu and submenu items

For each menu or submenu item, choose a name (if you want multi-language support), label and link for each.

• The name (like "link_sourceforge") will be used by PGV to link to your language text.
• The label ("Go to Sourceforge") will be displayed on the screen, either directly or with the langauge file
• The link (http://www.sourceforge.net) is the action that will be performed.

Here is what we will use in the example:

Item	Name	Label	Link
Welcome submenu item for Sourceforge	link_sf	"Sourceforge.net"	http://www.sourceforge.net
Welcome submenu item for PGVthemes	link_pgvt	"PGVThemes"	http://www.pgvthemes.com
New menu item	gen_sites	"Genealogy websites"	http://www.google.com/search?hl=en&q=genealogy
1st submenu	gen_sites_gdc	"Genealogy.com"	http://www.genealogy.com
2nd submenu	gen_sites_anc	"Ancestry.com"	http://www.ancestry.com

Language file

This is optional, since you can write your display text directly into the submenu. Edit or create languages/extra.XX.php (where XX is your desired language). If it doesn't exist, make a copy of languages/lang.XX.php, rename it extra.XX.php and remove nearly all of the existing definitions but leave the top and bottom. Edit the remaining definitions to match your new submenus, so your file looks like this:

<?php
/**
 * [leave the copyright information here]
 * [save this as languages/extra.XX.php]
 */

if (!defined('PGV_PHPGEDVIEW')) {
	header('HTTP/1.0 403 Forbidden');
	exit;
	}

$pgv_lang["link_sf"]		= "Sourceforge.net";
$pgv_lang["link_pgvt"]		= "PGVthemes.com";
$pgv_lang["gen_sites"]		= "Genealogy websites";
$pgv_lang["gen_sites_gdc"]	= "Genealogy.com";
$pgv_lang["gen_sites_anc"]	= "Ancestry.com";
?>

Save this as languages/extra.XX.php. Also save it as extra.en.php, even if you are not using English. This way if a user selects a language for which you have not created an extra.XX.php, the menu will still work because the English version is the backup for any missing language file.

Create submenu items on the Welcome menu

The basic code for a submenu item is

$submenu = new Menu("Display text", "link");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
$menu->addSubmenu($submenu);

PGV looks for the file /includes/extras/custom_welcome_menu.php and adds any submenu items it finds to the Welcome menu. There is a template in that directory with a sample submenu so start there. Open the file includes/extras/sample_custom_welcome_menu.php. In the body of the file you will see several examples of the code shown above, each with different conditions which control when the submenu will appear. These options are:

• show for everyone, every time
• show to everyone except search engines
• show only for site admins
• show only for GEDCOM admins
• show only if clippings cart is enabled

This is how we would make the two submenus appear for all users with a line separating them. The first item uses a language file and the second item has the display text directly in the code:

$submenu = new Menu($pgv_lang["link_sf"], "http://www.sourceforge.net");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
$menu->addSubmenu($submenu);

$menu->addSeperator();

$submenu = new Menu("Go to PGVthemes.com", "http://www.pgvthemes.com");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
$menu->addSubmenu($submenu);

If we want the links to appear only for certain users or under certain circumstances, we modify one of the if {} sections instead. Several different examples are provided, but you can also make your own. For instance, if we want the PGVthemes link to display only for users who are logged in, we would do this:

$username = PGV_USER_NAME;
if ($username) {
	$submenu = new Menu("Go to PGVthemes.com", "http://www.pgvthemes.com");
	$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
	$menu->addSubmenu($submenu);
	}

Once you have all of your submenu items configured, delete or comment out all of the unused if {} sections and save the file as custom_welcome_menu.php. Once this file is on the server, the new submenu should appear under the Welcome menu item.

Add a new menu with submenu items

This is similar to the submenu example above, except the code starts with the main menu item and we save it with a different name. Submenus are optional, and they are added to the menu item. In this example we will use our menu and submenu definitions from step 2 to create a menu for "Genealogy Links" and then create submenu items for Genealogy.com and Ancestry.com.

Edit /includes/extras/sample_custom_welcome_menu.php. The first block of code describes the main menu item, so edit that using the label and link that we decided on:

$menu = new Menu($pgv_lang["gen_sites"], "http://www.google.com/search?hl=en&q=genealogy", "down");
if (!empty($PGV_IMAGES["gedcom"]["large"])) $menu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["gedcom"]["large"]);
$menu->addClass("menuitem$ff", "menuitem_hover$ff", "submenu$ff");

All of the PGV menus have an action associated with the main menu item itself. In this case clicking on the menu item starts a Google search, but if you don't want that to behave like a link, use "#" as the link. If you don't have a link, the menu will not appear at all.

After the main menu item is configured, create the submenu items as in the previous example. The menu and submenu items can all be hidden to certain users with the IF {} statements. For instance, if we wanted the menu item to not have its own link and only appear for logged-in users, and the second submenu item to only appear for site admins, we could write it this way:

$username = PGV_USER_NAME;
if ($username) {
	$menu = new Menu($pgv_lang["gen_sites"], "#", "down");
	if (!empty($PGV_IMAGES["gedcom"]["large"])) $menu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["gedcom"]["large"]);
	$menu->addClass("menuitem$ff", "menuitem_hover$ff", "submenu$ff");
	}

$submenu = new Menu($pgv_lang["gen_sites_gdc"], "http://www.genealogy.com");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
$menu->addSubmenu($submenu);

if (PGV_USER_IS_ADMIN) {
	$submenu = new Menu($pgv_lang["gen_sites_anc]", "http://www.ancestry.com");
	$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
	$menu->addSubmenu($submenu);
	}

Save this as /includes/extras/optional_menu.php. Once this file is on the server, this menu will appear between the Search and Help menu items.

Changing the order of menu items

The menu is generated by themes/[theme]/topmenu.php. Edit this file and you will see the block of code for each menu item, including the optional menu. If you change the order of the blocks of code, you will change the order in which the menu items display.

Custom images for menu and submenu items.

Graphics for menu items are typically 50x50 pixels (large) or 25x25 pixels (small). They are stored either in the main images/ and images/small/ directories, or in similar directories within the theme folder. You should place your images wherever your theme looks for them. For our examples (using the standard theme, which uses the main image directories) we will place a 50x50 pixel image links.gif in the images/ directory for the "Genealogy Links" menu item, and four smaller images in the images/small/ directory for our links to Sourceforge, PGVThemes, Genealogy.com and Ancestry.com. Here are some that you can use:

Genealogy links menu item
Genealogy.com submenu item
Ancestry.com submenu item
PGVThemes submenu icon
Sourceforge submenu icon

These have to be saved in the image directories. You should use lower-case file names. Once you have done that, there are two ways to add them to your menu:

Write the filename directly into the menu code

This will make that image appear for every user, every theme, in every language.

The sample code for the menu item already has a line which adds the standard 'large gedcom' image, looking like this:

if (!empty($PGV_IMAGES["gedcom"]["large"])) $menu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["gedcom"]["large"]);

There is a line break in the sample code which we have removed here. You can add this same line to the code for the submenu, and you can make it refer to any image you want. To make this item refer to our custom image links.gif we would change it to:

if ( file_exists($PGV_IMAGE_DIR."/links.gif")) $menu->addIcon($PGV_IMAGE_DIR."/links.gif");

To add an image to the Genealogy.com submenu items, you use a similar line in its submenu code like this:

$submenu = new Menu($pgv_lang["gen_sites_gdc"], "http://www.genealogy.com");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
if (file_exists($PGV_IMAGE_DIR."/small/gdc.gif")) $submenu->addIcon($PGV_IMAGE_DIR."/small/gdc.gif");
$menu->addSubmenu($submenu);

Define the images in the theme

In PGV graphics are indexed to menu items by the $PVG_IMAGES[item][size] array, which is in themes/[theme]/theme.php. The standard PVG tree image, used on the Welcome menu, is used by default for custom menu and submenu items. You can see the code here for the Standard theme:

if (!empty($PGV_IMAGES["gedcom"]["large"])) $menu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["gedcom"]["large"]);

That tells PVG to use the large 'gedcom' image for the main menu item, if that image exists. That image is defined in themes/[theme]/theme.php as follows:

$PGV_IMAGES["gedcom"]["large"] = "gedcom.gif";

To use the custom images shown above in our custom menu and submenu items, we would add new image array elements to our theme.php as follows:

$PGV_IMAGES["gen_sites"]["large"] = "links.gif";
$PGV_IMAGES["gen_sites_anc"]["small"] = "small/anc.gif";
$PGV_IMAGES["gen_sites_gdc"]["small"] = "small/gdc.gif";
$PGV_IMAGES["link_pgvt"]["small"] = "small/ggvt.gif";
$PGV_IMAGES["link_sf"]["small"] = "small/sf25.gif";

To use the large links.gif image for the "Genealogy Websites" menu item, change the image definition line in includes/extras/optional_menu.php to read:

if (!empty($PGV_IMAGES["gen_sites"]["large"])) $menu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["gen_sites"]["large"]);

To use a small image for the Sourceforge.net link on the Welcome menu, add a similar line to its submenu definition in includes/extras/custom_welcome_menu.php as follows:

$submenu = new Menu($pgv_lang["link_sf"], "http://www.sourceforge.net");
$submenu->addClass("submenuitem$ff", "submenuitem_hover$ff");
if (!empty($PGV_IMAGES["link_sf"]["small"])) $submenu->addIcon($PGV_IMAGE_DIR."/".$PGV_IMAGES["link_sf"]["small"]);
$menu->addSubmenu($submenu);

Remember that since these are defined in the theme, you will need to define them in theme.php for every theme where you want them to appear. Your theme might require additional images, such as small images for the main menu item, and all of the images need to be stored where the theme expects to find them, either in the main image directories or in the theme image directories. Look at the theme.php file for

$PGV_IMAGE_DIR = $THEME_DIR."images";   uses theme image directories

or

$PGV_IMAGE_DIR = "images";   uses main image directories