Ephox EditLive! for XML allows for the developer to specify custom items on the toolbars and menus. These custom items can be used to insert specific HTML source or a hyperlink at the cursor location, it can also be used to raise a JavaScript event or cause EditLive! for XML to POST its content to a specific URL. For information on how to configure EditLive! for XML to include custom menu and toolbar items see the <customToolbarButton>, <customToolbarComboBox> and <customMenuItem> elements in the EditLive! for XML Configuration Reference.
Within EditLive! for XML custom menu items and toolbar buttons which insert hyperlinks or HTML at the cursor will function only within XHTML sections. Those custom functions which use the raise event functionality will function throughout the editor.
There are two types of custom items which can be added to the EditLive! for XML toolbar, these are custom toolbar buttons and custom toolbar combo items. Custom toolbar buttons appear as buttons within the toolbar and when configuring these within the EditLive! for XML configuration file a URL which corresponds to an image for the button must be included. This image is used on the button when it is placed in the toolbar. Custom combo boxes appear in the same format as the typeface, style and font size toolbar items. When configuring custom combo boxes for use within EditLive! for XML each individual item within the combo box must be configured via the <customComboBoxItem>element in the EditLive! for XML configuration file.
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.
Example 8.3. Configuring a Custom Toolbar Button
<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>The following example demonstrates how to define a custom combo box item for use within a custom toolbar combo box which exists on the EditLive! for XML Command Toolbar. The combo box item defined in this example will insert HTML to insert at the cursor, note that the value in the example below is URL encoded.
Example 8.4. Configuring a Custom Toolbar Combo Box
<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> Custom menu items in EditLive! for XML can only be of one format. Custom menu items can only be of a single layered depth (i.e. they cannot include submenus). Custom menu items can be added to any of the menus in EditLive! for XML via the <customMenuItem>in the EditLive! for XML configuration file.
The following example demonstrates how to define a custom menu item for use within EditLive! for XML. The menu item defined in this example will insert HTML to insert at the cursor, note that the value in the example below is URL encoded.
Custom toolbar buttons and combo boxes, and custom menu items can be configured within EditLive! for XML to insert specific HTML source or hyperlinks at the location of the cursor. When configuring custom toolbar buttons, combo boxes and menu items within EditLive! for XML to insert HTML at the cursor the HTML source to be inserted at the cursor needs to be specified within the EditLive! for XML configuration file. When declaring the HTML to insert in the XML configuration file the HTML needs to be URL encoded.
The insert hyperlink at cursor custom functionality in EditLive! for XML 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 configuration of the custom item.
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 XML configuration file.
The following example demonstrates how to define a custom menu item which uses the insertHTMLAtCursor action for use within EditLive! for XML. The menu item defined in this example will insert HTML to insert at the cursor, note that the value in the example below is URL encoded.
Example 8.6. Configuring a Custom Item to Insert HTML at the Cursor
<editLive>
...
<menuBar>
...
<menu>
<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> <editLive>
...
<menuBar>
...
<menu>
<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> The following example demonstrates how to define a custom menu item which uses the insertHyperlinkAtCursor action for use within EditLive! for XML. The menu item defined in this example will insert the URL http://www.ephox.com at the cursor.
Example 8.7. Configuring a Custom Item to Insert a Hyperlink at the Cursor
<editLive>
...
<menuBar>
...
<menu>
<customMenuItem
name="customItem2"
text="Ephox"
imageURL="http://www.someserver.com/image16x16.gif"
action="insertHyperlinkAtCursor"
value="http://www.ephox.com"
/>
</menu>
...
</menuBar>
...
</editLive>To ensure a custom interface item is only available whilst the cursor is placed within an XHTML section the xhtmlonly attribute of the relevant <customToolbarButton>, <customToolbarComboBox> or <customMenuItem> element must be set to true.
Custom toolbar and menu items in EditLive! for XML can be configured to raise JavaScript events. JavaScript events raised through EditLive! for XML are required to be defined either in the page in which EditLive! for XML is embedded or must be defined in a file which is included in the page in which EditLive! for XML is embedded.
When raising a JavaScript event from EditLive! for XML the value attribute of the related <customComboBoxItem>, <customToolbarButton> or <customMenuItem> element in the XML configuration file should specify the JavaScript function which is to be called.
The following example demonstrates how to define a custom menu item which uses the raiseEvent action for use within EditLive! for XML. The menu item defined in this example will call the JavaScript function called eventRaised.
The custom properties dialog functionality of EditLive! for XML allows developers to retrieve and set the attributes for a particular element within EditLive! for XML. Developers can use this functionality with their own JavaScript functions to manipulate the attributes of specific tags.
The custom properties dialogs should be linked to from a custom toolbar button or custom menu item. For more information on how to configure EditLive! for XML to include custom menu and toolbar items see the <customToolbarButton> and <customMenuItem> elements in the EditLive! for XML Configuration Reference.
Example 8.9. Configuring a Custom Item to Retrieve the Properties of a Tag
<editLive>
...
<menuBar>
...
<menu>
<customMenuItem
name="customProperties1"
text="Custom td Properties"
action="customPropertiesDialog"
value="customTDFunction" enableintag="td"
/>
</menu>
...
</menuBar>
...
</editLive>The JavaScript function corresponding to this custom menu item should be of the following form:
function customTDFunction(properties){
...
//Content of function goes here
...
} Where the parameter properties is a string.
Custom toolbar and menu items in EditLive! for XML can be configured to cause EditLive! for XML to POST its content to a specific URL. When using the PostDocument function the value attribute of the custom item is used to pass several parameters to EditLive! for XML. These parameters are delimited by the string ##ephox##. Thus, the string editlive_field##ephox##http://someserver/post/POSTacceptor.aspx contains two parameters editlive_field and http://someserver/post/POSTacceptor.aspx.
The value attribute for the PostDocument function may contain the following parameters.
The name of the field in the HTTP POST that EditLive! for XML uses to POST its content.
This parameter is required.
The URL for the POST acceptor that EditLive! for XML is to POST to.
The parameter is required.
The operation that EditLive! for XML 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.
The name of the JavaScript callback function to use for processing the response. This parameter should only be used if the repsonse processing is set to callback.
The parameters must appear in the value attribute in the the order POST field, POST Acceptor URL, Response Processing, JavaScript Callback Function. Thus, the content of the value attribute may appear as follows:
For saving to disk:
POST_field##ephox##http://someserver/postacceptor.jsp##ephox## saveToDisk
POST_field##ephox##http://someserver/postacceptor.jsp##ephox## callback##ephox##JSFunctionName
Where POST_field is the name of the field the content is to be POSTed to, http://someserver/postacceptor.jsp is the URL for the POST acceptor script and JSFunctionName is the name of the JavaScript function to be used as a call back.
The following example demonstrates how to define a custom menu item which uses the PostDocument action for use within EditLive! for XML. 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.
Example 8.10. Configuring a Custom Item to Use the PostDocument Functionality
<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>The developer can create extended customized functionality in EditLive! for XML via the custom toolbar and menu items. These items can be configured to insert a specific hyperlink or specific HTML at the cursor. They can also be configured to raise specific JavaScript events.
Copyright 2001-2004 Ephox Corporation. All Rights Reserved.