Creating Custom View Tiles

Version 67

    With the Jive Cloud release (and version 8.0), you can build your own HTML view within a tile. This UI extension behaves like an app inside a tile — you can place it anywhere you can place a tile, but you can also control the layout, as you can with an app. It is a compelling way to display your own canvas inside a tile.

    custom view tile.png

    This custom view runs either as a Jive-hosted tile or it can be hosted by your own integration service. With a Jive-hosted tile, Jive will host the static assets and you do not need to run a service at all. Alternatively, you can host the content using your own service and then use that service for background processing or event-driven actions.

     

     

    Create Custom View Tile Manually

     

    A custom view tile is similar to other tiles in many ways except that you have control over the visual layout. This section discusses the differences between a custom view tile and other tiles.

     

    NOTE: This section is intended for someone familiar with Jive tiles. If you want to run through a simple custom view tutorial without understanding these tile-related details, refer to the simple Jive Node SDK example below.

     

    Tile Style

     

    In order to create a Custom View tile manually, you need to specify the following property in definition.json, within your tile definition:

    "style": "CUSTOM_VIEW"

                                                                   

    This tells Jive that you a creating a tile with the CUSTOM_VIEW style.

     

    Tile View

     

    You also have to specify the filename or URL for the view within the tile definition of definition.json:

    "view": "http://my.integration.service.com:8090/sampletile-app/view.html"

                                                                   

    This file or URL provides the HTML for your custom view tile.

     

    Data Provider

     

    If you want to create a Jive-hosted custom view tile, you must specify a local URL for the "view" property (and for the "config" property if you have a configuration UI), and specify that your tile is "internal" using the following JSON property within your tile definition:

    "dataProviderKey": "internal"

                                                                   

    This allows you to create a tile without the need for an integration service.

     

    On the other hand, if you want to host a service, simply omit this dataProviderKey property and specify an http URL for the "view" value in definition.json.

     

    Tile Features

     

    There are certain features you can turn on and off for your custom view tile and this is done with a "features" query string at the end of the "view" URL.

     

    Here are the features available:

     

    FeatureDescription
    core-v3Gives your tile access to the Jive V3 API. Without this feature, your tile cannot access the Jive JavaScript V3 API.
    tileGives your tile access to the lightweight tile API, which includes functions such as jive.tile.onOpen() and jive.tile.close().
    os-2.5Gives your tile access to the OpenSocial JavaScript functions (see OpenSocial 2.5).
    oauthGives your tile access to the JavaScript that supports OAuth popups.
    jq-1.6Gives your tile access to the jQuery library (version 1.6).
    jq-1.9Gives your tile access to the jQuery library (version 1.9).
    jq-1.11Gives your tile access to the jQuery library (version 1.11).
    responsiveAllows this custom view to be visible in responsive mode so that mobile devices can view it. If this feature is turned on, your tile will be shown even in limited resolutions and on mobile devices. Note that it is still your responsibility to design your view to handle these resolutions.
    rewriteInstructs Jive to replace all JS and CSS references with URLs that route through Jive as a proxy.

     

    If you don't specify any features you get all the features except responsive (equivalent to "?features=os-2.5,core-v3,jq-1.6,tile,oauth,rewrite").

     

    If you specify "?features=", you get none of the features.

     

    Example feature options:

     

    ExampleDescription
    "view" : "http://my.integration.service.com:8090/sampletile-app/view.html"View has access to all features except responsive (equivalent to "?features=os-2.5,core-v3,jq-1.6,tile,oauth,rewrite").
    "view" : "http://my.integration.service.com:8090/sampletile-app/view.html?features="View has access to none of the features.
    "view" : "http://my.integration.service.com:8090/sampletile-app/view.html?features=jq-1.11"View has access to jQuery.
    "view" : "http://my.integration.service.com:8090/sampletile-app/view.html?features=jq-1.11,core-v3,responsive"View has access to jQuery and the Jive V3 API and will display in responsive mode.

     

    Sample definition.json

     

    This example illustrates two custom view tiles — one externally hosted tile (tile-app-external) containing all features except responsive, and one Jive-hosted tile (tile-app-internal) with no features:

     

    {
        "tiles": [
            {
                "displayName": "My External Custom Tile",
                "name": "tile-app-external",
                "description": "This is an external custom view tile",
                "style": "CUSTOM_VIEW",
                "displayWidth": "ALL",
                "pageTypes": ["PLACE", "USER"],
                "config": "http://my.service.com:8090/tile-app-external/configuration.html",
                "view": "http://my.service.com:8090/tile-app-external/view.html",
                "id": "976ac1ff-8911-486d-8066-04d1a24d7f7e",
                "definitionDirName": "tile-app-external",
                "published": "2014-12-28T15:12:16.768-0800",
                "updated": "2014-12-28T15:12:16.768-0800",
                "unregister": "http://my.service.com:8090/unregister",
                "register": "http://my.service.com:8090/registration"
            },
            {
                "displayName": "My Internal Custom Tile",
                "name": "tile-app-internal",
                "description": "This is an internal custom view tile",
                "style": "CUSTOM_VIEW",
                "displayWidth": "ALL",
                "pageTypes": ["PLACE", "USER"],
                "dataProviderKey": "internal",
                "view": "/public/tiles/tile-app-internal/view.html?features=",
                "id": "222eb1ff-8911-486d-8066-04d1a24d7328",
                "definitionDirName": "tile-app-internal",
                "published": "2014-12-28T15:12:16.768-0800",
                "updated": "2014-12-28T15:12:16.768-0800",
            }
        ]
    
    }
                                             

     

    Limitations

     

    • To ensure reasonable page load times, you are limited to two custom view tiles per page.
    • For security reasons, if you have an iframe inside your custom view tile, the child iframe of the custom view tile has to declare itself loadable from any origin. The X-Frame-Options header should NOT be present, or it must explicitly permit the Jive domain (using ALLOW-FROM). Refer to The X-Frame-Options response header - HTTP | MDN for more information about this header.

     

    Create Custom View Tile with the Jive Node SDK

     

    The Jive Node SDK contains several examples of custom view tiles. This section walks you through each one, from simplest to most complex. Before running this tutorial, be sure that you install the Jive Node SDK. If you are unfamiliar with Jive tiles or the Jive Node SDK, consider going through a beginner tile tutorial first: Getting Started > Creating a List Tile with the Jive Node SDK.

     

    Simple Custom View Tile (tile-app-simple)

     

    We've created a very simple starter example to help you get a feel for the custom view tile. This example demonstrates how you can have Jive host your HTML code within a tile. No integration service is necessary for this example. To keep things simple, this example doesn't even display a configuration dialog.

     

    To run this example:

     

    1. Create a new simple tile app example:
      jive-sdk create tile-app-simple --name="my-tile"
    2. Update dependencies:
      npm update
    3. Create a Jive-hosted add-on package:

      jive-sdk build add-on --apphosting="jive"

                                                                 
    4. Upload the add-on package to your Jive community: Installing an Add-on into Your Community

    5. Manage the settings of a Jive Place (i.e. a group or a project) and add the tile you have just uploaded to this place. Save the place.
      install-tile.png
    6. Bask in the joy of having created a simple custom view tile.
      tile-app-simple-canvas.png

    Let's break down some of the key parts of this example. If you inspect definition.json, you'll see several important properties.

     

    • The tile style definition:

    "style": "CUSTOM_VIEW"

                                                               
    • The instruction for Jive to host this tile (i.e. internally hosted):

    "dataProviderKey": "internal"

                                                               
    • The instruction that allows this tile to be placed in a Jive Place and in the Your View page (see PageTypes property for more information):

    "pageTypes": [ "PLACE", "USER" ]

                                                               
    • The location of the HTML view code (which does not include any features):

    "view": "/my-tile/view.html?features="

                                                              

    The lack of features will help performance, but if you require additional features (such as jQuery, the Jive V3 API, etc.), refer to the instructions above.

     

    To keep it simple, this example doesn't have any configuration component (there is no "config" property in definition.json) and all the content is hosted by Jive. To make changes, just update the HTML and reupload the add-on package. The HTML can be found at /tiles/tile-name/public/view.html:

     

    <html>
    <head>
        <meta http-equiv="Content-Type" value="text/html; charset=utf-8" />
        <link rel="stylesheet" type="text/css" href="/my-tile/stylesheets/main.css">
        <title>Tile App View</title>
    </head>
    <body>
    <h2>Simple HTML View</h2>
    <p>Update view.html to customize content.</p>
    </body>
    </html>
                                                             

     

    Pretty simple. You can now can display your own content right from within a tile.

     

    Internal Custom View Tile with Config Data (tile-app-internal)

     

    The previous example is an interesting start, but what if you want to build out a configuration page and pass configuration information into your view code? Well, you can do that with the tile-app-internal example. Like the simple tile app above, this tile is hosted by Jive (also known as an "internal" tile) and does not require an integration service.

     

    To run this example:

     

    1. Create a new simple tile app example:
      jive-sdk create tile-app-internal --name="my-tile"
    2. Update dependencies:
      npm update
    3. Create a Jive-hosted add-on package:
      jive-sdk build add-on --apphosting="jive"
    4. Upload the add-on package to your Jive community: Installing an Add-on into Your Community
    5. Manage the settings of a Jive Place (i.e. a group or a project) and add the tile you have just uploaded to this place.
    6. Enter configuration information for your tile.
      tile-app-internal-config.png
    7. Check out your Jive-hosted custom view tile.
      tile-app-internal-canvas.png

    The definition.json file has two main differences from the simple example:

     

    • The view property now supports all features other than responsive design. (As noted in the documentation above, if you do not include the '?feature' query parameter, you get most features automatically.)

    "view": "/my-tile/view.html"

                                                         
    • And we now have a config URL since we want a configuration page:
    "config": "/my-tile/configuration.html"

     

    In order to pass configuration information to your view, you need to call jive.tile.close with a configuration object. This object must contain a "data" object within it. Everything in that data object gets passed into your view function. For example:

     

    "data": {
        "config" : "data",
        "goes" : "here"
    }
                                                        

     

    The configuration logic resides in the /tiles/my-tile/public/javascripts/configuration.js file:

     

    jive.tile.onOpen(function(config, options ) {
            ...
            // populate the dialog with existing config value
            $("#config_string").val( config["data"]["configString"]);
    
            // update config object after clicking submit
            $("#btn_submit").click( function() {
                config["data"]["configString"] = $("#config_string").val();
                jive.tile.close(config, {} );
            });
    });
                                                              

     

    You'll see that it constructs a "data" object with just one value in it (named "configString").

     

    The view logic (/tiles/my-tile/public/javascripts/view.js) gets this configuration data and can populate its view with it:

     

    jive.tile.onOpen(function(config, options) {
        $("#config_string").text(config["configString"]);
        ...
    });
                                                              

     

    You'll see that it extracts the "configString" value and puts this value in the view.

     

    Your view can do whatever it wants with this data and update the HTML as necessary.

     

    Internal Custom View Tile with Tile Action and Properties (tile-app-action)

     

    Now let's add a tile action and have this action allow you to set properties on this tile. This example illustrates how to use private properties. Private properties allow you to store unique data for each user within Jive.

     

    To run this example:

     

    1. Create a new simple tile app example:
      jive-sdk create tile-app-action --name="my-tile"
    2. Update dependencies:

      npm update

                               
    3. Create a Jive-hosted add-on package:
      jive-sdk build add-on --apphosting="jive"
    4. Upload the add-on package to your Jive community: Installing an Add-on into Your Community
    5. Manage the settings of a Jive Place (i.e. a group or a project) and add the tile you have just uploaded to this place.
    6. Enter configuration information for your tile and save the Jive Place.
      tile-app-action-1.png
    7. Click the "Change Data" button to launch the tile action.
      tile-app-action-2.png
    8. Update the private property value.
    9. Note how this data is updated on the tile.
      tile-app-action-3.png
    10. Log in with a different user and browse to the place where this tile resides.
    11. Repeat steps 7, 8, 9.
    12. Note how the config data field is consistent across users but the private property field is unique to the currently logged in user.

     

    The definition.json file has one key difference from the previous example — we now have an action URL since we want a tile action:

    "action": "/my-tile/action.html"

     

    This action page has HTML and JavaScript associated with it (tiles/my-tile/public/action.html, tiles/my-tile/public/javascripts/action.js). We launch this action from within our view code (tiles/my-tile/public/javascripts/view.js) using the following tile command:

    jive.tile.doAction

                              

    We'll leave it to you to investigate this example further, but here are the essential APIs we are accessing in order to get and set properties:

     

    APIDescription
    jive.tile.getPrivatePropsGets the object containing the private properties for the logged-in user for this tile instance.
    jive.tile.updatePrivatePropsUpdate the private properties for the logged-in user for this tile instance.
    jive.tile.getIdentifiers({{callback}})Gets the tile's context
    jive.tile.getContainer({{callback}})Gets details about the tile's container (group information, etc...)

     

    These calls are all used within the view's JavaScript code (tiles/my-tile/public/javascripts/view.js).

     

    Refer to Private Properties and Extended Properties for Jive Tiles for additional information on tile properties.

     

    External Custom View Tile (tile-app-external)

     

    What if you want to build your own integration service and pass information to your view from your service? This is closer to the traditional tile model, where you push data to your tile from your own integration service. In this case, let's use the tile-app-external example...

     

    To run this example:

     

    1. Create a new simple tile app example:
      jive-sdk create tile-app-external --name="my-tile"
    2. Update dependencies:
      npm update
    3. Start your integration service and deploy your add-on package: Deploying a Jive Node SDK Project as an Add-On.
    4. Manage the settings of a Jive Place (i.e. a group or a project) and add the tile you have just uploaded.
    5. Enter configuration information for your tile.
      tile-app-external-config.png
    6. Check out your custom view tile that is hosted by your own integration service.
      tile-app-external-canvas.png

     

    The definition.json file no longer contains the "dataProviderKey" property since we will provide data from our integration service (i.e. the tile is not internal). Additionally, the "view" and the "config" properties are links to external URLs since we intend to host these pages from our own service.

     

    Similar to the internal tile, the configuration.js file calls jive.tile.close with config information, except in this case, this configuration information is passed to our service. And it does not need to contain information nested inside a "data" object (which only applies to internal tiles).

     

    If you inspect /tiles/my-tile/backend/service.js, you'll see that every 10 seconds our integration service pushes data to our canvas view tile. The processTileInstance function shows that we push JSON consisting of two properties:

     

    data: {
      "pushData": configData,
      "pushCount" : count++
    }
                                                          

     

    This example is intended to demonstrate that we can send content to our view using both the configuration data ("pushData") and data created by the service itself ("pushCount").

     

    Our view code (/tiles/my-tile/public/javascripts/view.js), in turn, extracts this information and updates the HTML accordingly:

     

    jive.tile.onOpen(function(data, options) {
        ...
        // update HTML with data pushed from service
        $("#data").text(data["pushData"]);
        $("#count").text(data["pushCount"]);
        ...
    });
                                                          

     

    This example should give you a feel for how to take advantage of this new custom view tile style while using your own integration service.

     

    Unlike traditional tiles that have a specific JSON schema and a tightly-defined UI layout, you are free to define your own rules for how to lay out a custom view tile.