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.
Getting your environment setup
First, you'll need Maven 3.2.1. You can check to see what version you're using by running the following command:
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:
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)
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.
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? 220.127.116.11: :18.104.22.168
What's this? Here, just specify which version of Jive you're going to customize. All GA versions of Jive, 22.214.171.124 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.
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.
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? 126.96.36.199: :
What's this? Specify the version of Jive your plugin will support. Be sure to enter the full version number (188.8.131.52, 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.
Once done, you can build the plugin
mvn clean package
Time to upgrade?