EditLive! 9 Documentation : customComboBoxItem (Applet)

Created by Kristin Repsher, last modified by Brett Henderson on Aug 27, 2013

This element specifies the properties for a developer-defined custom combo box item for use within EditLive!. The custom combo box item must be listed within a <customToolbarComboBox> element and will therefore appear on one of the toolbars within EditLive!.

Configuration Element Tree Structure

<editLive>
<toolbars>
<toolbar>
<customToolbarComboBox>
<customComboBoxItem (Applet)>

<editLive>
     ...
     <toolbars>
         <toolbar>
               <customToolbarComboBox>
                    <customComboBoxItem ... />
               </customToolbarComboBox>
          </toolbar>
     </toolbars>
     ...
</editLive>

Required Attributes

name

The name which uniquely defines this custom combo box item within the <customToolbarComboBox> element. This means that there cannot be two <customComboBoxItem> elements with the same name within one <customToolbarComboBox> element.

text

The text to represent this item within the combo box it is to be listed in.

action

The action which this custom combo box item performs when selected. This attribute has the following possible values:

  • insertHTMLAtCursor- Insert the given HTML at the cursor.

    The specified HTML must already be URL encoded.

  • insertHyperlinkAtCursor- Insert the given hyperlink at the cursor.

    The specified HTML must already be URL encoded.

  • raiseEvent - Call a JavaScript function with the name specified in the value attribute.
  • customPropertiesDialog - Call a JavaScript function with the name specified in the value attribute. The current tag's properties are also passed to this function as a string.
  • PostDocument - Post the content of the applet to a server-side script.

For more information on these actions, please see the Creating Custom Menu and Toolbar Items article.

value

The value of this attribute depends on the value specified in the action attribute.

  • insertHTMLAtCursor - value will be a string of HTML.
  • insertHyperlinkAtCursor - value will be a URL.
  • raiseEvent - value will be the name of the JavaScript function to call. The function will be called providing the id of the editor that the item was selected on. This id is the value used in the JavaScript constructor or in the case of inline mode the div id of the editable section.
  • customPropertiesDialog - value will be the name of the JavaScript function to call, passing the current tag's attributes as a string.
  • PostDocument- the value attribute is 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! for Java uses to POST its content.

      This parameter is required.

    • Post Acceptor URL
      The URL for the POST acceptor that EditLive! for Java is to POST to.

      The parameter is required.

    • Response Processing
      The operation that EditLive! for Java 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 th 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 repsonse 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 attribue 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"

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.

Conditional Attributes

enableintag

This attribute defines in which tags the function should be enabled. For example, when set to td the function will be enabled when the cursor is within a <td> tag (i.e. a table cell).

The enableintag attribute is required when using the customPropertiesDialog action. The enableintag attribute will not work with any of the other action attributes.

Examples

The following example demonstrates how to define a custom combo box item for use within a custom combo box which exists on the EditLive! 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.

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

The following example demonstrates how to define a custom combo box item which uses the raiseEvent action for use within a custom combo box which exists on the EditLive! Command Toolbar. The combo box item defined in this example will call the JavaScript function called eventRaised. This JavaScript function will show an alert with the text "button clicked on " with the id of the editor when then combo box item is selected.

function eventRaised(id) {
	alert("button clicked on " + id);
}
<editLive>
   ...
   toolbars>
        <toolbar name="command">
            <customToolbarComboBox name="customCombo">
                <customComboBoxItem 
                    name="customComboItem1" 
                    text="Custom Combo Item" 
                    action="raiseEvent" 
                    value="eventRaised" />
            </customToolbarComboBox>
        </toolbar>
    </toolbars>
   ...
</editLive>

Remarks

The <customComboBoxItem> element can appear multiple times within the <customToolbarComboBox> element.

The <customComboBoxItem> 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:

<customComboBoxItem name=... />

Text assigned to the value attribute must be URL encoded as it is in the example above.

See Also