How to: Add a Button to the HTML Editor Field Control

Article
10/16/2013

The HTML Editor field control provides built-in buttons that enable users to insert HTML elements such as tables and lists and apply styling without typing HTML and CSS code. This topic explains how to add a custom button to this editor to provide a new piece of functionality.

Procedure

To add a custom button to the HTML editor field control

Open the RTE2ToolbarExtension.xml file in the Editing Menu folder in the Master Page gallery. All customizations to the HTML Editor field control must be referenced in this file.
Add a <RTE2ToolbarExtraButton> tag under <RTE2ToolbarExtensions>. For example, change the file as follows:
```
<?xml version="1.0" encoding="utf-8" ?>
<RTE2ToolbarExtensions>
     <RTE2ToolbarExtraButton id="extraButtonTestId" 
        src="RTE2ToolbarExtraButtonTest.js" />
```
This change adds a new button with ID extraButtonTestId. You must also specify a source file containing the JavaScript code that performs the desired actions when the button is clicked.
Create and upload the JavaScript file referred to in step 2. This file must contain the following:
- Implementation of an onClickCallback method for your button.
- Implementation of an onResetStateCallback method for your button. This code runs when the state of the editor toolbar is reset. For example: a call of the RTE2_RegisterToolbarButton(mnemonic, iconUrl, text, toolTip, onClickCallback, onResetStateCallback, arguments) function.
  
  Following are the seven parameters to this function:
  
  mnemonic   A mnemonic for the button.
  
  iconUrl   Path to the icon file to display for your button.
  
  Text   Text to display next to the button's icon.
  
  toolTip   Tooltip to display when pausing over the button.
  
  onClickCallback   Method called when button is clicked.
  
  onResetStateCallback   Method called when any state of the editor is changed. A common use of this method is to enable and disable a button based on the text the user has highlighted in the editor window.
  
  arguments   An object that is passed to the onClickCallback and onResetStateCallback methods when they are run.
Following is an example of what RTE2ToolbarExtraButtonTest.js could contain:
```
[js]
// The method that is called when the button is clicked.
function TestButtonOnClick(strBaseElementID, arguments) {
alert("TestButton: I was clicked in " + strBaseElementID + ": " + 
arguments[1]); 
}

// The method that is called when the button's state is reset.
function TestButtonOnResetState(strBaseElementID, arguments) {
var docEditor=RTE_GetEditorDocument(strBaseElementID);
if (docEditor==null) { return; }
RTE_RestoreSelection(strBaseElementID);
var selection=docEditor.selection;
var rngSelection=selection.createRange();
rngSelection=selection.createRange();
rngSelection.pasteHTML("Resetting TestButton state! ");
return true;
}

// Register the toolbar button, which isnecessary for the 
// button to be displayed
RTE2_RegisterToolbarButton(
"testButton", 
RTE_GetServerRelativeUnlocalizedImageUrl("rte2spchk.gif"), 
"<- Test button", 
"This is my test button for toolbar extensibility", 
TestButtonOnClick,
TestButtonOnResetState,
new Array("one", "two", "3"));
```
Upload this file to the path specified in step 2. Locations in the src parameter are relative to the \Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\1033\ directory. For this example, RTE2ToolbarExtraButtonTest.js should be uploaded directly to this directory.

Now, all HTML editor field controls you open have the extra button you created.

Note

You can view the JavaScript source for the built-in HTML Editor field control source in the file.

To get a deeper understanding of how to add powerful new editor functionality, browse to the HtmlEditor.js file in the path \Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\LAYOUTS\1033\HtmlEditor.js.

Example

The following sample adds a button to the HTML Editor field control. When clicked, the button changes the background color of a table cell.

To use the sample, save the XML code below as RTE2ToolbarExtension.xml to the /_catalogs/masterpage/Editing Menu/ folder, and save the .js file to \Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\1033.

[xml]

  <?xml version="1.0" encoding="utf-8" ?> 
- <RTE2ToolbarExtensions>
  <RTE2ToolbarExtraButton id="bgColorButton" src="CodeSample.js" /> 
  </RTE2ToolbarExtensions>

var bgColor_mnemonic = "CodeSampleButtonId";

// The button has been clicked.
function BgColor_OnClick(strBaseElementID, args)
{
var elemCell=RTE_GetNearestContainingElementOfTypes(strBaseElementID, g_aTableCellTagNames);
if (elemCell==null
|| RTE2_IsSourceView(strBaseElementID)
|| !RTE2_ElementInContentArea(strBaseElementID, elemCell) )
{
return;
}

var dialogHelper=RTE_GetDialogHelper();
if (dialogHelper !=null)
{
var initialBgColor = elemCell.bgColor;

var newBgColor=dialogHelper.ChooseColorDlg(initialBgColor);
newBgColor=newBgColor.toString(16);
if (newBgColor.length < 6)
{
var tempString="000000".substring(0,6-newBgColor.length);
newBgColor=tempString.concat(newBgColor);
}
if (newBgColor.toUpperCase() != args.transparentColor.toUpperCase())
{
                elemCell.bgColor = newBgColor;
}
else
{
elemCell.bgColor = "";
}
}
RTE_GiveEditorFocus(strBaseElementID);
}

// The current state of the editor has changed.
// Should the Cell background button remain clickable?
function BgColor_OnResetState(strBaseElementID, args)
{
var elemCell=RTE_GetNearestContainingElementOfTypes(strBaseElementID, g_aTableCellTagNames);
if (elemCell==null
|| RTE2_IsSourceView(strBaseElementID)
|| !RTE2_ElementInContentArea(strBaseElementID, elemCell) )
{
RTE_TB_SetEnabledFromCondition(strBaseElementID, false, bgColor_mnemonic);
}
else
{
RTE_TB_SetEnabledFromCondition(strBaseElementID, true, bgColor_mnemonic);
}
return true;
}

// Register the button.
{
var iconUrl = "/_layouts/" + L_Language_Text + "/images/rtebkclr.gif";
var text = "Edit Cell Background Color";
var toolTip = text;
var onClickCallback = BgColor_OnClick;
var onResetStateCallback = BgColor_OnResetState;
var args = new Object();
args.transparentColor = "FFFFFF";
RTE2_RegisterToolbarButton(bgColor_mnemonic, iconUrl, text, toolTip, onClickCallback, onResetStateCallback, args)
}

How to: Add a Button to the HTML Editor Field Control

Procedure

To add a custom button to the HTML editor field control

Example

See Also

Other Resources

Additional resources