Getting Started > Creating a Cartridge with the Jive Node SDK

Version 6

    In this Getting Started tutorial, we will use the Jive Node SDK to create a simple Jive Anywhere cartridge for Google to easily capture search results and place them into a Jive discussion for collaboration.  The instructions below should take under 15 minutes. The extended example should take another 15 minutes.


    Prerequisites


    Before running this tutorial:

    1. Install the Jive Node SDK on your development system. Installation instructions are described at Getting Started > Installing the Jive Node SDK.
    2. You need to be able to install add-ons with the Jive server used for this tutorial. This will require you to be an administrator, a community manager, or have the sandbox property turned on (jive.extension.sandbox.enabled) to enable the installation of add-ons for personal use.
    3. Note:  In this example the Jive server must be able to communicate with your development system.
    4. You must install and configure Jive Anywhere for your Jive server.
      1. Install: Visit the header dropdown, select Tools and scroll to bottom to install Jive Anywhere for your desired web browser.
      2. Configure: Under the Gear icon, click Settings and then enter your Jive Instance URL in the provided field under the Accounts tab.  Then click Connect.

    Screen Shot 2014-05-18 at 8.14.32 AM.png Screen Shot 2014-05-18 at 8.17.29 AM.png Screen Shot 2014-05-18 at 8.16.32 AM.png

     

    Instructions

     

    To create a Jive Anywhere cartridge:

    1. Browse to an empty directory where you want your code for this tutorial to reside.
    2. Create a cartridge sample using the Jive Node SDK:

      jive-sdk create cartridge

      This creates a project with all the code necessary to build a simple cartridge. The provided sample cartridge is a basic cartridge that will grab search results from Google.

      Note:  As of 05/19/2014 some users have reported an error message similar to "ENOENT, open' ... if this occurs, simply ignore and continue ... we are looking into this issue.


    3. Update all node package dependencies.

      npm update

    4. To test what is provided out of the box, follow instructions for deploying your project at Getting Started > Deploying a Jive Node SDK Project as an Add-On.
      1. Since a cartridge does not require a middleware service, you can simply run
        node app.js
        to build your cartridge to generate the necessary extension.zip
    5. Publish your Cartridge via the Admin Console > Settings > Jive Anywhere > Cartridges
      Screen Shot 2014-05-19 at 12.52.33 PM.png
    6. Once the add-on is installed, visit google.com and search for any search term(s) and click Google Search.
      Screen Shot 2014-05-19 at 12.53.55 PM.png
    7. Click on the Jive Anywhere sidebar (Note: The Active Cartridge Reference should be our google-search-results cartridge)
      Screen Shot 2014-05-19 at 12.54.37 PM.png
    8. Click the "Start a new discussion" button, and notice the preview render a list of all detected search results (automatically)
      Screen Shot 2014-05-19 at 12.51.04 PM.png
    9. Select a place to store this discussion ("Post in:") and enter in some comments and possibly @mentions in the text area below.  The click Post.
    10. To view the thread, simply re-click on the Jive Anywhere sidebar, click on the discussion and interact with it from within Jive Anywhere
      • Note:  If you click on the discussion title, you will be taken to the native Jive instance to read the conversation.

     

    Code Organization

     

    In order to better understand (and to extend) this example, let's first discuss what is provided in this example. The table below describes the folder structure in more detail.

     

    File or FolderDescription
    app.jsNode service launcher. (optional, in a cartridge only add-on)
    extension_srcAuto-generated add-on package source.
    extension.zipAuto-generated add-on package zip.
    jiveclientconfiguration.json

    Service configuration information. See jiveclientconfiguration.json - Definition for additional details.

    • By Default, Jive Add-Ons require a Service URL and because Cartridges are not necessarily dependent on a middleware service, you can set the host to "http:" to bypass the configuration requirement of a service.
    • Note:  It is recommended that after you build your add-on the 1st time, that you lock in your extensionUUID as defined in jiveclientconfiguration.json - Definition for future extension builds.
    node_modulesAuto-generated information about metadata and dependencies. (not used in a cartridge only add-on)
    package.jsonPackage metadata and dependencies. (not used in a cartridge only add-on)
    publicStatic assets. (optional, in a cartridge only add-on)
    cartridges/google-search-results/definition.jsonThis is the add-on definition file that defines the name and URL pattern used for this cartridge.
    cartridges/google-search-results/content/GoogleSearchResultsPageDataTemplate.htmlThe HTML file cartridges/google-search-results/content/GoogleSearchResultsPageDataTemplate.html is used when generating the content preview for the discussion.
    cartridges/google-search-results/content/icon.pngThis icon used
    cartridges/google-search-results/content/module.jsThis JavaScript file cartridges/google-search-results/content/module.js is considered the main file in this cartridge.
    cartridges/google-search-results/content/pagescript.js

    The JavaScript file cartridges/google-search-results/content/pagescript.js is used to inject custom JavaScript into the active page DOM.  In this case, we are using it to grab information about the page being viewed and pass back pieces of information via a JSON object back to the cartridge for further processing.

     

    Extending the Example

     

    Now that you understand the basic organization of the code, let's extend the example a bit more:

    1. Add the following code to the bottom of the pagescript.js to set the background color of all Google Search Results to #ffff00 (or Yellow)

       

      
      function decorateGoogleSearchResults() {
          /*** LOAD RESULTS ***/
          $('li.g').each(function() {
          var result = {};
          result.title = $(this).find('h3.r a').text();
          result.url = $(this).find('h3.r a').attr('href');
          result.description = $(this).find('span.st').text();
      
          if (result.title && result.url) {
             $(this).css('background-color','#ffff00');
          } // end if
        });
      };
      
      decorateGoogleSearchResults();
      
      
      
      
      
      
      

       

    2. Update the pagescript.js > getPreviewData function to include a new variable into the JSON payload (perhaps something from <META>, Url Parameters or JS environment variables.

       

      // ~Line 16
      var result = {};
      result.foo = 'bar';
      // .... code omitted ...
      
      
      
      
      
      

       

    3. Modify the GoogleSearchResultsPageDataTemplate.html to output the new variable from the changes in Step #2 above.

       

      </h3>
         <p>{{>foo}}</p>
      </div>
      <table
      
      
      
      
      
      

       

    4. Re-bundle your Add-On, and re-install it to your Jive server, and publish the cartridge via the Admin Console. (see above)
    5. Close your web browser and repeat the steps on google.com, search for any search term(s) and click Jive Anywhere sidebar (see above)

     

    At this point, you should be able to play around with the example to see what else you can do with the Jive Anywhere cartridge, but learn more about what is possible check out all the Developer Resources and be sure to really read the Jive Anywhere 2.1 SDK.  Happy coding!

     

    For More Information