<customToolbarButton> Element

This element specifies the properties for a developer defined custom toolbar button for use within Ephox EditLive! for Java.

Element Tree Structure

<editLiveForJava>
    <toolbars>
        <commandToolbar> OR <formatToolbar>
            <customToolbarButton>

<editLiveForJava>
     ...
     <toolbars>
          <formatToolbar> OR <commandToolbar>*
               <customToolbarButton ... />
          </formatToolbar> OR </commandToolbar>*
     </toolbars>
     ...
</editLiveForJava>

*Note:  The <customToolbarButton> element can exist within either the <formatToolbar> element or the <commandToolbar> element.  Closing tags should be matched to opening tags (ie. <formatToolbar> ... </formatToolbar>).

Required Attributes

Attribute Description
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 four possible values; insertHTMLAtCursor, insertHyperlinkAtCursor, raiseEvent or customPropertiesDialog.  The raiseEvent functionality should not be used with the EditLive! for Java JavaBean.
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 twenty (20) pixels high and twenty (20) pixels wide.
Note:  This URL can be relative or absolute.

Optional Attributes

Attribute Description
enableintag The name of the tag in which a customPropertiesDialog menu item is to be available.

Note: To enable a custom properties dialog within a custom tag this property must be set to custom regardless of the name of the tag in which the functionality it to be enabled.  Enabling this functionality for custom tags via the custom value will enable it in all custom tags.

Examples

The following example demonstrates how to define a custom toolbar button for use within EditLive! for Java 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.

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

The following example demonstrates how to define a custom toolbar button for use within EditLive! for Java 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.

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

Remarks

The <customToolbarButton> element can appear multiple times within the <commandToolbar> or <formatToolbar> elements.

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. 

See Also