In talking with our customers, one of the most requested capabilities is the ability to extend or customize the behavior of EditLive!. Many of the most advanced of these scenarios requires the creation of a plug-in. In addition to customizing the editor experience, plug-ins also make the work of extending EditLive! simpler because they provide:
- Easier management and deployment of extensions/customizations
- More flexibility in deployment – you can choose when to load a plug-in so that users don’t wait for a plug-in to load if they will not use that functionality.
If you are new to EditLive! and plugins we have many plug-ins available via the Ephox support (http://support.ephox.com/forums/20131396-editlive-plugins) that are available for you to use with the Enterprise Edition of EditLive!.
This article will focus solely on how to best deploy a plug-in within EditLive!. The article assumes you already have a plug-in compiled to a JAR and are ready to deploy it within EditLive!.
Deploy a custom Plug-in
To deploy a custom plug-in you only need to do two things:
- Place the plug-in JAR file in a location that is "web accessible" so EditLive can load it at runtime.
- Add a <plugin> tag to the configuration file. This tells EditLive that you want to load a plug-in. The plug-in tag will also tell EditLive where to get the JAR file and which class to invoke at startup.
1. "Deploy" the JAR to a web accessible location
There is no requirement on where you must place your plug-in JAR file other than the location must be “web accessible” so EditLive can load the JAR as the editor itself loads.
We would strongly recommend that you do not place your own plug-ins in our standard plug-in folder. We recommend against this, as it is very easy to forget you have placed custom code in that folder. When upgrading EditLive!, we see many customers accidentally overwrite the plug-in folder and accidentally delete their customizations.
What we recommend instead is to put your plug-ins into their own folder and then reference your folder using the <plugin> and <advancedapis> tags.
For this article we will use this technique and have written these instructions assuming that you have created a myplugins folder at the root of your web application.
In your myplugins folder you need to place the compiled JAR file for your plug-in. For example, if you were using our table styling plug-in you would end up with the tablestyles.jar file in the myplugins folder.
2. Add a <plug-in> tag to the configuration file
The second stage of utilizing a plug-in is to tell EditLive to load the plug-in as it starts. The key to this is the <plugin> tag and its child tag <advancedapis>. Using the myplugins folder that you created in step 1 we create the tags to load the JAR as follows:
<plugin> <advancedapis jar="myplugins/tablestyles.jar" class="com.ephox.editlive.tablestyles.TableStylesPlugin" /> </plugin>
This <plugin> directive must be placed within the <plug-ins> tag that should already exist in your configuration file. EditLive loads a variety of its capabilities via our plug-in mechanism so you will likely see several <plugin> tags in your existing configuration file. After you place your plug-in tag at the end of the list your plug-in will load the next time you start EditLive!.
Confirming your custom Plug-in loaded
Once you have completed the steps detailed above you should restart EditLive! and your plug-in will now be available to you.
Should you want to confirm that this has been successful you can double check this in the debug log. Full details of how to create a debug log can be found at: http://ephox.com/support/debug
If the plug-in has loaded successfully you will see this:
[DEBUG] PluginLoader - -(Thread-104) Plugin loading policy: background
[DEBUG] ClassLoaderFactory - -(Thread-104) creating Class loader for:file:/Users/Shared/offline/web/res/plugins/tablestyles.jar
[DEBUG] PluginClassLoader - -(Thread-104) Loading plugin from file:/Users/Shared/offline/web/res/plugins/tablestyles.jar
If however the plug-in has not loaded successfully you will see an error similar to the following:
[ERROR] InitClassRunnable - -(Thread-163) Failed to load 'com.ephox.editlive.plugins.tablestyles.TableStylesPlugin' from 'tablestyles.jar' using base URL 'file:/Users/Shared/offline/web/res/plugins/tablestyles.xml'. <java.lang.ClassNotFoundException: com.ephox.editlive.plugins.tablestyles.TableStylesPlugin>java.lang.ClassNotFoundException: com.ephox.editlive.plugins.tablestyles.TableStylesPlugin
If you see an error and your plug-in has not loaded successfully the first thing to check is that the jar is in a file that is web accessible and secondly that you have entered the correct name and path for the files in the configuration file. Ephox support are available to assist and you can raise a support case via our website if you would like any further details or assistance.
The Plug-in APIs used by these plug-ins are only available to customers of the EditLive! Enterprise Edition.
Ephox Technical Support does not cover custom plug-ins.
Please direct any support requests or general enquiries about any code, integrations or plug-ins to the Ephox Support Forum. This code is released as-is with no support and no warranty and is installed at your own risk. We recommend thorough testing of any project before deploying to any production system.