Getting Started > Creating an App with the Jive Node SDK

Version 14

    In this Getting Started tutorial, we will use the Jive Node SDK to create an App.

    The instructions below should take under 10 minutes. The extended example should take another 20 minutes.

     


     

    NOTE: This tutorial involves creating an integration service using Node.js. For documentation on creating a Jive-hosted app that does not require an integration service, refer to Creating Jive-hosted Apps. However, we recommend that you first run through this (more elaborate) tutorial before creating a Jive-hosted app.

     

    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 on the Jive server being used for this tutorial. This will require you to be an administrator, a community manager, or have the sandbox property turned on to enable the installation of add-ons for personal use (property name: jive.extension.sandbox.enabled). Registered developers can use the Jive Developer Sandbox, which has the sandbox property turned on.
    3. Your development system must be accessible to the Jive server. If your system is not accessible to the Jive server (e.g. behind a firewall), consider using a cloud-based IDE for this tutorial. See Using Nitrous.IO with the Jive Node SDK for one type of cloud-based solution.

     

    Note:  If you'd rather see this app in action, without building yet, you can always check out the "jivedev App Reference" that is globally deployed on the Sandbox.

     

    Instructions

     

    To create an app:

    1. Browse to an empty directory where you want your code for this tutorial to reside.
    2. Create a list tile sample using the Jive Node SDK:
      jive-sdk create app
      This creates a project with all the code necessary to build a simple app. The Jive Node SDK uses built-in OAuth 2.0 authentication for app registration.
    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.
    5. Once you've deployed your app, you can view it by clicking on the Apps menu item and selecting your app ("simpleapp" by default).

      Your default app page should appear.

    Now that you have a working app, let's extend what it can do.

     

    Code Organization

     

    In order to better understand (and to extend) this example, let's first discuss what is provided. The screenshot below highlights the files and folders you will most likely want to change.

     

     

    The table below describes the folder structure in more detail.

    File or FolderDescription
    app.jsNode service launcher.
    apps/simpleapp/publicApp definition and interface.

    apps/simpleapp/public/app.xml

    App module specification.
    dbPlaceholder location for database content.
    extension_srcAuto-generated add-on package source.
    extension.zipAuto-generated add-on package zip.
    jiveclientconfiguration.jsonService configuration information. See jiveclientconfiguration.json - Definition for additional details.
    node_modulesAuto-generated information about metadata and dependencies.
    package.jsonPackage metadata and dependencies.
    publicStatic assets.

     

    The first place to look to understand the app definition is the app.xml file. Among other things, this file defines the relationship between app-related actions and specific views. With app actions, you can wire up your app to various menus and tabs and sidebars throughout the Jive product. Refer to App Action Contribution Reference for more information on app actions.

     

    Extending the Example

     

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

    1. Update the application icons. The three PNG image files found in /apps/simpleapp/public/images are the icons specific to your application. You will need a 16x16 icon (icon16.png), a 48x48 icon (icon48.png) and a 128x128 icon (icon128.png). You can download the attached silly icons and place them in /apps/simpleapp/public/images as an example.
    2. Customize the app name and description. Change the attributes within the ModulePrefs tag of the /apps/simpleapp/public/app.xml file to reflect the desired metadata for your application. The title attribute is displayed when a user clicks the Apps menu from within Jive software.

      <ModulePrefs title="My Example App Reference"

                    description="My Example App Reference Description"

                    author="My Author"

                    author_affiliation="My Company"

                    author_email="myemail@mycompany.com">

    3. Update the app home page. If you inspect app.xml, you will see the following line:
      <Content type="html" view="home,canvas,....." href="canvas.html" preferred_height="400" />
      This line is what causes the file /apps/simpleapp/public/canvas.html to open when you click on the app from the Apps menu. Update this HTML file with some custom content.
    4. Check out the /apps/simpleapp/public/javascripts/main.js for a bevy of examples on how to glean various context aspects. 
      • Note the design of the JavaScript file that helps the scoping of the Javascript runtime, it's not a bad pattern to follow, unless you already have one in mind. =)
    5. This application is designed to implement all known UI extension points listed in App Action Contribution Reference.  You can check it out on the Sandbox yourself either by using your custom app ... or the "jivedev App Reference" that is globally deployed on the Sandbox.
      • Create a Group and check out your Tabs and note the global places and specific place type views.
      • Check out your Profile Tabs (under More) and the Profile navbar
      • View the right-hand sidebar of Content and note the global content and specific content type actions.
      • Create some content and note the !app capability and the different ways you can embed content into the RTE.
        • Note:  At the time of writing this tutorial, jive-sdk v0.1.218, there was an issue with embedding an asset programmatically.  This is being researched.
    6. The three main files you need to review are /apps/simpleapp/public/javascripts/main.js and /apps/simpleapp/public/stylesheets/main.css and /apps/simpleapp/public/canvas.html

      • The mappings for the HTML to App Views are maintained via the /apps/simpleapp/public/app.xml

      • Try customizing an experience the app.xml and make your own actions.  Copy + Paste, or just modify the code Inline.

      • You'll find the using Ngrok: Warp Speed for Your Integration Iterations works really well in this case!

    7. Once you've saved all your changes, log in to Jive and launch the app using the App menu. This action should refresh your app. After opening the main app page, you may need to wait ten or twenty seconds before your new features are accessible.

     

    At this point, you can review the App Action Contribution Reference and find an example for each view/action in your own personal app!  Enjoy. =)

     

    For other Jive Node SDK tutorials, refer to Getting Started with the Jive Node SDK.