XWiki Enterprise 8.4.4 Documentation » Programming Overview » XWiki Platform Plugins Overview

XWiki Platform Plugins Overview

Plugins represented the old way of writing extensions and they were useful when interacting third-party code from the Velocity context. Currently, we are using the XWiki Components.

Architecture

An XWiki plugin consists of:

  • The plugin itself which implements the XWikiPluginInterface interface. It is also possible to extend the XWikiDefaultPlugin class which is actually an adapter to the "XWikiPluginInterface". The plugin contains the core functionality that are only accessible from scripting provided the user has programming rights.
  • The API that extends the Api class and contains all the public methods that are accessible from scripting. 

Create and Use a Plugin

As explained in the above section, any plugin has 2 parts: the plugin itself and the API. A simple example of a plugin's core functionality is:

package com.xpn.xwiki.plugin.helloworld;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import com.xpn.xwiki.XWikiContext;
import com.xpn.xwiki.api.Api;
import com.xpn.xwiki.plugin.XWikiDefaultPlugin;
import com.xpn.xwiki.plugin.XWikiPluginInterface;

// The plugin class declaration

public class HelloWorldPlugin extends XWikiDefaultPlugin {

  // Create a "log4j" instance in order to log errors   

  private static Log LOG = LogFactory.getLog(HelloWorldPlugin.class);

  // Constructor

  public HelloWorldPlugin(String name, String className, XWikiContext context) {
    super(name,className,context);
     init(context);
  }

  // The method used to retrieve the plugin name

  public String getName() {
    return "helloworld";
  }

   // The method used to retrieve the plugin API which requires a cast

  public Api getPluginApi(XWikiPluginInterface plugin, XWikiContext context) {
    return new HelloWorldPluginApi((HelloWorldPlugin) plugin, context);
  }
 
  // You can additionally overload the cache flush method

  public void flushCache() {
  }

  // Method for initializing the context
 
  public void init(XWikiContext context) {
      super.init(context);
  }
}

Having a log4j instance for the plugin is very useful for debugging. An example of the logger invocation would be:

public String getName() {
   LOG.debug("Entered method getName");
  return "helloworld";
}

Next, the API code is:

package com.xpn.xwiki.plugin.helloworld;

import com.xpn.xwiki.XWikiContext;
import com.xpn.xwiki.api.Api;

// The class declaration

public class HelloWorldPluginApi extends Api {
   
  //The plugin field declaration that will allow the API to call backend methods.

  private HelloWorldPlugin plugin;

  //The constructor

  public HelloWorldPluginApi(HelloWorldPlugin plugin, XWikiContext context) {
      super(context);
        setPlugin(plugin);
  }

  //The plugin getter
  
  public HelloWorldPlugin getPlugin(){
      return (hasProgrammingRights() ? plugin : null);
      // Uncomment for allowing unrestricted access to the plugin
      // return plugin;
  }

  //The plugin setter  

  public void setPlugin(HelloWorldPlugin plugin) {
      this.plugin = plugin;
  }

  //The API method that can be called from Velocity

  public String hello() {
      return "Hello World!";
  }

  public void updatePage() {
      //...
  }
}

In order to use the plugin, copy your classes to the XWiki "webapps/xwiki/WEB-INF/classes" folder, or copy the JAR file containing the classes in the "webapps/xwiki/WEB-INF/lib" folder. Finally, you need to register the new plugin in the "WEB-INF/xwiki.cfg" file by adding the line 

 ...,\
 com.xpn.xwiki.plugin.helloworld.HelloWorldPlugin

then restart the server.

To use the plugin in a wiki page, just write "$xwiki.helloworld.hello()" which will display "Hello World!".

XWiki Platform Plugins

Plugins that are in their own JAR

Plugins that are in the XWiki Old Core

Search this space