A Straight and To-The-Point 'Hello World' Plugin for Jive 5.0

    Note: This tutorial assumes that you know how to use Maven and you have Maven 2 installed in your development environment.


    In this tutorial, I will help you develop a plugin that displays Hello, USERNAME! in Admin Console > System > Settings > Hello World. Please note that this tutorial is, as the title says, straight and to the point. I do not go into much detail about anything actually works or exactly what a certain line does. You will need to go out and research this portion for yourself. For the most part, this is all self-explanatory.

     

    Setting up the Plugin

    This is the most critical part of developing any plugin or project is the structure. Otherwise, most web applications or plugins will not compile correctly. Fortunately for us, Maven will do all of this for us! For my plugin, I created a new plugin called HelloWorld:

    mvn archetype:create -e -DarchetypeGroupId=com.jivesoftware.maven -DarchetypeArtifactId=maven-jive-plugin-archetype -DarchetypeVersion=5.0.x-SNAPSHOT -DgroupId=com.jivesoftware.helloworld -DartifactId=HelloWorld
    
    
    
    
    

    Once you run this command, you should see a lot more than what I provide but get the ending success.

    Desktop — sh — 202×56.png

     

    WooHoo! You have a plugin created by Maven and perfectly structured. Keep your terminal window opened, but let's open your Development Environment.

     

    Opening the Plugin in Your Development Environment

    I am not sure what IDE you might use to open your plugin, but I enjoy using IntelliJ for my environment. Opening Maven projects is a lot quicker and simpler than downloading a plugin for Eclipse and figuring out how to import the Maven project. Therefore, this portion is exclusive to IntelliJ with the Maven project. Opening a Maven project in IntelliJ is a simple as File > Open Project, navigate to the project's directory and select on pom.xml.

    IntelliJ IDEA 11.png

     

    Once the project is loaded up in your environment, your environment should have the following structure:

    HelloWorld - [~_Desktop_HelloWorld].pngI am sure from here you can modify IntelliJ to work cleanly with Maven, but we are just going to use the terminal to compile your project with. Now that you have made it this far, you are done! Congrats and you have setup your environment.

     

    Modifying the Plugin.xml

    This part is not completely mandatory, but it is my favorite part of writing plugins. It is a very simple process and I found the Jive Documentation to be very helpful for this portion of the process. Take a quick look over Plugin XML Reference in the docs. Here is what the plugin.xml for this file looks for me:

     

    plugin.xml

    <plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="http://www.jivesoftware.com/schemas/clearspace/2_5/plugin.xsd">
        <name>helloworld</name>
        <description>A nice and simple Hello, World plugin!</description>
        <author>Sean M. Staley</author>
        <version>1.0.0</version>
    
        <!-- It is good practice to only develop a plugin toward one version of Jive SBS -->
        <minServerVersion>5.0.3</minServerVersion>
        <maxServerVersion>5.0.3</maxServerVersion>
    
        <!-- Database Key that should always be added, writing to the database or not -->
        <databaseKey>1000000</databaseKey>
    
      <!-- Initialization Class. Builds and Destroys the plugin -->
        <class>com.jivesoftware.helloworld.HelloWorldPlugin</class>
    
        <!-- Defines the menus where the plugin will exist, can find these in the ui-components.xml of the core code -->
        <components>
            <component id="admin-console">
                <tab id="system">
                    <section id="section-helloworld" name="admin.decorator.menu.system.helloworld.section"
                             description="admin.decorator.menu.system.dbQuery.section.desc">
    
    
                        <item id="helloworld-page" name="admin.decorator.menu.system.helloworld.item"
                              url="helloworld.jspa"
                              description="admin.decorator.menu.system.helloworld.item.desc" />
                    </section>
                </tab>
            </component>
        </components>
    
    
    </plugin>
    
    
    
    

     

    This should be self explanatory after reading the documentation. The most complex thing would be the component portion of the plugin.xml. This is where the new menus will be added into the Jive application and you can look in the ui-components.xml of the core application code.

     

    Creating Java Classes

    I am going to assume that everyone Unit Tests your code (which you should!) so I am going to skip this portion of the tutorial. First, let us setup the HelloWorldPlugin.java class that we mentioned in the plugin.xml above:

     

    HelloWorldPlugin.java

    package com.jivesoftware.helloworld;
    
    
    import com.jivesoftware.base.plugin.Plugin;
    import org.apache.log4j.Logger;
    
    
    /**
    * The class that initializes the plugin in the Jive environment.
    * User: Sean M. Staley
    */
    public class HelloWorldPlugin implements Plugin {
        //Initialize the logger so you can create some logging level messages!
        Logger log = Logger.getLogger(HelloWorldPlugin.class);
    
    
        /**
         * Method that is called when the application starts up with the plugin.
         */
        public void initPlugin() {
            log.info("Starting the HelloWorld Plugin...");
        }
    
    
        public void destroy() {
            log.info("Stopping the HelloWorld Plugin...");
        }
    }
    
    
    
    

     

    This class should be self-explanatory as to what it actually does. Let us move on to our Action class! The action class is what we will map our Struts action to that will glue the UI component to the business object section. I normally create this class in the com.jivesoftware.<pluginName>.action for ease and convention. Here is the completed Java class:

     

    HelloWorldAction.java

    package com.jivesoftware.helloworld.action;
    
    import com.jivesoftware.community.action.admin.AdminActionSupport;
    import org.apache.log4j.Logger;
    
    /**
    * Really dumb logic class
    * User: Sean M. Staley
    */
    public class HelloWorldAction extends AdminActionSupport {
        //Get that logger in there!
        Logger log = Logger.getLogger(HelloWorldAction.class);
    
        //Variable to hold the user's name
        private String userName;
    
        @Override
        public String execute() {
            log.info("In the Action class for the HelloWorld plugin!");
            return SUCCESS;      
        }
    
        public String getUserName() {
            log.debug("The user's username is " + getUser().getUsername());
            return getUser().getUsername();
        }
    }
    
    
    
    

     

    Make it Look Pretty with Freemarker!

    Now it is time to build the view of the application. This is what the end user will view when they load the page. I am not going to go into much detail about what Freemarker is, but all you need to know is that you can pass some variables from the Action into the Freemarker template. You will need to create this file in src/plugin/resources/templates directory of your plugin architecture.

     

    helloWorld-Page.ftl

    <html>
        <head>
            <title>Hello, World!</title>
            <meta name="pageID" content="helloWorld-Page"/>
            <content tag="pagetitle">Hello, World!</content>
            <content tag="pageID">helloWorld-Page</content>
            <content tag="pagehelp">
                <h3>Hello, World!</h3>
                The most essential program for learning anything new!
            </content>
        </head>
    
    
        <body>
            <p>
                <@s.text name="admin.decorator.helloworld.welcome.message"/> ${userName}!
            </p>
        </body>
    </html>
    
    
    

     

    As you can see, the ${userName} is referencing the userName in the Action class above. The admin.decorator.helloworld.welcome.message is a key referenced to a property file that describes what the application will say. As a matter of fact, let us talk about that now!

     

    Property Files and Text Mapping

    This section will focus on the many properties that I have mapped throughout this sample plugin. As you can see, this is really straight forward because each property maps to a certain string of text.

     

    plugin_i18n.properties

    #Admin Console Keys
    admin.decorator.menu.system.helloworld.section=Hello, World!
    admin.decorator.menu.system.helloworld.section.desc=Section to make your day brighter!
    admin.decorator.menu.system.helloworld.item=Hello, World!
    admin.decorator.menu.system.helloworld.item.desc=Page that will make your day brighter!
    
    
    #Message to Users
    admin.decorator.helloworld.welcome.message=Welcome to the Jive application,
    
    
    

     

    Glue it Together With Struts!

    Now is the second most exciting part of this process, aside from defining plugin.xml! Struts is what is used to glue the Java classes together with the View, or Freemarker Template we have created.

     

    struts.xml

    <!DOCTYPE struts PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
            "http://struts.apache.org/dtds/struts-2.0.dtd">
    <struts>
        <package name="HelloWorld-actions" extends="community-admin-default" namespace="/admin">
    
    
            <action name="helloworld" class="com.jivesoftware.helloworld.action.HelloWorldAction">
                <result name="success" type="freemarker">/plugins/helloworld/resources/templates/helloWorld-Page.ftl</result>
            </action>
      </package>
    </struts>
    
    
    

     

    Note: Be sure to have the DOCTYPE included in the top of the struts.xml file, as the application will not know what to look at it as without it.

     

    Not too much Spring

    This plugin does not integrate too much Spring into the application. However, there is a convention to declare one Spring Bean after the class specified in plugin.xml. As you can see, my spring.xml is kind of empty:

     

    spring.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:util="http://www.springframework.org/schema/util"
           xsi:schemaLocation="
            http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd"
           default-autowire="no" default-init-method="init" default-destroy-method="destroy">
    
    
        <bean class="com.jivesoftware.helloworld.HelloWorldPlugin"/>
    
    
    </beans>
    
    
    

     

    Putting it all Together

    Now that you have everything in place, your directory structure should look something like this:

    HelloWorldAction.java - [HelloWorld] - HelloWorld - [~_Desktop_HelloWorld].png

     

    This displays all the files that I have edited and where they should go in the project hierarchy. Now, let us build this with Maven! You will need to change the directory to the project's root directory. A easy way to check is performing an ls in your current location and noteing that the POM.xml is there. Once here, simply type the following command:

    mvn clean package
    
    
    

     

    Here is a visual representation of what it looks like:

    HelloWorld — sh — 199×49-1.png

     

    This will clean, compile, test, and package the entire project. Once Maven is done compiling, you should see something like this:

    HelloWorld — sh — 199×49.png

     

    Now the desired JAR has been created into the ./target/HelloWorld-1.0.5.0.3.0.jar file. You can copy this file to any directory that you would like for it to be in so you can install this into your Jive application. Install it like you normally would a normal plugin and restart the application.

     

    Final Results

    After the restart, you should see something like this in the Admin Console of your Jive application:

    Jive Admin Console _ Hello, World!.pngu

     

    Congrats! You have made a plugin!