Custom Menu Hook

From TNG_Wiki
Revision as of 05:58, 16 December 2018 by KenRoy (talk | contribs) (→‎Logged in users: marked mod as required prior to TNG 12.0.3)
Jump to navigation Jump to search


Ambox notice.png The information provided here is for constructing your Custom Menu in TNG V10 and above or for adding an entry to one of the TNG existing pull down menu.

Custom Menu Hook Mod provides a sample mod that uses the Custom Drop Down Menu mod syntax from TNG V9.
Converting Custom Menu Hook provides instructions for converting your Site Menu Mod to the new Custom Menu Hook syntax.

TNG 10.0



Purpose

The purpose of the Custom Menu Hook in TNG V10 is to make it easier to add a Site or 4th pull down menu without having to modify the TNG code.

It also makes it easier to add new entries to an existing TNG pull down menu, such as the Find, Media, or Info menus.

Its purpose is not to provide information on how to modify existing TNG pull down menu entries nor the language pull down menu.

For information on the previous hook see Custom Menu Hook V9

Parameters

Menu Title

The first line for your custom menu in your customconfig.php file defines your menu title.

Literal

The following line shows the use of a Literal for your custom title.

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

Variable

If you use multiple languages on your site, then you should use the title_index option for your title where the value specified is the $text['more'] found in your cust_text.php file for the current language.

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

Of course, the administrator must define $text['more'] = "More"; in the cust_text.php file or it won't work.

Menu Entries

Each menu entry line of the custom menu is generated by specifying a

  • link number
  • target
  • icon
  • label

and optionally specifying whether the link is

  • restricted to admin only
  • restricted to logged-in users only
  • opens in new window

Menu entries are created based on the beginning of the variable name as follows:

  • $custom... in the 4th custom pull down menu
  • $find... as an addition in the Find pull down menu
  • $media... as an addition in the Media pull down menu
  • $info... as an addition in the Info pull down menu

Link Number

The first link in the menu is always number 0. In order to support multiple mods adding entries to the TNG pull down menu, you should add the while() line to existing mods to make sure that $link_nr is set to the correct value, regardless of number of mods and order of installation. The while line doesn't affect anything until it's needed. The $link_nr should now be specified as

$link_nr=0; // the first link in the menu is always number 0
while ( isset($XXXXmenulinks[$link_nr]) ) $link_nr++; // Check that no other mod has added a link already

Additional links in the menu are specified by incrementing the link_nr, specified as

$link_nr++; // increment the number for each additional link

or using $link_nr=n; where n is a number

Target

The target parameter specifies where the link will point relative to your genealogy URL

$custommenulinks[$link_nr]['target'] = "extensions/fgw/index.php";

Icon

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:

$custommenulinks[$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 or your Genealogy URL.

Another option is to use a sprite.

$custommenulinks[$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.

Label

The label parameter can either be a literal

$custommenulinks[$link_nr]['label_text'] = "Submit Family";  // literal text

or a pointer to the text in your cust_text.php file

$custommenulinks[$link_nr]['label_index'] = "subfam"; // text from $text['subfam'];

Admin

Admin is an optional parameter than can be used to restrict a link to site admins. Anyone else who is not logged in with admin privileges will be unable to see or access it.

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

Logged in users

TNG version: 12.0.3

User is an optional parameter than can be used to restrict a link to logged in users. Anyone else who is not logged in will be unable to see or access it.
Included in TNG from v12.0.3.

TNG version: 12.0.2

NOTE! Before and including TNG v12.0.2 you have to use a very small mod (see below) for this to work.

$custommenulinks[$link_nr]['user'] = true;


This is the mod you have to use before and including TNG v12.0.2 (mod-version 12; edit to make it work in 10 or 11):

%name:User Menulink%
%version:v12.0.1.0%
%description:
<p>
This mod makes it possible to add a custom menu link that is only visible for loggedin users.<br />
<b>Read the Wiki page on how to use it.</b>
</p>
%author:Erik Hoppe:https://tng.lythgoes.net/wiki/index.php?title=User:XerxX%
%wikipage:Custom Menu Hook%

%target:genlib.php%
%location:%
		if( !isset( $linkdefs[$i]['target'] ) ) continue;
%end:%
%insert:before%

// Added by User Menulink mod

		if( isset($linkdefs[$i]['user']) && $linkdefs[$i]['user'] === true && !$currentuser) continue;

// End add

%end:%

New Window

The newwin is an optional parameter that indicates that you want this link to open in a new browser window or tab (browser dependent).

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

External Link

The external is an optional parameter that indicates that your menu item will take you to another website, where you will need to set an option as follows:

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

Add Tool Tips

Optionally, 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.

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

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

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

Menu Option

The TNG V10 Custom Menu Hook allows you to add to the existing TNG pull down menus or to create a custom menu. Each menu is associated with its own array:

  • $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, although normally additions here would be using user Media Collections.
  • $custommenulinks is for adding menu items to your custom menu.

Sprite

Darrin has provided two different sprite icons for the Mobile Mode Display

  • tng_mobile_sprite.png which includes a blank button for the custom menu that you can edit an add your own icon for your custom menu
  • tng_mobile_sprite2.png which provides a plus sign for the custom menu, if you are not comfortable with image editing tools. The plus sign signifying More.

If you want to use the plus sign icon, then rename

  • tng_mobile_sprite.png to tng_mobile_sprite1.png
  • tng_mobile_sprite2.png to tng_mobile_sprite.png

Custom Menu Construction

Menu Title

The title line of the custom menu if you are a multi-language site should use the title_index option

$custmenu['title_index'] = "mysite";

The title line of the custom menu if you are a single language site can use the title_text opion

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


Menu Entries

Each menu entry line of the custom menu is generated by specifying a

  • target
  • icon
  • label
$link_nr=0; // the first link in the menu is always number 0
while ( isset($custommenulinks[$link_nr]) ) $link_nr++; // Check that no other mod has added a link already
$custommenulinks[$link_nr]['target'] = "user/research_resources.php";
$custommenulinks[$link_nr]['icon'] = "user/images/my_resources.gif";
$custommenulinks[$link_nr]['label_index'] = "myresearch";
$custommenulinks[$link_nr]['user'] = true; // Only logged-in users


for each entry being generated. The $link_nr should be incremented using $link_nr++;

$link_nr++; // increment the number for each additional link (1)
$custommenulinks[$link_nr]['target'] = "guestbook.php";
$custommenulinks[$link_nr]['icon'] = "user/images/my_guestbook.gif";
$custommenulinks[$link_nr]['label_index'] = "myguestbook";

Custom Menu Example

Using TNG Mod

The Custom Menu Hook Mod can be used to installed your site custom menu in the customconfig.php file. If you don't want to use the Mod Manager to install your TNG customization, see the Manual update of customconfig.php file below.

TNG V10 zip file for the Custom Hook Menu Mod is included here for convenience [ custom_hook_menu_example_v10.0.0.0.zip]]

Note that no attempt was made to incorporate the Tray of Sprites capability in the sample menu.

Manual update

The following is an example of how you would code your custom site menu in customconfig.php. If you prefer to use the Mod Manager to install all your changes to TNG, then you should use the Custom Hook Menu Mod

Note that the code shown below is identical to what is added to the customconfig.php file if you install the Site Menu Mod

//    Custom HooK Menu added to customconfig.php in TNG V10
//     For additional details see the TNG Wiki <a  href="http://tng.lythgoes.net/wiki/index.php?title=Custom_Menu_Hook"  target="_blank">Custom Menu Hook</a>.

$custmenu['title_index'] = "mysite"; 
$link_nr=0; // the first link in the menu is always number 0
while ( isset($custommenulinks[$link_nr]) ) $link_nr++; // Check that no other mod has added a link already
$custommenulinks[$link_nr]['target'] = "user/research_resources.php";
$custommenulinks[$link_nr]['icon'] = "user/images/my_resources.gif";
$custommenulinks[$link_nr]['label_index'] = "myresearch";

$link_nr++; // increment the number for each additional link (1)
$custommenulinks[$link_nr]['target'] = "guestbook.ph";
$custommenulinks[$link_nr]['icon'] = "user/images/my_guestbook.gif";
$custommenulinks[$link_nr]['label_index'] = "myguestbook";


Adding to Find

The following is an example of how you would add the Census Plus International mod Find to the TNG Find pull down menu and restrict its access to those with TNG Admin privileges.

$link_nr = 0; 
while ( isset($findmenulinks[$link_nr]) ) $link_nr++; // Check that no other mod has added a link already
$findmenulinks[$link_nr]['target'] = "admin_censusplus.php";
$findmenulinks[$link_nr]['icon'] = "img/cpsprite.jpg";
$findmenulinks[$link_nr]['label_index'] = "mycensus"; // text from $text['mycensus'];
$findmenulinks[$link_nr]['newwin'] = true;
$findmenulinks[$link_nr]['admin'] = true;

Adding to Info

The following is an example of how you would add a Site How To link to the TNG Info pull down menu and open it in a new window and restrict it to logged-in users.

$link_nr = 0; 
while ( isset($infomenulinks[$link_nr]) ) $link_nr++; // Check that no other mod has added a link already
$infomenulinks[$link_nr]['target'] = "user/how_to.php";
$infomenulinks[$link_nr]['icon'] = "user/images/question.jpg";
$infomenulinks[$link_nr]['label_index'] = "myhowto"; // text from $text['myhowto'];
$infomenulinks[$link_nr]['newwin'] = true;
$infomenulinks[$link_nr]['user'] = true; // Only logged-in users