How to: Add a Button to the HTML Ed...

Switch on low bandwidth view

Community Content

In this section

Statistics Annotations (0)

Click here to expand

Language Filter

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

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
```
<?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.

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>

JScript

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)
}

After much fighting with it, it does certainly work. I question the usefulness of the first example. There are a lot of extra things included in the code that I'm not sure what purpose they serve. For instance the "new Array("one", "two", "3"));" that gets passed to the function that always display "two"... maybe we could have simply sent "Hello World" as a string... that way I have less to confuse me.

Also, the first code block is not closed properly and will error, it requires an extra "</RTE2ToolbarExtensions>".

As well as, for me the button never actually resets after the first time you click it. I think that's a bug in the code.

Lastly, the location of the RTE2ToolbarExtension.xml file, saying "Open the RTE2ToolbarExtension.xml file in the Editing Menu folder in the Master Page gallery" was somewhat confusing for me (despite it being absolutely correct). As this file DOES NOT exist on the server filesystem (you can search c: if you don't believe me). You must access it from either Sharepoint designer or from the actual Sharepoint web ui.

I find it ironic that this page is pretty much the ONLY place on the internet (currently) that has any info on these RTE_ commands... not even in the SDK. So, for it being the ONLY example available, its a pretty poor one, and is causing new Sharepoint developers significant pain.

Procedure

To add a custom button to the HTML editor field control

Example

See Also

Other Resources