Custom Properties Dialogs for EditLive! for Java

Introduction

Ephox EditLive! for Java allows for  developers to specify custom properties dialogs for use with specific tags.  The custom properties dialog functionality of EditLive! for Java allows developers to retrieve and set the attributes for a particular element within EditLive! for Java.  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 Java to include custom menu and toolbar items see the <customToolbarButton> and <customMenuItem> elements in the EditLive! for Java XML Reference.  

When to Use Custom Properties Dialogs

The custom properties dialogs functionality of EditLive! for Java can be used by developers when they wish to extend and customize the functionality of EditLive! for Java in respect to a specific tag.  In this way developers may provide functionality which complements EditLive! for Java's base functionality.

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 Java, to access the properties of  custom or XML tags such as <custom>, or to replace or complement an existing EditLive! for Java dialog, such as the Image Properties dialog which corresponds with the <img> tag.

Interacting with EditLive! for Java and Custom Properties Dialogs

Interacting between EditLive! for Java and custom properties dialogs occurs via a JavaScript API.  This API provides access to a list of relevant properties to an external JavaScript function when a custom properties dialog is called from a toolbar or menu item.  Another element of the JavaScript API then allows for properties to set back to the document contained within EditLive! for Java.  

JavaScript API for Custom Properties

Retrieving the Current Properties

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 Java.  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 Java document and the existing attributes of the relevant tag.  For more information on how to implement a custom properties dialog please see the EditLive! for Java JavaScript API CustomPropertiesDialog Example

<editLiveForJava>
    ...
    <menuBar>
        ...
        <menu>
            <customMenuItem 
                name="customProperties1" 
                text="Custom td Properties" 
                action="customPropertiesDialog" 
                value="customTDFunction" 
                enableintag="td" />
        </menu>
        ...
    </menuBar>    
    ...
</editLiveForJava>

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.

Setting New Properties 

In order to return the changed properties to EditLive! for Java 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 Java.  Also, the tag attribute must be present and the value of this attribute must correspond to the name of the tag (i.e. "span" for a <span> tag).

The following example sets the properties for a tag in the instance of EditLive! for Java named ELJApplet1 with the values stored in the newProperties string:

function makeChanges(paramOne,paramTwo){ 
    ...
        //Content of function goes here
        ELJApplet1_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

The ephoxTagID attribute is used by EditLive! for Java to maintain a reference to the relevant tag inside EditLive! for Java.  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 tag Attribute

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 Java.  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.

Standalone Attributes

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 Java 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.

Summary

EditLive! for Java 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 Java with custom functions.  When creating custom dialogs developers interact with EditLive! for Java 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.

See Also