Ephox EditLive! for XML allows for developers to specify custom properties dialogs for use with specific tags. 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.
The custom properties dialogs functionality of EditLive! for XML can be used by developers when they wish to extend and customize the functionality of EditLive! for XML in respect to a specific tag. In this way developers may provide functionality which complements EditLive! for XML's base functionality.
Custom properties dialogs in EditLive! for XML will function only within XHTML sections of the document.
Each menu or toolbar item related to a custom properties dialog is valid for use with a single tag as specified via the enableintag attribute of the relevant <customToolbarButton> or <customMenuItem> element. Thus, developers can create custom dialogs which pertain to specific tags. This is useful in providing new dialogs for HTML elements such as <span> which are not available for direct interaction within EditLive! for XML, to access the properties of custom or XML tags such as <custom>, or to replace or complement an existing EditLive! for XML dialog, such as the Image Properties dialog which corresponds with the <img> tag.
In order to use custom properties dialogs with unknown custom tags the enableintag attribute of the element should be set to custom. Note that this is only for unknown custom tags. For custom tags which are registered with EditLive! for XML via Ephox CSS the enableintag attribute should be set to the name of the specific tag (as with regular HTML tags).
Interacting between EditLive! for XML and custom properties dialogs occurs via a JavaScript API. This API provides access to a list of relevant properties to a JavaScript function when a custom properties dialog is called from a toolbar or menu item within EditLive! for XML. The SetProperties function allows properties returned to EditLive! for XML.
In order to implement a custom properties dialog an associated toolbar or menu item must be created. This can be done within the XML configuration file for EditLive! for XML. The example below demonstrates how to create a custom menu item which can be used to access the properties for a <td> element. The example below calls the JavaScript function customTDFunction. This JavaScript function is supplied with a string that contains the name (or type) of the tag, a number which identifies the particular instance of the tag within the EditLive! for XML document and the existing attributes of the relevant tag. For more information on how to implement a custom properties dialog please see the Custom Properties Dialog function in the runtime API.
Example 9.1. 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.
In order to return the changed properties to EditLive! for XML the SetProperties function of the JavaScript runtime API must be used. This function takes a single argument which is a string representing the name-value pairs for the relevant attributes. In order to correctly set the properties of the relevant tag it should be ensured that the ephoxTagID attribute is not altered by the functions external to EditLive! for XML. For all tags, except for unregistered custom tags, the tag attribute must also be present and the value of this attribute must correspond to the name of the tag (i.e. "span" for a <span> tag).
Example 9.2. Using the SetProperties Function to Set Attributes
The following example sets the properties for a tag in the instance of EditLive! for XML named ELApplet1 with the values stored in the newProperties string:
function makeChanges(paramOne,paramTwo){
...
//Content of function goes here
ELApplet1_js.SetProperties(newProperties);
...
} When constructing the string variable to use with the SetProperties function care should be taken to ensure that the ephoxTagID and tag attributes are correct.
The ephoxTagID attribute is used by EditLive! for XML to maintain a reference to the relevant tag inside EditLive! for XML. This attribute should not be changed when editing the properties of the tag. If the name or value of this attribute is altered in any way the custom properties dialog will not function correctly.
The value of the attribute with the name of tag designates the type of tag for which the properties are relevant. Changing the value of the tag attribute will change the tag type in EditLive! for XML. Thus, if the value of a tag attribute with the value td was changed to th then the relevant table cell would be changed from a normal (td) cell to a table header (th) cell.
The tag for which the custom properties dialog applies may contain standalone attributes. These are attributes which have only a name and do not exist as a name-value pairing. For example, the NOWRAP attribute of the <td> tag. EditLive! for XML outputs these attributes as a name-value pairing where the name and value are the same. In order to remove such attributes from the properties string both the relevant name and value strings should be removed from the properties string. In order to add such an attribute to the properties string a name-value pair in which the name and value are the same (e.g. NOWRAP="NOWRAP") should be added to the properties string.
EditLive! for XML includes functionality allowing developers to create their own custom properties dialogs for specific tags. This allows developers to complement and extend the existing functionality of EditLive! for XML with custom functions. When creating custom dialogs developers interact with EditLive! for XML via a JavaScript API. When interacting with the applet in this fashion it is important to remember several factors including the details of the ephoxTagID and tag attributes.
Copyright 2001-2005 Ephox Corporation. All Rights Reserved.