BC.NEXT - Access All BC Data: JSON Output Everywhere, More REST APIs

Cristinel Anastasoaie - Tuesday, June 17, 2014

The new BC rendering engine we are going to launch will allow us to give more access to the BC data as never before. We will be giving you access to all of the BC rendered data in JSON format in a very flexible and intuitive way.

Today we're announcing some big JSON related features scheduled to come in the next version of BC:

Dynamic .json pages that output module data

BC Partners often asked us to be able to create a JSON page and use existing modules in it, to be able to load data in JS and manipulate it in different ways.

We have implemented now a feature to enable you to create pages that output .JSON, and when rendering that page the following things happen:

  1. The page will not have any template (you cannot set a page-template on those pages)
  2. The modules are being rendered, but all of the values are correctly escaped to be JSON compatible (so you can put them directly in a JSON format)
  3. When the page is outputted, the appropriate JSON content-type is sent
  4. In order to differentiate those dynamic JSON pages from standard HTML pages, we have chosen to have those files on disk as sample.json.html

Suppose we want to output the items of a webapp called testimonials (that has 2 fields: name, content) and we want to list them in a JSON.

We would start by creating a page named testimonials.json.html and use the following code for its content:

{
    "testimonials" : [
            {module_webapps,testimonials,a template=”/testimonials.tpl"}
    ]
}

In the testimonials.tpl file we would have:

{
"name": "{tag_name_nolink}",
"content" : "{tag_description}"
},

Then when accessing the /testimonials.json.html URL we would get a nice-looking JSON file, containing all information from the page:

{
"testimonials": [
      {
"name" : "First Testimonial",
"content”: “This is the content of the first testimonial"
},
      {
"name" : "Second Testimonial",
"content”: “This is the content of the second testimonial"
},
      {
"name" : "Third Testimonial",
"content”: “This is the content of the third testimonial"
}
]
}

With this method you will be able to use existing parameters of the modules (for filtering, sorting) and create your own custom JSON outputs from them, as your application needs it. Also, we automatically detect the trailing comma and remove it.

module_json - a new module to support SEO rendering of JSON files

This module was added for a maximum flexibility in terms of data and layout. The module syntax is:

{module_json json="/module_json/data.json" template="/module_json/template.tpl"}

The module reads the data form the json and renders it using the template with Liquid syntax for rendering (http://docs.businesscatalyst.com/developers/beta/introduction-to-liquid).

Let’s take for example a data.json file that contains:

{
    "description": "List of a collection of Doughnuts",
        "doughnuts":
        [
            {
                "id": "5001", "type": "Plain", "price": 0 }
            ,
            {
                "id": "5002", "type": "Glazed", "price": 1 }
            ,
            {
                "id": "5005", "type": "Sugar", "price": 1 }
            ,
            {
                "id": "5007", "type": "Powdered Sugar", "price": 1.25 }
            ,
            {
                "id": "5006", "type": "Chocolate with Sprinkles", "price": 1.5 }
            ,
            {
                "id": "5003", "type": "Chocolate", "price": 2 }
            ,
            {
                "id": "5004", "type": "Maple Syrup", "price": 2.25 }
        ]
}

And a template.tpl that contains:

<div>{{this.description}}</div>
<ul>
    {% for doughnut in this.doughnuts %}
    <li>
        id={{doughnut.id}} type={{doughnut.type}}
        {% if doughnut.price == 0 %}
            Free!
        {% else %}
            Price: ${{doughnut.price}}
        {% endif %}
    </li>
    {% endfor %}
</ul>

Rendering the page containing the module will result in:

<!DOCTYPE html>
<html xmlns=" http://www.w3.org/1999/xhtml ">
    <!-- BC_OBNW -->
    <head>
        <title>Untitled page</title>
        <meta name="description" />
    </head>
    <body>
        <div>List of a collection of Doughnuts</div>
        <ul>
            <li>id=5001 type=Plain Free!</li>
            <li>id=5002 type=Glazed Price: $1</li>
            <li>id=5005 type=Sugar Price: $1</li>
            <li>id=5007 type=Powdered Sugar Price: $1.25</li>
            <li>id=5006 type=Chocolate with Sprinkles Price: $1.5</li>
            <li>id=5003 type=Chocolate Price: $2</li>
            <li>id=5004 type=Maple Syrup Price: $2.25</li>
        </ul>
    </body>
</html>

As you can see you can have any structure of JSON and use liquid in its full (conditionals, sort, etc). The data is exposed in the same structure as the one in the data file and exposed to liquid under the {{this}} variable.

This allows you to be as creative as you can with the layouts and use this new model of JSON data very flexibly with the new OpenAdmin.

Viewing the modules and the data used to render a page as JSON 

With the evolution of our rendering engine, we are now automatically capturing all the modules and tags rendered in a page in a data tree. We think it will be useful to expose this tree to you, in order to allow you to easily access any data used in a page.

For example, let’s say we have a page named jsonSerialization.html that contains:

<!DOCTYPE html>
<html>
    <head>
        <title>Untitled page</title>
        <meta name="description" content="" />
    </head>
    <body>
        <div>{module_pagename}</div>
        <div>{module_contentholder name="render_contentholder"}</div>
    </body>
</html>

And that the content of the “render_contentholder”  contains just another module:

<div>{module_faq filter="item" itemId="29318"}</div>

The result of calling the http://mysite.com/jsonSerialization.html?json=true will be:

{
   "moduleName":null,
   "pagename":{
      "moduleName":"pagename",
      "name":"jsonSerialization"
   },
   "urlculture":{
      "moduleName":"urlculture",
      "culture":"EN"
   },
   "contentholder":{
      "moduleName":"contentholder",
      "id":"12833",
      "name":"render_contentholder",
      "content":"<div>{module_faq filter="item" itemId="29318"}</div>",
      "faq":{
         "moduleName":"faq",
         "items":[
            {
               "body":"No you cannot combine two lead-in products together. You will need to upgrade to one of the All-in-One plans.<br><br>",
               "answer":"No you cannot combine two lead-in products together. You will need to upgrade to one of the All-in-One plans.<br><br>",
               "id":"29318",
               "question":"Can I combine two lead-in products together?",
               "releaseDate":"2007-11-15",
               "expiryDate":"9999-01-01",
               "lastUpdateDate":"2007-12-04",
               "counter":"1",
               "urlcountrycode_2":{
                  "moduleName":"urlcountrycode",
                  "countryCode":"AU"
               }
            }
         ]
      }
   }
}

As you can see the entire rendering tree and the module data has been outputted to JSON. You can also see that the hierarchy of modules has been respected (the faq is a child-module of the contentholder).

This also offers you a lot of flexibility in accessing BC data in ways that you could not have done before, and it's the foundation of our liquid rendering.

Note: for a quick way to look at your JSON data in the browser, we recommend the Chrome JSON Viewer extension

REST APIs

With the launch of OpenAdmin and the great feedback we received there, we understood that there is a need for even more APIs that expose BC's data to the developers of those applications.

We took this feedback and enhanced the engine with which we're exposing REST APIs to both allow us to create more APIs faster than before and in the same time expose more functionalities in those APIs (like partial updates, PARSE-like language for filtering, sorting, paginating REST queries, and more). Also, we will update the existing Javascript SDK to include these new APIs and features.

We will next be working to create new APIs that the OpenAdmin developer community was asking:

  • Page Properties Update
  • Secure Zones List
  • Template Properties Update
  • Assign web app items to secure zones
  • CRM APIs (customers, cases, orders, events, mailing lists, etc)
  • eCommerce APIs (products, catalogs, discount codes, vouchers, etc)

With these new features, you will be able to exercise your creativity and deliver even more great solutions for your customers.

Looking forward to get these new features in your hands as soon as possible,

The Adobe Business Catalyst Team.

Comments