Links

The links element in a Cj document is always a valid JSON array which contains one or more link objects. Important link properties include href, rel, and prompt. These work similarly to the way HTML <a>…</a> tags do—static URLs for HTTP GET actions:

"links": [
  {
    "href": "http://rwcbook12.herokuapp.com/home/",
    "rel": "home collection",
    "prompt": "Home"
  },
  {
    "href": "http://rwcbook12.herokuapp.com/task/",
    "rel": "self task collection",
    "prompt": "Tasks"
  },
  {
    "href": "http://rwcbook12.herokuapp.com/user/",
    "rel": "user collection",
    "prompt": "Users"
  }
]

In Cj, the links section typically holds links that are relevant for the current document or, in a human-centric UI, the current screen or web page. Along with important navigation links for the app (see in the previous example), the links section may include things like page-level navigation (first, previous, next, last) or other similar links.

Another handy property on Cj link objects is the render property. This tells consuming apps how to treat the link. For example, if the render value is set to "none", client apps are not expected to display the link. This is handy when passing link elements for things like CSS stylesheets, profile URLs, or other types of information:

"links": [
  {
    "href": "http://api.example.org/profiles/task-management",
    "rel": "profile",
    "render" : "none"
  }
]

Items

Probably the most unique element in Cj documents is the item sections. The items section is similar to HAL’s root-level properties and Siren’s properties object. Cj items contain the domain objects in the response, such as users, customers, products, and so forth. However, unlike the way HAL and Siren express domain objects, Cj has a highly structured approach. HAL and Siren express their domain objects as either simple name–value pairs or, in the case of Siren, as subentities. And both HAL and Siren support sending nested JSON objects as properties. But Cj doesn’t work like that and this can be a source of both frustration and freedom.

Here is an example of a user object expressed as a Cj item:

{
  "rel": "item http://api.example.org/rels/user",
  "href": "http://api.example.org/user/alice", 
  "data": [ 
    {"name": "id", "value": "alice", "prompt": "ID", "render":"none"},
    {"name": "nick", "value": "alice", "prompt": "Nickname"},
    {"name": "email", "value": "[email protected]", "prompt": "Email"},
    {"name": "name", "value": "Alice Teddington, Jr.", "prompt": "Full Name"}
  ],
  "links": [ 
    {
      "prompt": "Change Password",
      "rel": "edit-form http://api.example.org/rels/changePW",
      "href": "http://api.example.org/user/pass/alice"
    },
    {
      "prompt": "Assigned Tasks",
      "rel": "collection http://api.example.org/rels/filterByUser",
      "href": "http://api.example.org/task/?assignedUser=alice"
    }
  ]
}

As you see in this example, a Cj item contains the rel and href (), and a list of data elements (), and may also contain one or more link elements for read-only actions () associated with the item. The way Cj expresses the item properties (id, nick, email, and name) is unique among the formats covered in this book. Cj documents return not just the property identifier and value (e.g., "id":"alice") but also a suggested prompt property. Cj also supports other attributes, including render to help clients decide whether to display the property on screen. This highly structured format makes it possible to send both the domain data and metadata about each property and object. As we’ll see when we start working on the Cj client app, this added data comes in handy when creating a human-centric interface.

The links collection within each Cj item contains one or more static safe (read-only) links, like those in the root-level links collection. This space can be used to pass item-level links within a Cj response. For example, in the preceding snippet, you can see a link that points to a form for updating the user password and a link that points to a filtered list of tasks related to this user object. The item-level links section is optional and any link that appears in the collection must be treated as safe (e.g., dereferenced using HTTP GET).

Queries

The queries element in Collection+JSON is meant to hold safe requests (e.g., HTTP GET) that have one or more parameters. These are similar to HTML forms with the method attribute set to GET. The queries section in a Cj document is an array with one or more query objects. They look similar to Cj link objects but can have an associated data array, too.

Here’s an example:

{
  "rel": "search",
  "name" : "usersByEmai",
  "href": "http://api.example.org/user/",
  "prompt": "Search By Email",
  "data": [
    {
      "name": "email",
      "value": "",
      "prompt": "Email",
      "required": "true"
    }
  ]
}

As you can see from the preceding example, a Cj query object has rel, name, href, and prompt attributes. There also may be one or more data elements. The data elements are similar to HTML input elements. Along with the name, value, and prompt attributes, data elements can have required and (not shown in the previous example) readOnly and pattern attributes. These last attributes help services send clients additional metadata about the arguments for a query.

Note that Cj query objects do not have an attribute to indicate which HTTP method to use when executing the query. That is because Cj queries always use the HTTP GET method.

There is another Cj element that is similar to HTTP FORM: the template element.

Template

Cj’s template element looks similar to the Cj queries element—but it’s even smaller. It only has a set of one or more data elements. These data elements represent the input arguments for a write action (e.g., HTTP POST or PUT). Let’s take a look at what a Cj template looks like:

"template": {
  "prompt": "Add Task",
  "data": [
    {"name": "title", "value": "", "prompt": "Title", "required": "true"},
    {"name": "tags", "value": "", "prompt": "Tags"},
    {"name": "completeFlag", "value": "false", "prompt": "Complete",
      "patttern": "true|false"}
  ]
}

The template element can have an optional prompt, but the most important part of the template is the data array that describes the possible input arguments for the write operation. Like the data elements that appear in Cj queries and items, the template’s data elements include name and value properties along with a prompt property. And, like the queries version of data elements, they can have additional metadata attributes, including readOnly, required, and pattern. The pattern element works the same way as the HTML pattern attribute.

There are two important aspects of write operations missing from the Cj template: (1) the target URL, and (2) the HTTP method. That’s because in Cj, the template applies to two different parts of the CRUD model: create and update. Just how the request is executed depends on what the client app wants to do.

*** REQUEST ***
POST / HTTP/1.1 
Host: http://rwcbook12.herokuapp.com
Content-Type: application/vnd.collection+json
...

"template": {
  "data": [
    {"name": "title", "value": "adding a new record"},
    {"name": "tags", "value": "testing adding"},
    {"name": "completeFlag", "value": "false"}
  ]
}

*** REQUEST ***
PUT /1sv697h2yij HTTP/1.1 
Host: http://rwcbook12.herokuapp.com
Content-Type: application/vnd.collection+json
...
"template": {
  "data": [
    {"name": "id", "value": "1sv697h2yij"},
    {"name": "title", "value": "Marina Del Ray"},
    {"name": "completed", "value": "true"}
  ]
}

Error

The Collection+JSON design also includes an error element. This is used to pass domain-specific error information from server to client. For example, if a resource cannot be found or an attempt to update an existing record failed, the server can use the error element to return more than HTTP 404 or 400. It can return a text description of the problem and even include advice on how to fix it.

For example, if someone attempted to assign a TPS task to a nonexistent user, the server might respond like this:

{
  "collection": {
    "version": "1.0",
    "href": "//rwcbook12.herokuapp.com/error/",
    "title": "TPS - Task Processing System",
    "error": {
      "code": 400,
      "title": "Error",
      "message": "Assigned user not found (filbert). Please try again.",
      "url": "http://rwcbook12.herokuapp.com/task/assign/1l9fz7bhaho"
    }
  }
}

As mentioned earlier, there are some additional elements and properties of Cj documents that I won’t cover here. You can check out the full specification at the online site listed in the Reference section at the end of this chapter (see “References”).

A Quick Summary

By now, we can see that the three featured hypermedia types (HAL, Siren, and Cj) have several things in common. Like HAL and Siren, Cj has an element (links) for communicating Addresses. And, like Siren, Cj’s queries and template elements communicate Action metadata in responses. And all three have a way to communicate domain-specific Objects (HAL’s root-level properties, Siren’s properties object and Cj’s items collection). Cj’s items collection is unique because it includes metadata about each property in the domain object (e.g., prompt, render, etc.). This elevates Cj’s ability to handle the Object aspect of the OAA Challenge. We’ll talk about this again when we build the Cj client app.

For now, we have enough background to review the Cj representor and then walk through our Cj client SPA code.

The Top-Level Processing Loop

The top-level processing loop for my Cj representor is very simple. It starts by initializing an empty collection object (to represent a Cj document in JSON) and then populates this object with each of the major Cj elements:

• Links

• Items

• Queries

• Template

• Error (if needed)

function cj(wstlObject, root) {
  var rtn;

  rtn = {};
  rtn.collection = {}; 
  rtn.collection.version = "1.0";

  for(var segment in wstlObject) {
    rtn.collection.href = root+"/"+segment+"/"; 
    rtn.collection.title = getTitle(wstlObject[segment]); 
    rtn.collection.links = getLinks(wstlObject[segment].actions);
    rtn.collection.items = getItems(wstlObject[segment],root);
    rtn.collection.queries = getQueries(wstlObject[segment].actions);
    rtn.collection.template = getTemplate(wstlObject[segment].actions);

    // handle any error
    if(wstlObject.error) { 
      rtn.collection.error = getError(wstlObject.error);
    }
  }
  // send results to caller
  return JSON.stringify(rtn, null, 2); 
}

The code just shown has just a few interesting items. After initializing a collection document () and establishing the document-level href (), the code walks through the passed-in WeSTL object tree () and constructs the Cj title, links, items, queries, and template elements. Then, if the current object is an error, the Cj error element is populated (). Finally, the completed Cj document is returned () to the caller.

Now, let’s take a look at each of the major routines used to build up the Cj document.

Links

The links element in Cj holds all top-level links for the document. The Cj representor code scans the incoming WeSTL object for any action element that qualifies and, if needed, resolves any URI templates before adding the link to the collection.

Here’s the code:

// get top-level links
function getLinks(segment, root, tvars) {
  var link, rtn, i, x, tpl, url;

  rtn = [];
  if(Array.isArray(segment)!==false) {
    for(i=0,x=segment.length;i<x;i++) { 
      link = segment[i];
      if(link.type==="safe" &&
        link.target.indexOf("app")!==-1 &&
        link.target.indexOf("cj")!==-1) 
      {
        if(!link.inputs) {
          tpl = urit.parse(link.href);
          url = tpl.expand(tvars); 
          rtn.push({ 
            href: url,
            rel: link.rel.join(" ")||"",
            prompt: link.prompt||""
          });
        }
      }
    }
  }
  return rtn; 
}

Here are the high points in the getLinks function:

If we have action objects, loop through them.

First, check to see if the current link meets the criteria for top-level links in a Cj document.

If it does, use the passed-in tvars collection (template variables) to resolve any URI Template.

Then add the results to the link collection.

Finally, return the populated collection to the caller.

Items

The next interesting function is the one that handles items. This is the most involved routine in the Cj representor. That’s because Cj does quite a bit to supply both data and metadata about each domain object it passes to the client app.

Here’s the code:

// get list of items
function getItems(segment, root) {
  var coll, temp, item, data, links, rtn, i, x, j, y;

  rtn = [];
  coll = segment.data;
  if(coll && Array.isArray(coll)!==false) {
    for(i=0,x=coll.length;i<x;i++) {
      temp = coll[i];

      // create item and link
      item = {}; 
      link = getItemLink(segment.actions);
      if(link) {
        item.rel = (Array.isArray(link.rel)?link.rel.join(" "):link.rel);
        item.href = link.href;
        if(link.readOnly===true) {
          item.readOnly="true";
        }
      }

      // add item properties
      tvars = {}
      data = [];
      for(var d in temp) { 
        data.push(
          {
            name : d,
            value : temp[d],
            prompt : (g.profile[d].prompt||d),
            render:(g.profile[d].display.toString()||"true")
          }
        );
        tvars[d] = temp[d];
      }
      item.data = data;

      // resolve URL template 
      tpl = urit.parse(link.href);
      url = tpl.expand(tvars);
      item.href = url;

      // add any item-level links 
      links = getItemLinks(segment.actions, tvars);
      if(Array.isArray(links) && links.length!==0) {
        item.links = links;
      }

      rtn.push(item); 
    }
  }
  return rtn; 
}

The getItems routine is the largest in the Cj representor. It actually handles three key things: the URL for the item, the item’s data properties, and any links associated with the item. Here’s the breakdown:

For each data item in the list, first set the href property.

Then loop through the properties of the domain object and construct Cj data elements.

After collecting the data values, use that collection to resolve any URL template in the item’s href.

Next, go collect up (and resolve) any Cj link objects for this single item.

Once all that is done, add the results to the internal item collection.

Finally, return the completed collection to the calling routine.

The resulting item collection looks like this:

"items": [
  {
    "rel": "item",
    "href": "http://rwcbook12.herokuapp.com/task/1l9fz7bhaho",
    "data": [
      {"name":"id","value":"1l9fz7bhaho","prompt":"ID","render":"true"},
      {"name":"title","value":"extensions","prompt":"Title","render":"true"},
      {"name":"tags","value":"forms testing","prompt":"Tags","render":"true"},
      {"name":"completeFlag","value":"true","prompt":"Complete Flag",
        "render":"true"},
      {"name":"assignedUser","value":"carol","prompt":"Asigned User",
        "render":"true"},
      {"name":"dateCreated","value":"2016-02-01T01:08:15.205Z",
        "prompt":"Created","render":"false"}
    ],
    "links": [
      {
        "prompt": "Assign User",
        "rel": "assignUser edit-form",
        "href": "http://rwcbook12.herokuapp.com/task/assign/1l9fz7bhaho"
      },
      {
        "prompt": "Mark Active",
        "rel": "markActive edit-form",
        "href": "http://rwcbook12.herokuapp.com/task/active/1l9fz7bhaho"
      }
    ]
  }
  ... more items here ...
]

Queries

The getQueries routine is the one that generates the “safe” parameterized queries—basically HTML GET forms. That means, along with a URL, there is a list of one or more argument descriptions. These would be the input elements of an HTML form. The code that generates Cj queries is very straightforward and looks like this:

// get query templates
function getQueries(segment) {
  var data, d, query, q, rtn, i, x, j, y;

  rtn = [];
  if(Array.isArray(segment)!==false) {
    for(i=0,x=segment.length;i<x;i++) { 
      query = segment[i];
      if(query.type==="safe" &&  
        query.target.indexOf("list")!==-1 &&
        query.target.indexOf("cj") !==-1)
      {
        q = {}; 
        q.rel = query.rel.join(" ");
        q.href = query.href||"#";
        q.prompt = query.prompt||"";
        data = [];
        for(j=0,y=query.inputs.length;j<y;j++) { 
          d = query.inputs[j];
          data.push(
            {
              name:d.name||"input"+j,
              value:d.value||"",
              prompt:d.prompt||d.name,
              required:d.required||false,
              readOnly:d.readOnly||false,
              patttern:d.pattern||""
            }
          );
        }
        q.data = data;
        rtn.push(q); 
      }
    }
  }
  return rtn; 
}

The walk-through is rather simple:

Loop through all the transitions in the WeSTL document.

Find the transitions that are valid for the Cj queries collection.

Start an empty query object and set the href and rel properties.

Loop through the WeSTL input elements to create Cj data elements for the query.

Add the completed query to the collection.

Finally, return that collection to the calling routine.

Again, there is no HTTP method supplied for each query since the spec says all Cj queries should be executed using HTTP GET.

That covers the read operations in Cj. Next is the work to handle the write operations—the ones handled by the Cj template.

Template

In Cj, write operations are represented in the template element. The getTemplate routine in our Cj representor handles generating the template element, and the code looks like this:

// get the add template
function getTemplate(segment) {
  var data, temp, field, rtn, tpl, url, d, i, x, j, y;

  rtn = {};
  data = [];
  if(Array.isArray(segment)!==false) {
    for(i=0,x=segment.length;i<x;i++) {
      if(segment[i].target.indexOf("cj-template")!==-1) { 
        temp = segment[i];

        // emit data elements
        data = [];
        for(j=0,y=temp.inputs.length;j<y;j++) { 
          d = temp.inputs[j];
          field = { 
            name:d.name||"input"+j,
            value:(d.value||"",
            prompt:d.prompt||d.name,
            required:d.required||false,
            readOnly:d.readOnly||false,
            patttern:d.pattern||""
          };
          data.push(field); 
        }
      }
    }
  }
  rtn.data = data;
  return rtn; 
}

There is not much to the getTemplate routine, so the highlights are a bit boring:

Loop through the WeSTL transitions and find the one valid for Cj template.

Then loop through the transition’s input collection.

Use that information to build a Cj data element.

And add that to the collection of data elements for this template.

Finally, after adding the completed data collection to the template object, return the results to the caller.

As a reminder, there is no href property or HTTP method for Cj templates. The URL and method to use are determined by the client at runtime based on whether the client is attempting a Create or Update action.

That leaves just one small object to review: the Cj error element.

Error

Unlike HAL and Siren, Cj has a dedicated error element for responses. This makes it easy for clients to recognize and render any domain-specific error information in server responses. There are only four defined fields for the Cj error object: title, message, code, and url. The getError function is small and looks like this:

// get any error info
function getError(segment) {
  var rtn = {};

  rtn.title = "Error";
  rtn.message = (segment.message||"");
  rtn.code = (segment.code||"");
  rtn.url = (segment.url||"");

  return rtn;
}

There is really nothing to talk about here since the routine is so simple. It is worth pointing out that Cj responses can include both error information and content in the links, items, queries, and template elements. That makes it possible to return a fully populated Cj document along with some error information to help the user resolve any problems.

With the Cj representor walk-through completed, it’s time to review the Cj client SPA.

The HTML Container

All the SPA apps in this book start with an HTML container, and this one is no different. Here is the static HTML that is used to host the Cj documents sent by the server:

<!DOCTYPE html>
<html>
  <head>
    <title>Cj</title>
    <link href="./semantic.min.css" rel="stylesheet" />
  </head>
  <body>
    <div id="links"></div> 
    <div style="margin: 5em 1em">
      <h1 id="title" class="ui page header"></h1> 
      <div id="content" style="margin-bottom: 1em"></div> 
      <div class="ui mobile reversed two column stackable grid">
        <div class="column">
          <div id="items" class="ui segments"></div> 
        </div>
        <div class="column">
          <div id="edit" class="ui green segment"></div>
          <div id="template" class="ui green segment"></div> 
          <div id="error"></div> 

          <div id="queries-wrapper">
            <h1 class="ui dividing header">
              Queries
            </h1>
            <div id="queries"></div> 
          </div>
        </div>
      </div>

      <div>
        <pre id="dump"></pre>
      </div>

    </div>
  </body>
  <script src="dom-help.js">//na </script>
  <script src="cj-client.js">//na </script> 
  <script>
    window.onload = function() {
      var pg = cj();
      pg.init("/", "TPS - Task Processing System"); 
    }
  </script>
</html>

A lot of the HTML shown here supports the layout needs of the CSS library. But you can still find all the major Cj document elements represented by <div> tags in the page. They are:

The links collection

The title element

The content element

The items element

The template element

The error element

The queries element

The Cj parsing script is loaded at and, after everything loads, the initial request starts at . That line calls into the top-level parse loop for the Cj library.

The Top-Level Parse Loop

In the Cj client, the top-level parse loop gets called each time a user makes a selection in the UI, which follows the Request, Parse, Wait (RPW) pattern I covered in Chapter 5. It turns out the parse loop for Cj is a bit simpler than the ones for the JSON, HAL, and Siren clients:

// init library and start
  function init(url) {
    if(!url || url==='') {
      alert('*** ERROR:

MUST pass starting URL to the Cj library');
    }
    else {
      global.url = url;
      req(global.url,"get"); 
    }
  }

  // primary loop
  function parseCj() { 
    dump();
    title();
    content();
    links();
    items();
    queries();
    template();
    error();
    cjClearEdit();
  }

This code set should look pretty familiar by now. After making the initial request (), the parseCj routine () is called and it walks through all the major elements of a Collection+JSON document. The only other interesting elements in this code snippet are the internal routines. First, the call to the dump() method at the start of the loop—this is just for debugging help on screen—and second, the cjClearEdit() call at the end of the routine to handle cleaning up the HTML div used to display the UI’s current editing form.

I’ll skip talking about the title and content routines here—you can check them out in the source code. We’ll now walk through the other major routines to handle Cj responses.

Links

The routine that handles parsing and rendering Cj links is pretty simple. However, it has a bit of a twist. The code checks the domain-specific metadata about the link. For example, some links are not rendered on the screen (e.g., HTML stylesheets, IANA profile identifiers, etc.). Some other links should actually be rendered as embedded images instead of navigational links. The Cj design allows servers to indicate this level of link metadata in the message itself—something the HAL and Siren clients do not support in their current design.

Here’s the code for the links() function:

// handle link collection
function links() {
  var elm, coll, menu, item, a, img, head, lnk;

  elm = domHelp.find("links");
  domHelp.clear(elm);
  if(global.cj.collection.links) { 
    coll = g.cj.collection.links;
    menu = domHelp.node("div");
    menu.className = "ui blue fixed top menu";
    menu.onclick = httpGet;

    for(var link of coll) { 
      // stuff render=none Cj link elements in HTML.HEAD 
      if(isHiddenLink(link)===true) {
        head = domHelp.tags("head")[0];
        lnk = domHelp.link({rel:link.rel,href:link.href,title:link.prompt});
        domHelp.push(lnk,head);
        continue;
      }
      // render embedded images, if asked 
      if(isImage(link)===true) {
        item = domHelp.node("div");
        item.className = "item";
        img = domHelp.image({href:link.href,className:link.rel});
        domHelp.push(img, item, menu);
      }
      else {
        a = domHelp.anchor({rel:link.rel,href:link.href,text:link.prompt, 
          className: "item"});
        v.push(a, menu);
      }
    }
    domHelp.push(menu, elm); 
  }
}

While there is quite a bit of code here, it’s all straightforward. The highlights are:

After making sure there are Cj links to process, set up some layout to hold them.

Now start looping through the links collection.

If the link element should now be rendered, place it in the HTML <head> section of the page.

If the link element should be rendered as an image, process it properly.

Otherwise, treat is as a simple <a> tag and add it to the layout.

Finally, push the results to the viewable screen.

Figure 8-2 shows an example of rendering the Cj links at runtime.

Figure 8-2. Rendering Cj links at runtime

It turns out that the cases where the link element is not displayed () or the link is an image () takes more code than cases where the link element is just a navigational element (). We’ll see some more of that kind of code when we parse the items collection.

Items

The items() function is the most involved routine in the Cj library. At 125 lines, it is also the longest. That’s because (as we saw when reviewing the items handling in the Cj representor) the items element is the most involved of all in the Cj document design. I won’t include all the lines of this routine but will show the key processing in the routine. You can find the full set of code in the source code repo associated with this chapter.

I’ll break up the code review for the items() routine into three parts:

• Rendering Cj item editing links

• Rendering Cj item links

• Rendering Cj item data properties

First, the code that handles each item’s Read-Update-Delete links—the last three elements of the CRUD pattern. Each Cj item has an href property and, optionally, a readOnly property. Using this information as a guide, Cj clients are responsible for rendering appropriate support for the read, update, and delete links. You can see this in the code that follows. At , the read link is created. The update link is created at and the delete link is created at . Note the checking of both the readOnly status of the client as well as whether the template can be found in the Cj document. These values are used to decide which links (update and delete) are rendered for the item:

// item link
a = domHelp.anchor( 
  {
    href:item.href,
    rel:item.rel,
    className:"item link ui basic blue button",
    text:item.rel
  }
);
a.onclick = httpGet;
domHelp.push(a1,buttons);

// edit link
if(isReadOnly(item)===false && hasTemplate(g.cj.collection)===true) {
  a = domHelp.anchor( 
    {
      href:item.href,
      rel:"edit",
      className:"item action ui positive button",
      text:"Edit"
    }
  );
  a.onclick = cjEdit;
  domHelp.push(a2, buttons);
}

// delete link
if(isReadOnly(item)===false) {
  a = domHelp.anchor( 
    {
      href:item.href,
      className:"item action ui negative button",
      rel:"delete",
      text:"Delete"
    }
  );
  a.onclick = httpDelete;
  domHelp.push(a3,buttons);
}

The next important snippet in the items() routine is the one that handles any item-level links. In the code you can see () that, if there are links for this item, each link is checked to see if it should be rendered as an image () and, if not, if it can be rendered as a navigational link (). Finally, after the links are processed, the results are added to the item display ():

if(item.links) { 
  for(var link of item.links) {
    // render as images, if asked
    if(isImage(link)===true) { 
      p = domHelp.node("p");
      p.className = "ui basic button";
      img = domHelp.image(
        {
          className:"image "+link.rel,
          rel:link.rel,
          href:link.href
        }
      );
      domHelp.push(img, p, buttons);
    }
    else {
      a = domHelp.anchor( 
        {
          className:"ui basic blue button",
          href:link.href,
          rel:link.rel,
          text:link.prompt
        }
      );
      a.onclick = httpGet;
      domHelp.push(a,buttons);
    }
  }
  domHelp.push(buttons,segment); 
}

The last snippet to review in the items() routine is the one that handles all the actual data properties of the item. In this client, they are rendered one by one as part of a UI table display. As you can see, the code is not very complicated:

for(var data of item.data) {
  if(data.display==="true") {
    tr = domHelp.data_row(
      {
        className:"item "+data.name,
        text:data.prompt+" ",
        value:data.value+" "
      }
    );
    domHelp.push(tr,table);
  }
}

That’s all for the items() routine. Figure 8-3 is an example of the generated UI for Cj items.

Figure 8-3. Generated Cj items

Next up is the routine that handles the queries element of the Cj document.

Queries

The queries() routine processes all the elements in the Cj queries collection and turns them into HTML GET forms. The code is not very complex, but it is a bit verbose. It takes quite a few lines to generate an HTML form! The code our Cj client uses for generating the UI for Cj queries follows:

// handle query collection
function queries() {
  var elm, coll;
  var segment;
  var form, fs, header, p, lbl, inp;

  elm = domHelp.find("queries");
  domHelp.clear(elm);
  if(global.cj.collection.queries) { 
    coll = global.cj.collection.queries;
    for(var query of coll) { 
      segment = domHelp.node("div");
      segment.className = "ui segment";
      form = domHelp.node("form"); 
      form.action = query.href;
      form.className = query.rel;
      form.method = "get";
      form.onsubmit = httpQuery;
      fs = domHelp.node("div");
      fs.className = "ui form";
      header = domHelp.node("div");
      header.innerHTML = query.prompt + " ";
      header.className = "ui dividing header";
      domHelp.push(header,fs);
      for(var data of query.data) { 
        p = domHelp.input({prompt:data.prompt,name:data.name,value:data.value});
        domHelp.push(p,fs);
      }
      p = domHelp.node("p"); 
      inp = domHelp.node("input");
      inp.type = "submit";
      inp.className = "ui mini submit button";
      domHelp.push(inp,p,fs,form,segement,elm); 
    }
  }
}

The queries routine has just a few interesting points to cover:

First, see if there are any queries in this response to process.

If so, loop through each of them to build up a query form.

Create the HTML <form> element and populate it with the proper details.

Walk through each data element to create the HTML <inputs> that are needed.

Then add the submit button to the form.

Finally, add the resulting markup to the UI for rendering on the page.

That’s how the Cj client handles generating all the safe query forms (e.g., HTTP GET). There are a few parts that deal with the HTML layout that are left out here, but you can see the important aspects of the queries() routine. Figure 8-4 shows an example of the generated query forms in our Cj client app.

Figure 8-4. The generated Cj query forms

Template

Just as Cj queries describe safe actions (e.g., HTTP GET), the Cj template describes the unsafe actions (e.g., HTTP POST and PUT). The code looks very similar to the code for generating Cj queries:

// handle template object
function template() {
  var elm, coll;
  var form, fs, header, p, lbl, inp;

  elm = domHelp.find("template");
  domHelp.clear(elm);
  if(hasTemplate(global.cj.collection)===true) { 
    coll = global.cj.collection.template.data;
    form = domHelp.node("form"); 
    form.action = global.cj.collection.href;
    form.method = "post";
    form.className = "add";
    form.onsubmit = httpPost;
    fs = domHelp.node("div");
    fs.className = "ui form";
    header = domHelp.node("div");
    header.className = "ui dividing header";
    header.innerHTML = global.cj.collection.template.prompt||"Add";
    domHelp.push(header,fs);
    for(var data of coll) { 
      p = domHelp.input(
        {
          prompt:data.prompt+" ",
          name:data.name,
          value:data.value,
          required:data.required,
          readOnly:data.readOnly,
          pattern:data.pattern
        }
      );
      domHelp.push(p,fs);
    }
    p = domHelp.node("p"); 
    inp = domHelp.node("input");
    inp.className = "ui positive mini submit button";
    inp.type = "submit";
    d.push(inp,p,fs,form,elm); 
  }
}

Here are the highlights for the template routine:

Confirm there is a template element in the loaded Cj document.

If there is, start building and populating an HTML <form>.

Using the template’s data properties, create one or more HTML <input> elements.

After all the inputs are created, add an HTML submit button.

Finally, add the completed HTML form to the UI.

You will also notice in the preceding code that the HTML <form> element is set to use the POST method. This takes care of the create use case for Cj template. For the update use case, there is a shadow routine in the Cj client called cjEdit(). This is invoked when the user presses the Edit button generated for each item. I won’t review the code for cjEdit() here (you can check out the source yourself) but will just mention that it looks almost identical except for a few changes related to the HTTP PUT use case.

Figure 8-5 is an example of the Cj template rendered for the create use case.

Figure 8-5. Generating the Cj create UI

The only code left to review for the Cj client is the code that handles any error elements in the response.

Error

Cj is the only hypermedia design featured in this book that has built-in support for sending domain-specific error information. The Cj error element is very simple. It has only four properties: title, message, code, and url. So the client routine for rendering errors is simple, too.

The following code shows that the Cj client app just echoes the properties of the error element in Cj responses directly to the screen:

// handle error object
function error() {
  var elm, obj;

  elm = domHelp.find("error");
  domHelp.clear(elm);
  if(global.cj.collection.error) {
    obj = global.cj.collection.error;

    p = d.para({className:"title",text:obj.title});
    domHelp.push(p,elm);

    p = d.para({className:"message",text:obj.message});
    domHelp.push(p,elm);

    p = d.para({className:"code",text:obj.code});
    domHelp.push(p,elm);

    p = d.para({className:"url",text:obj.url});
    domHelp.push(p,elm);
  }
}

Quick Summary

The Cj client differs from the HAL and Siren clients reviewed earlier in the book in a number of respects, most significantly in the way domain objects are handled in Cj. Instead of just echoing a set of name–value pairs or even a nested JSON object graph, Collection+JSON only supports returning flat lists of items. Each item represents more than just a domain object’s properties. It also includes metadata about the domain object (prompt and render information) and a collection of one or more link elements associated with the domain object.

The way safe and unsafe actions are expressed in Cj is also unique. Instead of leaving it up to source code (as in HAL) or relying on a general model for all actions (as in Siren), the Cj design supports two different action elements: the queries and template elements. Cj queries are for safe actions (e.g., HTML GET) and the template is for unafe actions (e.g., HTTP POST and PUT).

The other main element in Cj documents is the links collection, which is very similar to the way both HAL and Siren express links, too.

Now that we have a fully functional Cj general client, let’s introduce some modifications to the backend TPS API and see how it deals with backward-compatible changes.

Adding the Note Object to the TPS API

Let’s assume that the TPS team decides to add support for attaching comments or Notes to Task records in the TPS API. That means defining a Note object’s fields and adding support for the basic CRUD operations on Note objects along with some other NOTE-specific actions like filters, etc.

In this section, I’ll review the API design elements (internal Note object and public API) and the resulting WeSTL document, and take a look at a bit of the server code. Then, after completing the backend changes, we’ll fire up the Cj client and see what happens.

  props = ["id","title","text","assignedTask","dateCreated","dateUpdated"]; 
  elm = 'note';

  // shared profile info for this object 
  profile = {
    "id" : {"prompt" : "ID", "display" : true},
    "title" : {"prompt" : "Title", "display" : true},
    "text" : {"prompt" : "Text", "display" : true},
    "assignedTask" : {"prompt" : "Assigned Task", "display" : true},
    "dateCreated" :  {"prompt" : "Created", "display" : false},
    "dateUpdated" :  {"prompt" : "Updated", "display" : false}
  };

function addNote(elm, note, props) {
  var rtn, item, error;

  error = "";

  item = {} 
  item.title = (note.title||"");
  item.text = (note.text||"");
  item.assignedTask = (note.assignedTask||"");

  if(item.title === "") { 
    error += "Missing Title ";
  }
  if(item.assignedTask==="") {
    error += "Missing Assigned Task ";
  }
  if(component.task('exists', item.assignedTask)===false) { 
    error += "Task ID not found. ";
  }

  if(error.length!==0) {
    rtn = utils.exception(error);
  }
  else {
    storage(elm, 'add', utils.setProps(item,props)); 
  }

  return rtn;
}

  // add task 
  trans.push({
    name : "noteFormAdd",
    type : "unsafe",
    action : "append",
    kind : "note",
    target : "list add hal siren cj-template",
    prompt : "Add Note",
    inputs : [
      {name : "title", prompt : "Title", required : true},
      {name : "assignedTask", prompt : "Assigned Task", required : true},
      {name : "text", prompt : "Text"}
    ]
  });

  ...

  trans.push({ 
    name : "noteAssignLink",
    type : "safe",
    action : "read",
    kind : "note",
    target : "item cj read",
    prompt : "Assign Task",
  });
  trans.push({ 
    name : "noteAssignForm",
    type : "unsafe",
    action : "append",
    kind : "note",
    target : "item assign edit post form hal siren cj-template",
    prompt : "Assign Task",
    inputs : [
      {name: "id", prompt:"ID", readOnly:true, required:true},
      {name: "assignedTask", prompt:"Task ID", value:"", required : true}
    ]
  });

// add the item-level link
wstl.append({name:"noteAssignLink",href:"/note/assign/{id}",
  rel:["edit-form","/rels/noteAssignTask"],root:root},coll);

// add the assign-page template
wstl.append({name:"noteFormAdd",href:"/note/",
  rel:["create-form","/rels/noteAdd"],root:root},coll);

case 'GET':
  if(flag===false && parts[1]==="assign" && parts[2]) {
    flag=true;
    sendAssignPage(req, res, respond, parts[2]);
  }

case 'POST':
  if(parts[1] && parts[1].indexOf('?')===-1) {
    switch(parts[1].toLowerCase()) {
      case "assign":
        assignTask(req, res, respond, parts[2]);
      break;
    }
  }

Testing the note API with the existing Cj client

In a real-life scenario, the TPS API would be updated into production without prior warning to all the existing Cj clients. Then at some point, one of the clients might make an initial request to the TPS API, just as in previous days, and automatically see the new Notes option at the top of the page (see Figure 8-6).

Figure 8-6. New Notes option in the Cj client

When the user clicks on the Notes link, the fully populated interface comes up with all the display and input constraints enforced. Along with the expected Read, Edit, and Delete buttons for each item plus the Add Note form, users will also see (in Figure 8-7) the special Assign Task link that appears for each Note in the list.

Figure 8-7. The Notes page in the Cj client

Finally, clicking the Assign Task button will bring up the screen that prompts users to enter the id value of the Task to which this note should be attached (see Figure 8-8).

Figure 8-8. Assigning a Note to a Task

So, the existing Cj client was able to support all the new API functionality (the new Object, Addresses, and Actions) without any new coding or configuration. At this point, the TPS web API team has quite a bit of freedom to modify the existing production API. As long as the changes are backward-compatible, not only will the Cj client not break when new changes appear, but the new changes will be fully supported (not just safely ignored) for now and into the future.

Cj and the OAA Challenge

The OAA Challenge tests whether the format was designed to support dynamically changing the API’s Objects, Addresses, and Actions and have a standard client application automatically adapt to those changes at run time without the need for any custom coding. The Collection+JSON format is the only format we’ve covered in this book that was designed to meet the OAA Challenge without the need for private extensions or customization of the format.

That means that web APIs that can output responses in Cj can assume that there is a client that is able to adapt to changes in things like:

• Adding new links and forms

• Changing the URLs of existing links and forms

• Changing the input rules for forms

• Adding new resource objects

• Changing the rules on whether users can edit or delete resource objects

This gives API providers a wide range of choices for updating existing APIs without breaking any client apps using that same API. And that means client app developers do not have to constantly monitor the change notices from a service provider in order to head off a fatal crash or unexpected loss of functionality.

There are trade-offs for this ability to adapt, too. The standard Cj client applications lose some aspect of control—they end up showing the UI that the API wants them to see, they follow the workflow provided by the API, and they show the links and forms the API thinks are important. The layout is even controlled, to some extent, by the API provider. These can be hard things to accept for those who spend most of their time crafting pixel-perfect bespoke user interfaces for web APIs.

However, there is room here for both API provider and client developer to each take control of the things that matter. If client-side developers decide they want full control of the user experience, Cj client apps can be crafted to continue to ignore new functionality. Some of the techniques for making this possible were covered in “Client Implementors”. And, as long as API providers follow the rules outlined in “Server Implementors”, client apps will not experience unexpected breakage even if they ignore the providers’ new features.

Quick Summary

So, working with Cj is pretty nice. But things are not perfect with our Cj client. As you might have noticed on those last couple screens, entering the text of a note is a problem—the text box is too small. It should be rendered as an HTML <textarea> control to support longer text entry and even scroll bars. Even more problematic is the Assign Task data entry. There, users are expected to supply two rather opaque record identifiers (NoteID and TaskID) in order to complete the Assign Task action. That’s not very user-friendly and it is likely to be rejected by any team responsible for building quality user experiences.

To fix this shortcoming, we’ll need to extend the Cj design to do a better job of describing (and supporting) user-friendly input experiences. There are lots of options for improvement and I’ll just focus on two of them for now: (1) improving client-side support for input types, and (2) supporting a drop-down or suggested list of possible values for input.

Supporting Improved Input with Cj-Types

Adding support for HTML5-style input types (e.g., email, number, url, etc.) is a pretty simple extension for Cj. It’s just a matter of adding the type property to the Cj output and honoring it on the client side. There are also a series of associated properties like min, max, size, maxlength, etc. that should also be supported.

The Cj media type has an option for adding backward-compatible extensions to allow new features to emerge without the need for advanced approval and modification of the media type specification itself.

"template": {
  "prompt": "Add User",
  "rel": "create-form userAdd create-form",00
  "data": [
    {"name": "nick","value": "","prompt": "Nickname","type": "text",
      "required": "true","pattern": "[a-zA-Z0-9]+"}, 
    {"name": "email","value": "","prompt": "Email","type": "email"}, 
    {"name": "name","value": "","prompt": "Full Name","type": "text",
        "required": "true"},
    {"name": "password","value": "","prompt": "Password","type":"text",
        "required": "true","pattern": "[a-zA-Z0-9!@#$%^&*-]+"} 
  ]
}

"template": {
  "prompt": "Add Note",
  "rel": "create-form //localhost:8181/rels/noteAdd",
  "data": [
    {"name": "title","value": "","prompt": "Title",
      "type": "text","required": "true"},
    {"name": "assignedTask","value": "","prompt": "Assigned Task",
      "type": "text","required": "true"},
    {"name": "text","value": "","prompt": "Text",
      "type": "area","cols": 40,"rows": 5} 
  ]
}

// emit data elements
data = [];
for(j=0,y=temp.inputs.length;j<y;j++) {
  d = temp.inputs[j];
  field = {
    name:d.name||"input"+j,
    value:(isAdd===true?d.value:g.tvars[d.name])||"",
    prompt:d.prompt||d.name,
    type:d.type||"text" 
  };
  if(d.required){field.required=d.required.toString();} 
  if(d.readOnly){field.readOnly=d.readOnly.toString();}
  if(d.pattern){field.pattern=d.pattern;}
  if(d.min){field.min=d.min;}
  if(d.max){field.max=d.max;}
  if(d.maxlength){field.maxlength=d.maxlength;}
  if(d.size){field.size=d.size;}
  if(d.step){field.step=d.step;}
  if(d.cols){field.cols=d.cols;}
  if(d.rows){field.rows=d.rows;}
  data.push(field);
}