Tiny EditLive! allows developers to create custom menu and toolbar items. Developers can specify the text, image, and functionality of these menu and toolbar items.
Custom Toolbar Items
There are two types of custom items that can be added to the EditLive! toolbar:
- Custom Toolbar Button Items
- Custom Toolbar Combo Items
Custom Toolbar Button Items
Custom toolbar buttons are specified using the <customToolbarButton> configuration file element. Through this configuration file element developers can specify the image, tooltop text, and operation associated with the custom toolbar button.
Example
The following configuration file example demonstrates how to define a custom toolbar button for use within EditLive! on the Command Toolbar. The button defined in this example will insert the HTML <p>HTML to insert</p> at the cursor.
HTML to be inserted at the cursor must be URL encoded. For this example the value to be inserted has already been URL encoded.
<editLive>
...
<toolbars>
<toolbar name="command">
<customToolbarButton
name="customButton1"
text="Custom Button"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHTMLAtCursor" value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
</toolbar>
</toolbars>
...
</editLive>
For additional information and examples of custom toolbar buttons, please see the <customToolbarButton> configuration file article.
Custom Toolbar Combobox Items
Custom toolbar combo boxes are specified using the <customToolbarComboBox> configuration file element. The custom toolbar combo box item itself can be configured to perform custom operations, and/or its nested combo box items can be configured to perform custom operations. Combo box items to be contained within a custom combo box are specified using the <customComboBoxItem> configuration file element.
Example
The following example specified a custom toolbar combo box item. This combo box itself doesn't perform a custom operation, but its child custom combo box item performs an insert HTML at cursor custom operation, <p>HTML to insert</p>.
HTML to be inserted at the cursor must be URL encoded. For this example the value to be inserted has already been URL encoded.
<editLive>
...
<toolbars>
<toolbar name="command">
<customToolbarComboBox name="customCombo">
<customComboBoxItem
name="customComboItem1"
text="Custom Combo Item"
action="insertHTMLAtCursor"
value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
</customToolbarComboBox>
</toolbar>
</toolbars>
...
</editLive>
For additional information and examples of custom toolbar buttons, please see the <customToolbarComboBox> and <customComboBoxItem> configuration file articles.
Custom Menu Items
Custom menu items in EditLive! can only be of one format and of a single layered depth (i.e. they cannot include submenus). Custom menu items can be added to any of the menus in EditLive! via the <customMenuItem> configuration file.
Example
The following configuration file example demonstrates how to define a custom menu item for use within EditLive!'s Insert menu. The button defined in this example will insert the HTML <p>HTML to insert</p> at the cursor.
HTML to be inserted at the cursor must be URL encoded. For this example the value to be inserted has already been URL encoded.
<editLive>
...
<menuBar>
...
<menu name="ephox_insertmenu">
<customMenuItem
name="customItem1"
text="Custom Item"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHTMLAtCursor" value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
</menu>
...
</menuBar>
...
</editLive>
Custom menu items can also be embedded into the shortcut menu. For example:
<editLive>
...
<shortcutMenu>
<shrtMenu>
...
<customMenuItem
name="customItem1"
text="Custom Item"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHTMLAtCursor" value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
...
</shrtMenu>
</shortcutMenu>
...
</editLive>
Custom Operations for Toolbar and Menu Items
Custom menu and toolbar items can be used to perform the following operations:
- Insert HTML at the cursor
- Insert a hyperlink at the cursor
- Raise a JavaScript event
- Calling a JavaScript function, passing the current tag's attributes
- Cause EditLive! to HTTP Post its content to a specific URL.
Inserting HTML and Hyperlinks at the Cursor
When configuring custom toolbar buttons, combo boxes, and menu items within EditLive! to insert HTML at the cursor, the HTML needs to be specified within the EditLive! configuration file. The HTML to insert in the XML configuration file the HTML also needs to be already URL encoded.
The insert hyperlink at cursor custom functionality in EditLive! requires that the user select text before using the relevant custom item. Upon using the relevant custom item, the selected text will become a hyperlink linking to the address specified in the custom item configuration.
The HTML or hyperlink to insert at the location of the cursor is specified via the value attribute of the related <customComboBoxItem>, <customToolbarButton> or <customMenuItem> element in the EditLive! configuration file.
Example
The following example demonstrates how to define a custom menu item which uses the value insertHTMLAtCursor for the action attribute to insert HTML into an instance of EditLive!. The HTML to insert is the string <p>HTML to insert</p>, which is already URL encoded and stored in the value attribute.
<editLive>
...
<menuBar>
...
<menu name="ephox_insertmenu">
<customMenuItem
name="customItem1"
text="Custom Item"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHTMLAtCursor"
value="%3Cp%3EHTML%20to%20insert%3C/p%3E" />
</menu>
...
</menuBar>
...
</editLive>
Example
The following example demonstrates how to define a custom menu item which uses the value insertHyperlinkAtCursor for the action attribute to insert a hyperlink into an instance of EditLive!. The hyperlink to insert is the URL http://www.ephox.com, which is stored in the value attribute.
<editLive>
...
<menuBar>
...
<menu name="ephox_insertmenu">
<customMenuItem
name="customItem2"
text="Ephox"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHyperlinkAtCursor"
value="http://www.ephox.com" />
</menu>
...
</menuBar>
...
</editLive>
Raising a JavaScript Event
Custom toolbar and menu items in EditLive! can be configured to raise JavaScript events. JavaScript events raised through EditLive! are required to be defined either in the page in which EditLive! is embedded or in a file which is included in the page EditLive! is embedded in.
To raise a JavaScript event through a <customComboBoxItem>, <customToolbarButton> or <customMenuItem> element, the value raiseEvent is used for the action attribute. The value attribute of the element should specify the name of the JavaScript function which is to be called.
Example
The following example demonstrates how to define a custom menu item which uses the raiseEvent action for use within EditLive!. The menu item defined in this example will call the JavaScript function called eventRaised.
<editLive>
...
<menuBar>
...
<menu name="ephox_insertmenu">
<customMenuItem
name="customItem1"
text="Raise Event"
imageURL="http://www.someserver.com/image16x16.gif"
action="raiseEvent"
value="eventRaised" />
</menu>
...
</menuBar>
...
</editLive>
Calling a JavaScript Function, Passing the Current Tag's Attributes
Custom toolbar and menu items in EditLive! can be configured to pass all the attributes of the current tag to a specified JavaScript function. Developers can use this functionality with their own JavaScript functions to manipulate the attributes of specific tags at runtime. This allows developers to create custom dialogs which pertain to specific tags. This is useful in several ways: providing new dialogs for HTML elements (e.g. <span>, which is not available for direct interaction within EditLive!); accessing the properties of custom or XML tags such as <custom>; or replacing/complementing an existing EditLive! dialog, such as the Image Properties dialog which corresponds with the <img> tag.
To pass the attributes of the current tag to a JavaScript function through a <customComboBoxItem>, <customToolbarButton> or <customMenuItem> element, the value customPropertiesDialog is used for the action attribute. The value attribute of the element should specify the name of the JavaScript function to be called.
The JavaScript function called will have a string parameter passed to it. This string will be a collection of name-value pairs for each attribute found in the tag. The string will also contain an ephoxID name-value pair. This ephoxID value is used by EditLive! to keep track of all tags currently stored in the editor.
Tiny strongly advises developers not to change the value of the ephoxID name-value pair.
Example
The following example demonstrates how to define a custom menu item which uses the customPropertiesDialog action for use within EditLive!. The menu item defined in this example will call the JavaScript function called DisplayAttributes. This menu item is only available when a <h1> tag is selected.
This operation will only work for one specified tag type. To specify which tag type the menu or toolbar item will appear for, use the enableintag attribute.
<editLive>
...
<menuBar>
...
<menu name="ephox_insertmenu">
<customMenuItem
name="showAttributes"
text="H1 Properties"
action="customPropertiesDialog"
value="customPropDemo"
enableintag="h1"
/>
</menu>
...
</menuBar>
...
</editLive>
For an instance of EditLive! using the <customMenuItem> created above, the following function would create a JavaScript dialog displaying each name-value pair of attributes for the <h1> tag.
function customPropDemo(properties)
{
alert("VALUE-NAME pairs: " + properties);
}
The setProperties Method of EditLive! is used to set new attribute values for a tag. This property takes a string containing all the new name-value pairs for the tag to be changed. Which tag to change is specified through the ephoxID name-value pair.
Generating a HTTP Post for EditLive!'s Content
Custom toolbar and menu items in EditLive! can be configured to cause EditLive! to POST its content to a specific URL.
To post the content of EditLive! to a server-side script event through a <customComboBoxItem>, <customToolbarButton> or <customMenuItem> element, the value PostDocument is used for the action attribute.
The value attribute of the element can be used to specify several different parameters. Each parameter is delimited with the string ##ephox##. The following are the different parameters that can be specified through the value attribute:
Post Field
The name of the field in the HTTP POST that EditLive! uses to POST its content.
This parameter is required.
Post Acceptor URL
The URL for the POST acceptor that EditLive! is to POST to.
The parameter is required.
Response Processing
The operation that EditLive! is to perform with the HTTP response from the POST acceptor script.
The parameter can have the following values:
- saveToDisk - Present the user with a save file dialog, with which they can save the response to the local machine.
- callback - Pass the entire content of the HTTP response to a specified JavaScript callback function for processing.
This parameter is required.
JavaScript Callback Function
The name of the JavaScript callback function to use for processing the response.
This parameter should only be used if the response processing is set to callback.
The parameters specified through the value attribute string must appear in the order Post Field, Post Acceptor URL, Response Processing and JavaScript Callback Function (if needed).
Example
The following parameters specified through the value attribute string would store the contents of EditLive! in a hidden HTML form field called POST_field, sending the contents via HTTP Post to http://someserver/postacceptor.jsp, then call back the JavaScript function called JSFunction.
value="POST_field##ephox##http://someserver/postacceptor.jsp##ephox## callback##ephox##JSFunction"
Example
The following example demonstrates how to define a custom menu item which uses the PostDocument action for use within EditLive!. The menu item defined in this example will POST the content in the field editlive_field to the script at http://someserver/post/POSTacceptor.aspx upon completion of the POST the content of the HTTP response will be passed to the JavaScript callback function JSFunction.
<editLive>
...
<menuBar>
...
<menu>
<customMenuItem
name="customItem1"
text="POST Content"
imageURL="http://www.someserver.com/image16x16.gif"
action="PostDocument" value="editlive_field##ephox##http://someserver/post/POSTacceptor.aspx ##ephox##callback##ephox##JSFunction" />
</menu>
...
</menuBar>
...
</editLive>