<customToolbarButton> Configuration Element

<customToolbarButton> Configuration Element
Prev	Chapter 18. XML Configuration API	Next

This element will cause a particular button to be present on the toolbar within Ephox EditLive! for XML.

Configuration Element Tree Structure

<editLive>
- <toolbars>
  - <toolbar>
    <customToolbarButton>

<editLive>
     ...
     <toolbars>
          <toolbar>
               <customToolbarButton ... />
          </toolbar>
     </toolbars>
     ...
</editLive>

Required Attributes

name: The name which uniquely defines this custom toolbar button.

text: The tooltip text for this custom toolbar button.

action

The action which this toolbar button performs when clicked on.

Note

This attribute has the following possible values:

insertHTMLAtCursor - Insert the given HTML at the cursor
insertHyperlinkAtCursor - Insert the given hyperlink at the cursor
raiseEvent -Call a JavaScript function with the given name
customPropertiesDialog - Call a JavaScript function with the given name and pass it the current tag's properties
PostDocument - Post the content of the applet to a server side script

value: The value of the text or hyperlink to be inserted or the name of the JavaScript function to be called when this toolbar button is clicked.
Note
When using the insertHTMLAtCursor action the HTML to be inserted must be URL encoded in the XML file. For example, <p>HTML to insert<p> becomes %3Cp%3EHTML%20to%20insert%3C/p%3E.

imageURL

The URL of the image to be placed on the menu with the menu item text. The image should be of a .gif format and be a size of sixteen (16) pixels high and sixteen (16) pixels wide.

Note

This URL can be relative or absolute. If relative the URL is relative to the URL of the page in which EditLive! for XML is embedded.

xhtmlonly

This attribute defines whether the custom toolbar button should be active only when the cursor is placed within an XHTML section. Setting this attribute to true will ensure that the toolbar button is only active when the cursor is within an XHTML section.

Default: false

enableintag

This attribute defines in which tags the function should be enabled. For example, when set to td the function will be enabled when the cursor is within a <td> tag (i.e. a table cell).

Example

The following example demonstrates how to define a custom toolbar button for use within EditLive! for XML on the Command Toolbar. The button defined in this example will insert HTML to insert at the cursor, note that the value in the example below is URL encoded.

<editLive>
    ...
    <toolbars>
        <toolbar name="command">
            <customToolbarButton 
                name="customButton1" 
                text="Custom Button" 
                imageURL="http://www.someserver.com/image20x20.gif"
                action="insertHTMLAtCursor" 
                value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
        </toolbar>
    </toolbars>
    ...
</editLive>

The following example demonstrates how to define a custom toolbar button for use within EditLive! for XML on the Format Toolbar. The button defined in this example is used with a custom properties dialog. The custom properties dialog will be available for use when the cursor is inside any <td> tag.

<editLive>
  ...
  <toolbars>
    <toolbar name="format">
      <customToolbarButton 
        name="customPropButton1" 
        text="Custom td Properties" 
        imageURL="http://www.someserver.com/image20x20.gif"
        action="customPropertiesDialog" 
        value="customTDFunction"
        enableintag="td"
      />
    </toolbar>
  </toolbars>
  ...
</editLive>

Remarks

The <customToolbarButton> element can appear multiple times within the <toolbar>.

The <customToolbarButton> element must be a complete tag, it cannot contain a tag body. Therefore the tag must be closed in the same line. See the example below:

<customToolbarButton name=... />

Text assigned to the value attribute must be URL encoded as it is in the example above.

Prev	Up	Next
<comboBoxItem> Configuration Element	Home	<customToolbarComboBox> Configuration Element