EditLive! 9 Documentation : Creating Plugins Utilizing Advanced APIs Tutorial

Created by Jessica Hardy, last modified by Gavin Douglas on Jul 25, 2012

Getting Started

Required License 

EditLive!'s Advanced APIs and plugin functionality is only supported if an EditLive! Enterprise Edition license has been installed for the editor or if the user is still within their 30 day trial period.

Required Skills

The following skills are required prior to working with this tutorial:

  • Basic client-side JavaScript
  • Basic knowledge of XML
  • Basic knowledge of Java Swing
Required Tutorials Completed

The following tutorials are required to be undertaken before attempting this tutorial:

Tutorial

Step 1. Create a Java class

Create a Java class called AdvancedAPIPlugin. This class will be used to extend EditLive! using the Advanced APIs.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin{
 
       public AdvancedAPIPlugin() {
       }
}

Save this class in a file called AdvancedAPIPlugin.java.

Step 2. Pass EditLive! the Class

Edit the constructor for AdvancedAPIPlugin to require an instance of the ELJBean class. The ELJBean class is the Advanced API instance of EditLive!. When a Java class is registered with an instance EditLive! (whether through the addJar Method or Plugin XML Elements), the instance of EditLive! is passed to the constructor of the class as this ELJBean parameter.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin{
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
       }
}

Step 3. Register an EventListener with the Class

Modify AdvancedAPIPlugin to implement the EventListener interface. This interface is used to catch events fired by EditLive!. Register the EventListener with the instance of ELJBean.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
}

Step 4. Define the raiseEvent Method for Catching Events

Events fired by EditLive! will be passed through the raiseEvent method. Create an instance of this method in AdvancedAPIPlugin.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
 
       public void raiseEvent(TextEvent e) {
       }
}

Create a condition to catch events that have the following conditions:

  • The event type is a CUSTOM_ACTION
  • The event extra type information defines a RAISE_EVENT custom action.
  • The event extra string passes "displayDialog"

These conditions will match the <customMenuItem/> element created in step 10 in the Plugin XML Elements used by this tutorial.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
 
       public void raiseEvent(TextEvent e) {
               if (e.getActionCommand() == TextEvent.CUSTOM_ACTION) {
                       if (e.getExtraInt() == TextEvent.CustomAction.RAISE_EVENT) {
                               if (e.getExtraString().equals("displayDialog")) {
                               }
                       }
               }
       }
}

Step 5. Display a Java Dialog and Insert Content into EditLive!

Handle the event caught to ensure the event is not further propagated to any other EventListeners registered with the ELJBean instance.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
 
       public void raiseEvent(TextEvent e) {
               if (e.getActionCommand() == TextEvent.CUSTOM_ACTION) {
                       if (e.getExtraInt() == TextEvent.CustomAction.RAISE_EVENT) {
                               if (e.getExtraString().equals("displayDialog")) {
                                       e.setHandled(true);
                               }
                       }
               }
       }
}

Use the JOptionPane class to display a dialog to the user.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
 
       public void raiseEvent(TextEvent e) {
               if (e.getActionCommand() == TextEvent.CUSTOM_ACTION) {
                       if (e.getExtraInt() == TextEvent.CustomAction.RAISE_EVENT) {
                               if (e.getExtraString().equals("displayDialog")) {
                                       e.setHandled(true);
 
                                       JOptionPane.showMessageDialog(null, "This dialog has been generated by the EditLive! Advanced APIs");
                               }
                       }
               }
       }
}

Use the insertHTMLAtCursor Method for ELJBean to insert a string of HTML into the EditLive! instance.

import com.ephox.editlive.*;
import com.ephox.editlive.common.*;
import javax.swing.JOptionPane;
 
public class AdvancedAPIPlugin implements EventListener {
 
       ELJBean _bean;
 
       public AdvancedAPIPlugin(ELJBean bean) {
               _bean= bean;
               bean.addEditorEventListener(this);
       }
 
       public void raiseEvent(TextEvent e) {
               if (e.getActionCommand() == TextEvent.CUSTOM_ACTION) {
                       if (e.getExtraInt() == TextEvent.CustomAction.RAISE_EVENT) {
                               if (e.getExtraString().equals("displayDialog")) {
                                       e.setHandled(true);
 
                                       JOptionPane.showMessageDialog(null, "This dialog has been generated by the EditLive! Advanced APIs");
                                       _bean.insertHTMLAtCursor("<b>Advanced API Dialog Called</b>");
                               }
                       }
               }
       }
}

Step 6. Compile the Class into a Jar Archive

Using the instructions in the Compiling and Running the Advanced APIs article in the Developer Guide for this SDK, compile and store the AdvancedAPIPlugin class in a .jar archive called AdvancedAPIPlugin.jar.

Step 7. Create an Instance of EditLive! for Java in a Webpage

Using the load-time properties described in the Instantiating the Editor tutorial, create an instance of EditLive!:

<html>
       <body>
               <h1>Adding a Plugin that Utilizes the Advanced APIs</h1>
               <!--
               Include the EditLive! JavaScript Library
               -->
               <script src="../../redistributables/editlivejava/editlivejava.js" language="JavaScript"></script>
               <!--
               The instance of EditLive!
               -->
               <script language="JavaScript">
                       // Create a new EditLive! instance with the name "ELApplet", a height of 400 pixels and a width of 700 pixels.
                       var editlive = new EditLiveJava("ELApplet", 700, 400);
 
                       // This sets a relative or absolute path to the XML configuration file to use
                       editlive.setConfigurationFile("../../redistributables/editlivejava/sample_eljconfig.xml");
 
                       // .show is the final call and instructs the JavaScript library (editlivejava.js) to insert a new EditLive! instance
                       //  at the this location.
                       editlive.show();
               </script>
       </body>
</html>

Save this webpage as advancedAPIPlugin.html.

Step 8. Create a Plugin XML File

EditLive! loads plugins based on a Plugin XML file. For detailed information on the elements of these Plugin XML files, see the Plugin XML Elements section of the Reference guide for this SDK.

Create an .xml file called advancedAPIPlugin.xml. Create an empty Plugin XML structure featuring only a <plugin> element.

<?xml version="1.0" encoding="US-ASCII" ?> 
<plugin>
</plugin>

Add the attribute load="lazy" to the <plugin> element. Using lazy will ensure that the plugin is only loaded when the user attempts trigger the plugin functionality via its corresponding menu item in EditLive! (see step 10).

<?xml version="1.0" encoding="US-ASCII" ?> 
<plugin load="lazy">
</plugin>

Step 9. Reference the Java Class in the Plugin XML

Use the Plugin XML to create an <advancedapis (Applet)> element that references the AdvancedAPIPlugin.jar and its archived AdvancedAPIPlugin.class.

<?xml version="1.0" encoding="US-ASCII" ?> 
<plugin load="lazy">
       <advancedapis jar="AdvancedAPIPlugin.jar" class="AdvancedAPIPlugin" />
</plugin>

Step 10. Create a Custom Menu Item to be Displayed in the Plugins Menu

In the Custom Toolbar Buttons in the Applet Tutorial you've seen how custom toolbar or menu items can be easily added to EditLive! via the Configuration File. This same logic can be applied to the <menu> element available in the Plugin XML. Any child elements found in a Plugin XML <menu> element will be added to the Plugin menu in EditLive!.

The event fired by a custom menu item can be processed differently by Advanced API code registered with EditLive!. For information on how Advanced API implementations can process events fired by custom menu items, see the Configuration File Differences section of the Advanced API section of the Developer Guide.

Add a <customMenuItem> to advancedAPIPlugin.xml that will perform the following:

  • Display a menu item titled Display Dialog.
  • The action performed will be a raiseEvent.
  • The string passed by this menu item will be "displayDialog" (which will then be caught by the Advanced API code seen in step 4).
<?xml version="1.0" encoding="US-ASCII" ?> 
<plugin load="lazy">
       <advancedapis jar="AdvancedAPIPlugin.jar" class="AdvancedAPIPlugin" />
       <menu>
                  <customMenuItem name="plugin2" action="raiseEvent" value="displayDialog" text="Display Dialog" imageURL="images/small_logo.gif"/> 
       </menu>
</plugin>

Step 11. Register the Plugin With EditLive!

In the advancedAPIPlugin.html file, add a call to the addPlugin Method. Pass the URL for the advancedAPIPlugin.xml file as a parameter.

<html>
       <body>
               <h1>Adding a Plugin that Utilizes the Advanced APIs</h1>
               <!--
               Include the EditLive! JavaScript Library
               -->
               <script src="../../redistributables/editlivejava/editlivejava.js" language="JavaScript"></script>
               <!--
               The instance of EditLive!
               -->
               <script language="JavaScript">
                       // Create a new EditLive! instance with the name "ELApplet", a height of 400 pixels and a width of 700 pixels.
                       var editlive = new EditLiveJava("ELApplet", 700, 400);
 
                       // This sets a relative or absolute path to the XML configuration file to use
                       editlive.setConfigurationFile("../../redistributables/editlivejava/sample_eljconfig.xml");
 
                       // specifying the plugin to use with EditLive!
                       editlive.addPlugin("../../examplePlugins/advancedAPIPlugin.xml");
 
                       // .show is the final call and instructs the JavaScript library (editlivejava.js) to insert a new EditLive! instance
                       //  at the this location.
                       editlive.show();
               </script>
       </body>
</html>