Difference between revisions of "Custom Drop Down Menu"

From TNG_Wiki
Jump to navigation Jump to search
Line 65: Line 65:
  
 
= Upgrading to New Version =
 
= Upgrading to New Version =
Use the TNG Mod Manager to remove the previous version of custom_ddmenu before you install a new one. <span style="color:#990000;">There is no need to remove or replace any of the data you've defined in your customconfig.php file, or in your cust_text.php files.</span>  Having said that, please be aware that we are deprecating a few of the old-style link definitions and will at some point remove them altogether.  You should review your customconfig.php links and update any that are deprecated.
+
Use the TNG Mod Manager to remove the previous version of custom_ddmenu before you install a new one. <span style="color:#990000;">There is no need to remove or replace any of the data you've defined in your customconfig.php file, or in your cust_text.php files.</span>  Having said that, please be aware that we are deprecating a few of the old-style link definitions and will at some point remove them altogether.  You should review your customconfig.php links and update any that are deprecated.  We will point them out in the discussion of menu and link options below.
  
 
= Installation =
 
= Installation =

Revision as of 18:18, 10 March 2013

custom_ddmenu
Summary modifies the custom menu hook to allow users to create a drop down menu from data provided in the customconfig.php file.
Validation n/a
Mod Updated {{{mod_last_update}}}
Download link custom_ddmenu_v9.0.0.5.zip
TNG 9.0
Download stats Statistics
Author(s) Rick Bisbee
Homepage Bisbee Family Connection
Mod Support Support for Custom Drop Down Menu
Contact Developer Rick Bisbee
Latest Mod 9.0.0.5
Min TNG V 9.0.0
Max TNG V 9 (all)
Files modified
genlib.php
Related Mods
None
Notes
The customconfig.php menu and link definitions, as well as any language support, are not installed by this mod, but must be created manually using the examples in this article as a guide.


Introduction

TNG version 9 provides a rudimentary "hook" for administrators to create their own drop down menus in the TNG menu bar. To use it, administrators must write their own PHP code in the customconfig.php file -- a problem for administrators who are not programmers. Furthermore, configuration and language text files are intended for data, not code. Using them for code presents a unique set of challenges that the administrator must also deal with. This mod avoids those problems, inserting links into existing TNG menus and/or creating a custom menu with its own links.

The custom_ddmenu mod modifies the TNGv9 menu "hook' to process data, rather than code. The data provided by the administrator describes the menu and each of its links. Every website is unique -- custom_ddmenu is not able to anticipate and provide links that each administrator might want, but we do provide some sample data to use as a pattern. It can be copied and placed in the customconfig.php file and will produce a drop down menu with working links. From there it is a simple matter to modify and add additional links to create a completely personalized drop down menu. If administrators provide language support in their cust_text.php files, custom_ddmenu will use it.

Revision History

Version Date Description
v9.0.0.5 10 Mar 2013
  • adds option for tool tips on custom menu links
  • adds option to open custom menu link in new window
  • improves the code
v9.0.0.4 20 Apr 2012 Add external links to menus
v9.0.0.3 7 Apr 2012 Addresses syntax error if mod is removed, but data structures in customconfig.php remain.
v9.0.0.2 2 Mar 2012 Adds capability to insert links into standard TNG drop down menus
v9.0.0.1 13 Feb 2012 Adds admin-only links
v9.0.0.0 7 Feb 2012 Initial release

Vizualization

Dd001.jpg

Upgrading to New Version

Use the TNG Mod Manager to remove the previous version of custom_ddmenu before you install a new one. There is no need to remove or replace any of the data you've defined in your customconfig.php file, or in your cust_text.php files. Having said that, please be aware that we are deprecating a few of the old-style link definitions and will at some point remove them altogether. You should review your customconfig.php links and update any that are deprecated. We will point them out in the discussion of menu and link options below.

Installation

Custom_ddmenu is installed using TNG's Mod Manager. Download the installation package, unzip it and drop the configuration file into the mods folder. Then go to the Admin >> Mod Manager Panel and click on install.

After you've installed it, you can copy and paste the sample data provided in custom_ddmenu.txt and test it -- does the menu appear in the menu bar and do the two links provided work? If it is working, modify the data to suit your needs. TNG upgrades do not affect your custom configuration or the cust_text files. After a TNG upgrade, all you have to do is reinstall the custom_ddmenu mod. Your data will remain intact.

Note: custom_ddmenu only accommodates one extra menu to the right of the existing drop downs on the menu bar.

To completely uninstall custom_ddmenu, go to Admin >> Mod Manager, find the mod and click on Remove. Delete the Structured data from your customconfig.php and any supporting text you have added to cust_text.php.

Menu Structure

In computer science a data structure is a scheme for organizing and storing data for efficient processing. Technically, we are using arrays, or array of arrays (sometimes called a list of lists) as our data structures, but administrators don't need to fully understand them to use them by example.

How to Create a Custom Menu

Please Note: It is not necessary to add a custom menu if all you want to do is add a link to one of the existing TNG drop down menus.

To create a custom menu, just put a line in your customconfig.php file as follows to assign an appropriately short title for it.

Menu Title: Literal (As Given)

The following line placed in you customconfig.php file will create a custom menu on the TNG menu bar titled, "More".

$custmenu['title_text'] = "More";


The following will still work to do the same thing, but has been deprecated and should be replaced by the example above.

DEPRECATED
$custmenu['text'] = "More";
$custmenu['literal'] = true;

Menu Title: Use Text From Language Support File

The following line placed in your customconfig.php file will create a new menu on the TNG menu bar and title it with the contents of $text['more'] found in your cust_text.php file for the current language.

$custmmenu['title_index'] = "more";

Of course, the administrator must define $text['more'] or it won't work.


The following will still work, but has been deprecated and should be replaced by the example above.

DEPRECATED
$custmenu['text'] = "more";
$custmenu['literal'] = false;

Only applicable options need to be given in the customconfig file. If both title_text and title_index are defined, the index option will be ignored.

PLEASE NOTE: Prior to version 9.0.0.3, this array was named $custommenu. We changed it to preclude a syntax error caused by removing the custom_ddmenu mod, but failing to remove this data from the customconfig.php file. With version 9.0.0.3, either name will be accepted, but we recommend you change it in your customconfig.php file to $custmenu to avoid the issue.

Setting Link Options

Link data structures are placed in our customconfig.php file and the tell Custom Drop Down Menu how to construct and where to insert menu items. For illustration we will begin to build a link, starting with basic information (target and label) and adding some options.

Whether you assign links to a custom menu you've created, or to one of the standard TNG drop down menus, you will need to describe them for the system. The data structure for each link is a bit more complex than for the custom menu, but easily adaptable by example. Our example here is for illustration only. If you want a working example for testing your custom_ddmenu mod installation, please see Working Example.

A Basic Link

A basic menu link only requires two elements -- a target and a title or label. The target is the script file or external link you want to open, and the label is a word or two that describes what will happen when you click on it.

Here are two example of a basic link that we might insert into the TNG Info menu. The first uses text provided here for the label, the second gets its label text from the language support file.

$link_nr = 0; 
$infomenulinks[$link_nr]['target'] = "extensions/fgw/index.php";
$infomenulinks[$link_nr]['label_text'] = "Submit Family";  // literal text

or

$link_nr = 0; 
$infomenulinks[$link_nr]['target'] = "extensions/fgw/index.php";
$infomenulinks[$link_nr]['label_index'] = "subfam"; // text from $text['subfam'];

Note that in older versions of this mod, label text was defined differently, requiring two lines instead of one.

DEPRECATED
$infomenulinks[$link_nr]['text'] = "Submit Family"; 
$infomenulinks[$link_nr]['literal'] = true;  // literal text
DEPRECATED
$infomenulinks[$link_nr]['text'] = "subfam"; 
$infomenulinks[$link_nr]['literal'] = false;  // from language support files

While these will still work, please upgrade your link configurations to the new format. At some point we will remove the old ones from the mod and they will no longer work.

Whenever we insert a link into a TNG or custom menu, we must assign it an ID number ($link_nr). Within each menu the first link must be zero, and each succeeding link must each be incremented by one (you will see how later.)

  • $infomenulinks is an array that will contain all the configurations for links to be inserted into the TNG Info menu.
  • $findmenulinks is for adding items to the Find menu
  • $mediamenulinks is for adding menu items to the Media menu.
  • $custommenulinks is for adding menu items to your custom menu.

Adding Options

The order of the following options does not matter and they need only be added to your link definition if they apply.

* External Link

if your menu item will take you to another website, you will need to set an option as follows:

$infomenulinks[$link_nr]['external'] = true;

* Icon or Sprite

You will probably want an icon displayed with the menu item. There are two options, one using a traditional icon file, the other using a sprite. We can assign a traditional icon to the link by adding the following line to the link definition:

$infomenulinks[$link_nr]['icon'] = "img/families_icon.gif"; 

The assigned value is a path to a valid icon file and it is relative to (that is, starts in) the TNG root directory.

Another option is to use a sprite.

$infomenulinks[$link_nr]['sprite'] = "fsearch-icon"; 

TNG sprites are defined by id in genstyle.css. The id in the example above is 'fsearch-icon'. If you are an advanced user, you can provide your own sprites and CSS id's. If both an icon and sprite are given, the icon will take precedence.

* Restrict Access to Admins Only

This is an option we can add to the link to restrict it to site admins. Anyone else who is not logged in as an admin will be unable to see or access it.

$infomenulinks[$link_nr]['admin'] = true;

* Add Tool Tips

If you would like your menu items to display a tool tip, there are two options -- one where you can directly enter the text into your link definition, and another to use language support by adding it to the $text array in the cust_text.php files.

This option will use the text as given for the tool tip.

$infomenulinks[$link_nr]['tip_text'] = "Submit your family history for inclusion." 

This next option will look in your current language $text array for $text['subfam'].

$infomenulinks[$link_nr]['tip_index'] = "subfam";  // $text['subfam']

* Open Link in a New Window

Use this option if you want your link to open in a new browser window or tab (browser dependent).

$infomenulinks[$link_nr]['newwin'] = true;

A Complete Example

Here is an example of a link in a custom drop down menu you've already defined. Notice how the link number is incremented ($link_nr++;) showing that it is not the first link in our custom menu. By using this syntax, we do not have to renumber items when we want to insert a new link.

$link_nr++; // increment the number for each additional link
$custommenulinks[$link_nr]['target'] = "http://bisbeefamily.com";
$custommenulinks[$link_nr]['icon'] = "img/families_icon.gif";
$custommenulinks[$link_nr]['label_text'] = "Bisbee Family";
$custommenulinks[$link_nr]['tip_text'] = "Go to the Bisbee Family Website";
$custommenulinks[$link_nr]['admin'] = true;
$custommenulinks[$link_nr]['external'] = true;
$custommenulinks[$link_nr]['newwin'] = true;

More Examples

First link in the custom menu

$link_nr=0; // the first link in the menu is always number 0
$custommenulinks[$link_nr]['target'] = "military/cw52/index.php";
$custommenulinks[$link_nr]['icon'] = "img/civil_war.gif"";
$custommenulinks[$link_nr]['label_text'] = "Military Records";
$custommenulinks[$link_nr]['admin'] = true; //optional

Second link in the custom menu

$link_nr++; // increment the number for each additional link (1)
$custommenulinks[$link_nr]['target'] = "cemeteries.php";
$custommenulinks[$link_nr]['sprite'] = "cemeteries-icon";
$custommenulinks[$link_nr]['label_text'] = "cemeteries";
$custommenulinks[$link_nr]['admin'] = false;

Third link - external opens in new window for admin only

$link_nr++; // increment the number for each additional link (2)
$custommenulinks[$link_nr]['target'] = "http://tng.lythgoes.net/wiki";
$custommenulinks[$link_nr]['external'] = true;
$custommenulinks[$link_nr]['newwin'] = true;
$custommenulinks[$link_nr]['icon'] = "img/tng_doc.gif";
$custommenulinks[$link_nr]['label_text'] = "TNGWiki";
$custommenulinks[$link_nr]['admin'] = true;

Case is very important -- except for title_text or label_text, keep everything in lower case. These are only examples and may not work on your Website. You can use the links from the Working Example below for testing. Although you can type them directly into your customconfig.php file, it is recommended you just copy and paste them to avoid typing errors.

Creating an Auxiliary Mod

If you have a lot of menu links and language support, you might consider creating your own auxiliary mod to write your menu data to your customconfig.php and your supporting text to all the required language files.

Working Example

If you prefer, you can copy and paste the following data for a custom drop down menu into your customconfig file for testing instead of using the text file included in the download package.

$custmenu['title_text'] = "More";

$link_nr=0; // the first link in the menu is always number 0
$custommenulinks[$link_nr]['target'] = "surnames.php";
$custommenulinks[$link_nr]['sprite'] = "surnames-icon";
$custommenulinks[$link_nr]['label_text'] = "Surnames";

$link_nr++; // increment the number for each additional link
$custommenulinks[$link_nr]['target'] = "cemeteries.php";
$custommenulinks[$link_nr]['icon'] = "img/cemeteries_icon.gif";
$custommenulinks[$link_nr]['label_text'] = "Cemeteries";

$link_nr++; // increment the number for each additional link
$custommenulinks[$link_nr]['target'] = "http://tng.lythgoes.net/wiki";
$custommenulinks[$link_nr]['external'] = true;
$custommenulinks[$link_nr]['newwin'] = true;
$custommenulinks[$link_nr]['icon'] = "img/tng_doc.gif";
$custommenulinks[$link_nr]['label_text'] = "TNGWiki";
$custommenulinks[$link_nr]['admin'] = true;

Disclaimer

Custom_ddmenu modifies your TNG genlib.php. While we don't anticipate it causing any particular problems with your website, use it at your own risk. If you do experience difficulty please notify the mod's developer.

TNG User sites using this mod

If you download and install this mod, please add your TNG site to the table below

URL User Note Mod-Version/TNG-Version User-language
A Bisbee Family History] Rick Bisbee mod developer's site v9.0.0.5/9.2.0 EN
Chambers Family Ancestry] Tom Chambers Using this with no problem in conjunction with FGW Tabs + Genlib Tab + Submit Photo Tab v9.0.0.4/9.0.3 EN
Chamberlain and Eidenbenz Genealogy] Graham Chamberlain v9.0.0.5/9.1.2 EN,DE,ES,FR,NL