How To: Create a Custom Jive Project

Version 25

     

    Jive instances can be customized in a number of ways, including overlays, plugins, and themes. Development of these types of customizations occurs within a Maven environment, and Jive employs the use of Maven archetypes to facilitate that development. This document describes the steps create a custom Jive project. Following these steps will ensure a developer of a Jive customization is set up to get going quickly, and with very little fuss.

     

    Having problems?  Tell us what's happening, and we'll assist!

     

    Getting your environment setup

     


     

    JDKs

     

    First, you'll need Maven 3.2.1. You can check to see what version you're using by running the following command:

    mvn --version

     

    Depending on what version of Jive you're coding against, you'll need to have already installed either JDK 6 (up to Jive 6), JDK 7 (Jive 7), or JDK 8 (Jive 8 and later). If you're developing against various versions of Jive, it's also helpful to have some scripts handy to enable easy switching between the JDKs. I have the following entries in my .bash_profile:

     

    export JAVA_6_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
    export JAVA_7_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home
    export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_40.jdk/Contents/Home
    alias java6='export JAVA_HOME=$JAVA_6_HOME;echo JAVA_HOME=$JAVA_6_HOME'
    alias java7='export JAVA_HOME=$JAVA_7_HOME;echo JAVA_HOME=$JAVA_7_HOME'
    alias java8='export JAVA_HOME=$JAVA_8_HOME;echo JAVA_HOME=$JAVA_8_HOME'                        

     

    This makes switching JDKs as easy as typing "java6" or "java7" on the command line:

    java7

    JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home

    java -version

    java version "1.7.0_45"

    Java(TM) SE Runtime Environment (build 1.7.0_45-b18)

    Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)

     

     

    Maven

     

    You will need an account on Jive's Maven Archiva site. If you do not have an account, you can request one by creating a Support Case.

     

    passwords.pngMaven Quick start

    Copy settings.xml and update your local ~/.m2/settings.xml file. Don't forget to update the two node sets of username and password values found at the bottom of the file.

     

     

    You will need to make sure the following entries are in your ~/.m2/settings.xml file (a full example settings.xml file can be found here.

     

        
            
                jive.internal
                Jive's Maven Repository
                
                    https://maven-secure.jivesoftware.com/archiva/repository/jive.internal
                
                
                    false
                
                
                    true
                
            
        
        
            
                jive.internal
                Jive's Maven Repository
                
                    https://maven-secure.jivesoftware.com/archiva/repository/jive.internal
                
                
                    false
                
                
                    true
                
            
        
        
            
                jive.internal
                first.last
                thepassword
            
        
        
            com.jivesoftware.maven.plugins
        
                            

     

    This enables your Maven installation to pull from Jive's Maven Archiva repositories, which contain all the binaries you'll need to create projects, compile against the Jive codebase, and to run your local instance.

     

    Note the last section, <servers>, which contains two <server> entries, each containing a username and password. The credentials for both entries will be the same, and will be those you would use to log into Jive's Maven Archiva site.

     

    The <pluginGroups> section will allow you to create your Jive project using our Mojo shortcut, rather than having to remember and type in the groupId, artifactId, and version for the Jive project creation command covered in the next section.

     

     

     

     

     

    Creating a Project

     


     

    If you're looking to create a custom Jive project or a custom Jive theme, you'll need to execute this step. If you're just creating a Jive Plugin, you can skip this section entirely, but you may still want understand what's going on here, as it's useful for creating a local vanilla Jive instance to use to test your plugins locally.

     

    New project setup

     

    Open up your terminal, and run the following command:

    mvn -U jive:create-project

     

    What's this? This will download the jive-project-plugin, which is a Maven plugin Jive uses to create new projects from our archetype.

     

     

    Afterwards, you will be prompted with a series of questions ( example answers shown in white):

    Which version of Jive? 7.0.0.1: :7.0.0.1

     

    What's this? Here, just specify which version of Jive you're going to customize. All GA versions of Jive, 6.0.0.0 and later, are in play here. Be sure to provide the full version number, and not just something like "6.0.3". If you provide an invalid version, project creation will fail. If you want to accept the default version, which will be the latest version of Jive, just hit the enter key. Specifying the version of Jive you want will also determine the versions of EAE and Search server dependencies.

     

     

    What is your project's group id? Be sure it is unique (com.jivesoftware.customer.project).: com.jivesoftware.customername.communityname

     

    What's this? Specify the group id for your new project here. It should be something like com.jivesoftware.customername.communityname. Specificity is important here, especially if you deploy your build artifacts to Maven. Since this project produces artifacts with common names, like "web" and "themes", you'll need to be sure that other projects for the same customers don't collide when deployed.

     

     

    What is your project's artifact id?:

     

    What's this? Can be the same as the communityname element from the group id. This will be the name of the root project, but won't necessarily be reflected in the names of the sub-module artifacts (web, theme, etc.).

     

    What type of license will your instance use? (internal/external) internal: :

     

    What's this? Determines whether your local instance will act as an internal or external Jive instance. This will affect which profile fields are created by default, and will also determine which features are enabled. Note that, once your instance has been created and initialized, you cannot change the license type. If you do need to change the type of license, you'll need to delete and recreate the instance.

     

     

    Running your new project

     

    Once you have answered these questions, your project will be created in a directory with the same name as the artifactId you specified. Now you can build the new project.

    cd communityname

    mvn clean install -Djive.setup=false

     

     

     

     

     

    Creating a Plugin

     


     

    Plugins offer a much more elegant way to augment the out-of-the-box Jive experience. Many times, a custom project will require many different custom elements, including a web overlay, a theme, and one or more plugins. Usually in these cases, the plugin will be created as a sub-module of the custom project, which requires creating the plugin from the root project directory. It may be, however, that you are creating a standalone plugin, that is not related to a parent project. In this case, plugin creation can be done from wherever you keep your source code.

     

    New plugin setup

     

    If you're creating the plugin as a sub-module to a parent project, navigate to your parent project on the command line.

    cd communityname

     

    To create the plugin project, run the following command:

    mvn -U jive:create-plugin

     

    What's this? The questions asked as a result of the command will differ depending on whether the plugin is being created independent, or as part of a parent project. All the questions listed below will note the conditions under which they are displayed.

     

     

    Which version of Jive? 7.0.0.1: :

     

    What's this? Specify the version of Jive your plugin will support. Be sure to enter the full version number (7.0.0.0, as opposed 7.0.0). If you are creating the plugin inside a parent project, you will not see this question, as the parent project's version will be used.

     

     

    What is your project's group id? Be sure it is unique (com.jivesoftware.customer.project).:

     

    What's this? Specify the group id for your plugin. It should be as specific as possible, so as to avoid namespace collisions, should this plugin be deployed to a Maven repository. If you are creating the plugin inside a parent project, you will not see this questions, and the parent project's groupId will be used.

     

     

    What is your project's artifact id?:

     

    What's this? The name of the plugin, it is required, regardless of where the plugin is being created.

     

     

    Building the new plugin

     

    Once the plugin has been created, you can navigate to its root directory.

    cd plugin-name

     

     

    Once done, you can build the plugin

    mvn clean package

     

     

    .

     

     

    Time to upgrade?

     

    See Upgrades Made Easy(er)