Old Documentation, Currently Being Redone/Moved

Lineage

The original extension was authored by Yan as custombuttons. LouCypher and deepakjoshi04 contributed heavily by their work with userChrome.js and the userChrome.js button including further contributions from the late cblover and SCClockDr. These concepts and the code is now incorporated in the extension Custom Buttons².

SCClockDr is currently maintaining the code and authoring enhancements.

Context Menu

Standard Menuitems

Introduction

Every button created with Custom Buttons² has a context menu consisting of:

• Edit Button...
• Delete Button
• Disable/Enable this Button
• Clone Button
• Copy as HyperLink
• Copy as BBCodeLink
• Copy to Clipboard
• Copy Button Name
• Save this Button
• Update Button
• Bookmark Button
• Button's Attributes
• Button Help
• Button's HomePage
• Add New Button
• Customize...

Screenshot:

The Context Menu comes in two parts.

1. The primary Context menu whose Id is “custombuttons-contextpopup”

   • It is intended for this menu to be customizable yet in full control of the extension.

2. A Sub-Context menu whose Id is “custombuttons-contextpopup-sub”

   • This menu is NOT intended to be customizable and we ask you honor that intension.

Edit Button...

The Edit Button option opens the custombuttons edit dialog. Allowing the author to edit the code that controls the button's function.

The Code Field contains code that executes on a left click by default. Pressing F9 while in this field caused the code to execute and focus to return to the Edit dialog when the execution is complete.

The Initialization code field contains code that executes on button initialization and on mouse clicks when an on click handler is specified.

Delete Button

The Delete Button option Removes the button from localstore.rdf and buttonsoverlay.xul.

Disable/Enable this Button

The Disable/Enable this Button option toggles the active state of the button, sets the opacity to 0.3, prevents focus, and toggles context menu options.

Clone Button

The Clone Button option clones the target button and positions the clone to the right on the same toolbar. All attributes are duplicated with the exception of the button.id.

Copy as HyperLink

The Copy as HyperLink option creates a html custombutton URL and places it on the system clipboard. This is for easy pasting on sites which support html and your own html documents.

Copy as BBCodeLink

The Copy as BBCodeLink option creates a BBCode tagged custombutton URL and places it on the system clipboard. This is for easy pasting into bbcode enabled forums which support the [cb] tag.

Copy to Clipboard

The Copy to Clipboard option creates a custombutton URL and places it on the system clipboard.

Copy Button Name

The Copy Button Name option places the button label, version, and status on the system clipboard.

Save this Button

The Save this Button option creates an HTML page containing the button's HyperLink information and various Attributes.

Update Button

The Update Button option inserts new parameters into the target button which are in the clipboard. All 4 fields are replaced and the copied link need not be the same button as the target.

Bookmark Button

The Bookmark Button creates a bookmark of the target button

Button's Attributes

The Button's Attributes option displays a dialog containing the button's attributes information and, also, places the information on the system clipboard.

Screenshot:

Button Help

The Button Help option displays a dialog containing the Button's help information. This must be specified by the author.

Screenshot:

Button Homepage

The Button's HomePage option directs the browser to the button's homepage. This must be specified by the author.

Add New Button...

Opens the Edit Dialog to allow for creating a new button.

Customize...

This is the option to open the Toolbar pallet for moving and adding buttons to the browser's toolbars.

NOTE: When the editor window is opened, Custom Buttons² either hides or disables the Customize... menu item. This is done to prevent any attempt to move the button to the toolbox prior to its being saved.

Modifying the Context Menu

1. Retrieve the Menu controller object from the extension by calling custombuttons.getCbContextObj

   Example: this.mObj = custombuttons.getCbContextObj(this); where:

   • this.mObj is mandatory because the extension needs to access this object once it is established in your button.
   • custombuttons is the namespace the extension operates in.
   • getCbContextObj is the constructor function.

2. Properties:

   1. BtnIdNum:0, - Houses the Button ID number portion for easy access.
   2. ItemIdPre:'Cb2-', - MenuItem prefix.
   3. mCtxtSub:false, - true = Primary context menu is modified. false = Standard behavior.
   4. oMenu:null, - Holds the Primary Context menu object.
   5. nMenu:null, - Holds the Sub-Context menu object.
   6. Oid:'', - Primary Context menu id.
   7. nId:'', - SubMenu Context menu id.
   8. OurCount:{}, - Holds an instance of the counter object custombuttons.gCounter
   9. menuitems:0, - Holds the Primary menu child count.
   10. listener:function(){}, - Holds a listener function if you provide it. The context listener in the extension will call this property if this object is present in the button. note: This property must contain a function.
   11. This is the list of names used to access the menuitem properties:

aItemIdx:['id','label','image','oncommand','command','acceltext',
'accesskey','allowevents','autocheck','checked','crop',
'description','disabled','key', 'name','tabindex','type',
'validate','value'],

1. Methods

   1. init( oBtn ) - Sets the initial state and is called by the wrapper prior to presenting the object to the caller. oBtn is the parent button.
   2. setSub() - Sets the Sub menu on and reduces the primary menu to one Custom Buttons² item "Custom Button" which invokes the subMenu. If button specific Items are already in the primary menu they will be presented as well.
   3. setPri() - Resets the Primary menu and kills the SubMenu. It hides any button specific Items appended to the primary menu.

   4. getItem() - Retrieves an object with named properties, which the user populates with the item data specific to their application. Fields not populated will not alter the menuitem when populated. Argument 'Id' is REQUIRED and if omitted a default will be substituted.
      Example: Cb2-##-YourID++ where:

      • ## is the button's id number.
      • ++ is a 0 based sequential number.

      Menuseparators are invoked by omitting the label property

   5. insertBefore( oNew, oChildNode ) - Inserts a menuitem to the primary Context menu before the menuitem specified in arg2. Requires the populated getItem Object (oNew) as an arg and a reference menuitem as arg 2.
   6. insertAfter( oNew, oChildNode ) - Inserts a menuitem to the primary Context menu after the menuitem specified in arg2. Requires the populated getItem Object as an arg and a reference menuitem as arg 2.
   7. addItem( oNew ) - Prepends a menuitem to the primary Context menu. Requires the populated getItem Object as an arg.
   8. populate( oData, mItem ) - Populates the menuitem mItem with the data supplied oData.
   9. getItemsById( id ) - Returns the menu element specified by id.
   10. RemItem( id ) - Removes the specified item (by id) from the Primary Context Menu. If id is null or not passed, ALL items associated with the button will be removed.

Example: Modifying Context Menu

This sets up the menu object and initializes it.

this.mObj = custombuttons.getCbContextObj(this);

This establishes a listener function ( Optional ).

x.mObj.listener = function(x){x.getIndex();};

This tells custombuttons to implement the sub-menu.

x.mObj.setSub();

This will contain the item to be submitted to add/insert methods.

var nItem = {};

This will contain the item returned by the add/insert methods.

var mItem = {};

This stops event propagation to avoid unintended behavior.

document.getElementById(CB2const.sCBCtxtMenu).setAttribute("oncommand", "event.stopPropagation()");

note: These next statements can be placed in a loop for implementing several menuitems.

This sets up nItem to populate with the data we wish.

nItem = new x.mObj.getItem();

Here we set some attributes for the menuitem.

nItem.id = 'MyId';
nItem.label = My Label;
nItem.value = 'Some Data';
nItem.checked = false;

This will insert a new menuitem before the last child. mItem will be a different object than nItem.

mItem = x.mObj.insertBefore( nItem , x.mObj.oMenu.lastChild);

Due to scoping this must be setup here and not within the object. Arg2 is whatever you need to implement.

mItem.setAttribute( 'oncommand','document.popupNode.setIndex(this);' )

Here we set some attributes directly.

mItem.setAttribute( 'type','checkbox')
mItem.setAttribute( 'checked',false)
mItem.setAttribute( 'autocheck',false )

Now to create and insert a separator.

x.mObj.getItem();
nItem = x.mObj.getItem();
nItem.id = 'Note';
this.separator = x.mObj.insertBefore( nItem , x.mObj.oMenu.lastChild);

Note we did not set the label with anything.

That completes the setup. Now the extension will do the rest.

FAQ

Why go to all this trouble?

1. Custombuttons provides a means to disable a button via it's context menu. When the button is disabled the menu should not provide the normal options because the button is disabled.
2. When authors implemented their own context manipulation they usually modified the context menu's id. From that point on the extension looses control of it's menu and can no longer disable its menuitems when the button is disabled.
3. Also this implements more consistency in button behavior.

Global Objects, Handlers, and Functions

Global Clipboard Object

Property

sRead is an array container to house internal clipboard like data.

Methods

1. gClipboard.write(str) - stuffs the system clipboard with the argument str
2. gClipboard.read - returns the contents of the system clipboard
3. gClipboard.clear - stuffs the system clipboard with ""
4. gClipboard.Write(str) - stuffs the internal clipboard with the argument str
5. gClipboard.Read - returns the contents of the internal clipboard

This Object can be instanced but there remains one and only one system clipboard. var myClipBoard = new Object(gClipboard); is an example of this object being instanced.

Mouse Click Event Handler

gQuot = function(evt, cButton)

Args:

• evt - Mouse click event used to direct code execution based on the button clicked and any extra state keys held during the event.

• cButton - Object of the calling button used to appropriately locate the context menu.

Returns: Nothing.

How this works:

On a click the calling button is strobed via the this.setAttribute("onclick", "gQuot(event, this);"); statement in the button's Initialization Code section. This passes the event and button object (this) to the event handler.

Execution:

1. Execution proceeds to check for a click event function presence in the calling button.
   • Testing progresses down the tree till it arrives at a function with no extra key qualifier.
   • The first found function is called within the calling button. It passes the event object to the called function to provide the button author with the event object for further processing.
2. If no matches are found then gShowPopup(cButton) is called passing it the button object.

Calls:

Ctrl+LeftClick example:

1. cButton.cleftclick(evt) calls the button object function cleftclick. It passes the click event object to the button and expects nothing in return.
2. When control returns to gQuot function, program flow will encounter a break and the function exits to the button's calling attribute "onclick" statement.
3. Handling of the event is now complete.

Alerts, Messages, Prompts and Dialogs

Alert Box

Alerts the user to an event

Syntax:

var cbTitle = "My Title"; // Title of the alert box
var cbDesc = "My Description/Instructions"; // Instructions/Info just before the button
custombuttons.alertBox(cbTitle, cbDesc);

Which produces this:

The button returns nothing, so this is all that is needed.

Why use this instead of the standard javascript alert?
You can specify a title for the alert box using this method.

See Alert Box Demo for a working demo of this function.

Alert Slide

Alerts the user to an event with a non-invasive sliding popup that slides in from the side of the screen

Syntax:

var cbTitle = "My Title"; // Title of the sliding alert
var cbDesc = "My Description/Info"; // Instructions/Info to describe the event
custombuttons.alertSlide(cbTitle, cbDesc);

Which produces this:

The button returns nothing, so this is all that is needed. Why use this instead of the standard javascript alert or the above custom buttons alert? Less invasive, doesn't pause other scripts from completing their functions and prettier.

See Alert Slide Demo for a working demo of this function

Create Message Function

createMsg = function(title)

Args: title - Optional

Returns: New Message Object with title property initialized if provided.

How this works: createMsg uses the Object constructor method to create an object Msg

Properties:

1. prompts
2. check
3. sTitle

Methods:

Msg.aMsg(str,title)

1. str - is the passed message string
2. title - is the optional dialog title

Calls: this.prompts.confirmEx();

Setup: MyObj = createMsg(['title']);

Use: MyObj.aMsg('a message here'); // Display message

Example:

// Setup the object
MyObj = createMsg("My message");
 
// Display a message
MyObj.aMsg("Hello World!");

Produces this:

Prompt Box

Prompts user for input string

The syntax is:

var cbTitle = "My Title"; // Title of the prompt
var cbDesc = "My Description/Instructions"; // Instructions/Info just before the input box
var cbDefVal = "Default Value"; // Default value to place in the input box
var cbPrompt = custombuttons.promptBox(cbTitle, cbDesc, cbDefVal);

Which produces this:

The prompt will return an array where the first item in the array is either false or true depending on whether the user clicked ok or cancel. Then the second item in the array is the value from the input box.

Here is a simple way to parse the array returned from the prompt

if (cbPrompt[0] == false) alert('cancel'); // first item in array was false
else alert(cbPrompt[1]); // first item in array was NOT false

See Prompt Box Demo for a working demonstration.

Prompt Box (with checkbox)

Prompts user for input string, has a checkbox for setting a preference or perhaps obtaining additional information

The syntax is:

var cbTitle = "My Title"; // Title of the prompt
var cbDesc = "My Description/Instructions"; // Instructions/Info just before the input box
var cbDefVal = "Default Value"; // Default value to place in the input box
var cbCkTxt = "Remember this choice?"; // Text for placing with checkbox
var cbCheck = {value:true,prompt:cbCkTxt} // value can be changed to default the checkmark to checked/unchecked
var cbPrompt = custombuttons.promptBox(cbTitle, cbDesc, cbDefVal, cbCheck);

Which produces this:

The prompt will return three pieces of data, the first two are part of an array where the first item in the array is either false or true depending on whether the user clicked ok or cancel. Then the second item in the array is the value from the input box. The third is the value from the checkbox.

Here is a simple way to parse the data returned from the prompt

if (cbPrompt[0] == false) alert('cancel'); // first item in array was false
else { // was true
  // the check is done inside this statement to avoid running it when cancel is pressed
  if (cbCheck.value == true) alert("ok we'll remember"); // the check returns either true or false
  if (cbCheck.value == false) alert("ok we'll forget"); 
  alert(cbPrompt[1]); // first item in array was NOT false
}

See Prompt Box Demo (with checkbox) for a working demonstration.

Confirm Box

Prompt the user to confirm an action

Syntax:

var cbTitle = "My Title"; // Title of the confirmation box
var cbDesc = "My Description/Instructions"; // Instructions/Info just before the buttons
var cbBtn1 = "Yes";
var cbBtn2 = "No";
var cbPrompt = custombuttons.confirmBox(cbTitle, cbDesc, cbBtn1, cbBtn2);

Which produces this:

The value returned will either be true or false depending on the button clicked. Used the returned valued like so:

if (cbPrompt == false) alert('No Button was clicked'); // "No" button was clicked
if (cbPrompt == true) alert('Yes Button was clicked'); // "Yes" button was clicked

See the Confirm Box Demo for a working example of this function

Confirm Box (3 Buttons)

Prompt the user to confirm an action

Syntax:

var cbTitle = "My Title"; // Title of the confirmation box
var cbDesc = "My Description/Instructions"; // Instructions/Info just before the buttons
var cbBtn1 = "Yes";
var cbBtn2 = "No";
var cbBtn3 = "Maybe";
var cbPrompt = custombuttons.confirmBox3(cbTitle, cbDesc, cbBtn1, cbBtn2, cbBtn3);

Which produces this:

The value returned will be 0, 1, or 2 depending on the button clicked. Use the returned values like so:

if (cbPrompt == 0) alert('Yes was clicked'); // "Yes" button was clicked
else if (cbPrompt == 1) alert('No was clicked'); // "No" button was clicked
else if (cbPrompt == 2) alert('Maybe was clicked'); // "Maybe" button was clicked

See the Confirm Box Demo (3 buttons) for a working example of this function

Checkbox Dialog

This dialog gives the author the ability to create a customized dialog of checkboxes. The author sends an array to the dialog and is returned the values in the same array.

The syntax is as follows:

declare your array

var cbArr = new Array();
cbArr[0] = ["Apple", true];
cbArr[1] = ["Banana", true];
cbArr[2] = ["Carrot", true];

this next section is a number of variables, none of which are required, but they give more options for customization of the dialog:

var cbTtl = "My Title"; // Title of the dialog
var cbLbl = "My Label"; // Label for the checkboxes area (displays above checkboxes)
var cbHed = "My Header"; // A Header Box that displays near the top of the dialog
var cbDsc = "My Description"; // The description for the Header Box.
 
var cbAcc = "Accept"; // The text to show on your OK button (OK is used when not specified)
var cbCnl = "Don't Accept"; // The text to show on your cancel button (Cancel is used when not specified)
 
var cbHlp = "Help"; // The text to show on your Help button (This button does not show if no label is specified)
var hlpTp = "Check the food that you like,\\n uncheck the ones you don't."; // Needed when clicking on the Help button
 
var cbDis = "Disclosure"; // The text to show on your Disclosure button (This button does not show if no label is specified)
var disTp = "Only use this button if you agree not to be stupid"; // Needed when clicking on the Disclosure button

This is the part that calls the actual dialog, this particular example uses the variables assigned above:

var cbCheck = custombuttons.checkboxDialog(this,cbArr,cbTtl,cbLbl,cbHed,cbDsc,cbAcc,cbCnl,cbHlp,hlpTp,cbDis,disTp);

Which produces this:

This is a dialog with everything available, however the minimum necessary to use this dialog is simply:

custombuttons.checkboxDialog(this,cbArr);

The remaining options would simply get left out.

If you would like to declare one of the options from later in the string, then you may do something like:

custombuttons.checkboxDialog(this,cbArr,null,cbLbl);

the null will mean that the title is not declared, but the label that follows it is.

Please see Checkbox Dialog Demo Button for an example of this dialog's operation.

Radiobox Dialog

This dialog gives the author the ability to create a customized dialog of radio buttons. The author sends an array to the dialog and is returned the values in the same array.

The syntax is the same as the checkboxdialog above, with the exception of a few things:

The specified array may either be a single array or an array with multiple nested arrays (note that nesting is only supported 1 level deep).

Single array:

var cbArr = [
["Apple", true],
["Banana", true],
["Carrot", true]
];

Which, when used in calling a radio button dialogue, produces this:

Nested array:

var cbArr = [ [
  ["Apple", false],
  ["Banana", false],
  ["Carrot", false]
],[
  ["Coffee", false],
  ["Milk", false],
  ["Orange Juice", false]
] ];

Which, when used in calling a radio button dialogue, produces this:

The only other difference is the syntax for calling the dialog, custombuttons.radioboxDialog

See Radio Dialog Demo Button (Single and Multi) for working demonstrations of this function.

Preference Utilities

Check for Existence of Pref

Checks whether a preference exists or not, optionally allows setting it if not

custombuttons.isPref('preference'[, 'defaultValue']); // the section in brackets is optional

The word 'preference' would be replaced by the preference you would like to check, then the section in brackets could be removed completely if you don't need to set a default value. If you do want to set a default value the replace 'defaultValue' with your value and remove brackets.

The default branch after Version 2.0.9.6.5rc1 is "extensions.CustomButtons2@cbtnext.org." Installation of a equal or newer than the version above will copy your old preferences to the new branch. Any subsequent update will clear the old prefs as well.

This example checks for 'example.myPreference' if it doesn't exist then it sets it to 'poop' and returns a boolean value of true.

Use after Custom Buttons² Version after 2.0.9.6.5rc1

custombuttons.isPref('myPreference', 'poop');        // Uses the default branch
custombuttons.isPref('branch.myPreference', 'poop'); // Specifies branch

This example checks for 'myPreference' and returns a boolean value of either true or false.

custombuttons.isPref('myPreference');        // Uses the default branch
custombuttons.isPref('branch.myPreference'); // Specifies branch

Using returned value

if (custombuttons.isPref('myPreference')) alert('Preference Exists');
if (custombuttons.isPref('branch.myPreference')) alert('Preference Exists');

Deprecated:

custombuttons.isPref('example.myPreference', 'poop');

This example checks for 'example.myPreference' and returns a boolean value of either true or false.

custombuttons.isPref('example.myPreference');

Using returned value

if (custombuttons.isPref('example.myPreference')) alert('Preference Exists');

Get Value from Existing Pref

Get the value from a preference

Use after Custom Buttons² Version after 2.0.9.6.5rc1

custombuttons.getPref('myPreference', 'poop');        // Uses the default branch
custombuttons.getPref('branch.myPreference', 'poop'); // Specifies branch
alert(pref);

Deprecated:

custombuttons.getPrefs('example.myPreference', 'poop');
alert(pref);

If the preference does not exist the returned value will be null

Setting a Pref

Set a specified preference to a given value

This example sets the specified preference to 'poop'

Use after Custom Buttons² Version after 2.0.9.6.5rc1

custombuttons.setPref('myPreference', 'poop');        // Uses the default branch
custombuttons.setPref('branch.myPreference', 'poop'); // branch

Deprecated:

custombuttons.setPrefs('example.myPreference', 'poop');

Clear a Pref

Resets a preference to default status, clearing it's value and in turn removing the value on restart

Use after Custom Buttons² Version after 2.0.9.6.5rc1

custombuttons.clearPref('myPreference');        // Uses the default branch
custombuttons.clearPref('branch.myPreference'); // Specifies branch

Deprecated:

custombuttons.clearPrefs('example.myPreference');

Button Attributes

Toolbar Groups

There is a built in preference to make buttons work as a group (as of 2.0.7.9). This is meant for use with buttons that have menus. Basically, this means if you have a menu of a button open and you move your mouse over to another button within that group then the current menu will collapse and the next button's menu will expand. The same kind of operation one sees on firefox's default menus on the menubar.

Syntax:

custombuttons.setToolbarGroup(this, "unique-identifier");

Of course the author provides the identifier, careful it won't conflict with other grouped buttons. Please note that due to the operation of this attribute it must be declared AFTER any onmouseover declaration. If you don't do this then it will not operate correctly. If there is no onmouseover declared then anywhere will be fine, it is more than likely best to declare it at the end of the initialization tab with other attributes.

See the Menubar Buttons for an example of this function.

Translation

Please see the wiki entry on translation