Pages API Overview

Version 24

     

    Summary

     

    Place owners can add additional pages to a place and configure the pages with tiles and streams. This can be done directly from the UI, but you can also use REST APIs (starting with the Fall 2014 Jive Cloud release – version 8c4) to programmatically create and manage pages, tiles, external streams, and templates.

    pages api screenshot.png

    When creating a page, you can create elements of the page using prototypes. A prototype contains sample JSON content that can be used as the foundation for an instance of a new page, tile, stream, or template.

     

    Activity Page vs. Custom Page

     

    There are two types of pages: activity pages and custom pages. An activity page contains recent activity associated with that place; custom pages do not contain this activity stream. There are other differences between these types of pages, which are important to understand when creating and configuring pages.

     

    Activity PageCustom Page
    What is the name of the page/tab?"Activity"You can name it whatever you want
    Does it contain local activity for that place?YesNo
    Does it support external activity streams (i.e. exstreams)?YesNo
    Can it be created with a template?YesNo
    Does it support tiles?Yes (up to 8)Yes (up to 8)
    What layouts does it support?See Page Layouts table below

     

    One additional note about activity pages: If you create a place using the UI, it will automatically create an activity page. If you create a place with the REST API, it will not create an activity page automatically. However, if you browse to a place created via the REST API, you will always see an activity page — if you did not create the activity page manually, a default page is generated on the fly. You can still manually create an activity page for this place using the API and customize it as you want.

     

    Page Layouts

     

    There are several layouts supported for your custom page. The layout is specified in the JSON data you provide when creating a page.

     

    Layout NameWhat does it look like?What page supports this?
    widewide.pngcustom page
    wide_narrowwide_narrow.png

    custom page

    (This layout is visually the same as the activity layout)

    narrow_widenarrow_wide.pngcustom page
    wide_narrow_widenarrow_wide_narrow.pngcustom page
    activitywide_narrow.png

    activity page

    (This layout is visually the same as the wide_narrow layout)

     

    Simple Tutorial

     

    These instructions walk you through the process of creating a custom page with a tile on it.

     

    Step 1: Find a set of tile definitions

     

    Before creating a page, you must first find a set of tiles that you want to put on your page by searching the list of tile definitions. A tile definition is a type of tile that is available for you to use. A tile instance is a specific instantiation of a tile in a specific place. So to begin, we query for the list of tile definitions.

     

    GET https://sandbox.jiveon.com/api/core/v3/tileDefs
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Let's say we like a tile definition with ID 1005, a "Featured Content" tile.

     

    Step 2. Create a set of tile prototypes

     

    We can now create a prototype of this tile definition. A tile prototype is sample JSON data that we can use as the basis for building our tile instance.

     

    GET https://sandbox.jiveon.com/api/core/v3/tileDefs/1005/prototype
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    We repeat this step for all the tiles we are interested in using.

     

    The only change we need to make to this prototype data before using it to create a page is to adjust the column value ("column") and the display width ("displayWidth"). The column is a 0-based index value defining which column in the page layout this tile should reside. The display width should either be "wide" or "narrow", depending on the target column. You can optionally change the display name as well as other settings within this prototype as desired. Below is an abridged version of a tile prototype:

     

    {
      "published" : "2014-11-11T16:16:17.452+0000",
      "updated" : "2014-11-11T16:16:17.452+0000",
      "state" : "VISIBLE",
      "column" : 0,                    <---- COLUMN VALUE
      "data" : { .... etc .... }
      "definition" : {
        "id" : "1005",
        ...
        "displayWidth" : "narrow",     <---- DISPLAY WIDTH
        "pageType" : "place",
        "type" : "tileDefinition"
      },
      "viewstyle" : "list",
      "type" : "tileInstance"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Step 3. Find the correct place ID

     

    We now need to find the place ID we are interested in adding a page to, using the places API.

     

    GET https://sandbox.jiveon.com/api/core/v3/places
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Let's say we want to add a page to place ID 99774...

     

    Step 4. Create a page

     

    Now let's add a page using the Pages API. We include the tile prototypes we received earlier (after adjusting any values as desired).

     

    POST https://sandbox.jiveon.com/api/core/v3/pages
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    In addition to using the proper authentication (either Basic or OAuth), be sure to include the correct content type header for our JSON payload:

     

    Content-Type: application/json
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    And now we'll use the following JSON data:

     

    {
       "name": "My New Page",
       "parent" : "http://sandbox.jiveon.com/api/core/v3/places/99774",
       "tiles": [ {INSERT_JSON_ARRAY_OF_TILE_PROTOTYPES_FROM_STEP_2} ],
       "layout": "narrow_wide",
       "type": "page"
    }
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

     

    Notice that we are using the "narrow_wide" tile layout. Be sure to update the column value and display width for each tile (as specified in step 2) so that they are placed in the correct column of the layout.

     

    That's it. We should now have a new page with our tiles on it.

    Screen Shot 2014-11-14 at 11.35.14 AM.png

     

    Reference Documentation Links

     

    For a reference to the Pages API, refer to: Page service

    For a reference to Tiles, Templates, and Streams API, refer to: Tiles, Streams & Templates entity.