Getting Started > Creating a List Tile with the Jive Node SDK

Version 31

    In this Getting Started tutorial, we will use the Jive Node SDK to create a simple list tile. A list tile is a Jive tile that can be used in a Place to display a list of information.

    tile-1.png

    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 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.

     

    Instructions

     

    To create a list tile:

    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 tile-list

      This creates a project with all the code necessary to build a simple list tile. The provided sample tile is a counter that updates every ten seconds. The Jive Node SDK uses built-in OAuth 2.0 authentication for tile 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 a tile, you can test it out by going to a Place and creating a tile.
      1. Browse to a Place (i.e. a Space, Project, or Group).
      2. Select Settings from the Manage submenu.
        install-tile-1.png
      3. On the right panel, click "Add a tile".
        install-tile-2.png
      4. Select "sampletile-list" (or whatever you named your tile) from the "Other" tile category.
        install-tile-3.png
      5. This tile has a sample configuration page. Enter a number on the configuration page to configure the tile. Click Submit.
        install-tile-4.png
      6. Click Save at the bottom of the Place.
        install-tile-5.png
      7. Wait ten seconds for the counter to update.

     

    The tile should now update with counter information.

    install-tile-6.png

     

    Code Organization

     

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

    tile-files.png

    The table below describes the folder structure in more detail.

    File or FolderDescription
    app.jsNode service launcher.
    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.
    tiles/samplelist/backendBackend code for tile. In particular, services.js contains the counter code, and the code for pushing content to the tile.
    tiles/samplelist/definition.jsonTile definition.
    tiles/samplelist/publicFrontend code for tile. This folder contains the UI for the tile.
    templates.jsonJive template definition.

     

    The JavaScript file services.js contains the core backend for this example tile. This is probably the best place to begin inspecting the code. The exports properties wire up the essential functions.

    exports.eventHandlers = [

      {

          'event' : jive.constants.globalEventNames.NEW_INSTANCE,

          'handler' : processTileInstance

      },

      {

          'event' : jive.constants.globalEventNames.INSTANCE_UPDATED,

          'handler' : processTileInstance

      }

    ];
    exports.task = [

    {

          'interval' : 10000,

          'handler' : pushData

      }

    ];

    The Jive Node SDK uses the eventHandlers property to ensure that the processTileInstance function gets executed when a new tile is added (NEW_INSTANCE) or an existing tile needs to be updated (INSTANCE_UPDATED). Additionally, the Jive Node SDK provides a task scheduler with the task property. In this case, the pushData handler function will be called every ten seconds (10000 milliseconds). This handler function pushes data into the tile. The data that gets pushed is defined by the getFormattedData function:

    function getFormattedData(count) {

           return {

               data: {

                   "title": "Simple Counter",

                   "contents": [

                       {

                           "text": "Current count: " + count,

                           "icon": "https://community.jivesoftware.com/servlet/JiveServlet/showImage/102-99994-1-1023036/j.png",

                           "linkDescription": "Current counter."

                       }

                   ],

                   "config": {

                       "listStyle": "contentList"

                   },

                   "action": {

                       "text": "Share State",

                       "context": {

                           "count": count

                       }

                   }

               }

    };

     

    NOTE: The Jive Node SDK code uses the Q promise library. Refer to the Q library documentation for information on this mechanism.

     

    Extending the Example

     

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

    1. Open /tiles/samplelist/definition.json. Change the values for "displayName" and "description". These values affect the name and description of your tile when you try to add it to a Place.
    2. In the same file, change sample data "title" and "text" within the "sampleData" section. This is the initial content that will be filled in your list before data is pushed to it from the backend code.
    3. Open /tiles/samplelist/backend/services.js. Change the JSON content of the getFormattedData function to this:

      data: {

          "title": "My Great List",

          "contents": [

              {

                "text": "A cat",

                "icon": "http://localhost:8090/images/cat.png",

                "linkDescription": "A cat."

            },

            {

                            "text": "A dog",

                            "icon": "http://localhost:8090/images/dog.png",

                            "linkDescription": "A dog."

            },

            {

                            "text": "An alien",

                            "icon": "http://localhost:8090/images/alien.png",

                            "linkDescription": "An alien."

            },

            {

                            "text": "A counter: "+count,

                            "icon": "http://localhost:8090/images/count.png",

                            "linkDescription": "A counter."

            },

            {

                            "text": "A link to other content",

                            "icon": "http://localhost:8090/images/link.png",

                            "action":

                            {

                                "text": "This is a link!",

                                "url": "http://www.jivesoftware.com"

                            },

                            "linkDescription": "A link."

            }

          ],

          "config":

          {

              "listStyle": "contentList"

          }

      }

      This JSON snippet is what is pushed to your tile using the jive.tiles.pushData API. For information on the JSON schema for a list tile, as well as other tile styles, refer to Tiles and Tile Styles and List Tile: Design and JSON Schema. For an API reference, refer to the Jive SDK API documentation.
    4. In order to use the icons referenced in the previous JSON snippet:
      1. Download the attached set of (goofy!) images.
      2. Unzip them into a new directory called /public/images/.
      3. Update the icon URLs in the JSON to reflect the domain and port of your Node server. (You can leave it as "localhost:8090" if you are running a Jive server on the same system as your Node server.)
    5. Once you've saved all your changes, restart your Node server and then follow steps #4 and #5 in the earlier instructions in order to deploy and install your new tile to a Place.

     

    You should now see the following information on your tile:

    tile-extended-example.png

    At this point, you should be able to play around with the example to see what else you can do with a list tile and the Jive Node SDK. A useful next step in creating a tile is to play around with tile actions, which give you the ability to create an embedded experience associated with a tile link. For an elaboration on tile actions, refer to Getting Started > Using Tile Actions with the Jive Node SDK.

     

    For More Information