Saturday, August 20, 2022

The iPhora Journey - Part 5 - Dammit Jim, I'm a LotusScripter not a JavaScripter

As often said by Dr. McCoy in the original Star Trek series, he is a doctor, not a ____________ .  However, just like Dr. McCoy, you may sometimes need to work on things that seem very alien to your experience.  One of those things, might be JSON. LotusScript, which was derived from Visual Basic, was written long before JSON existed, and therefore, LotusScript had no built-in capabilities for handling JSON objects.

As we mentioned in Part 4, JSON plays a critical role in iPhora.  All data are stored as JSON, and JSON serves as the primary data and communication format between modules, functions and services.  All core components operate using JSON-based configurations.  Therefore, it was extremely important that we are able to fluidity create, read and process JSON.  

Creating a JSON string is relatively easy in any programming language. You can create it even using Commodore 64 Basic, and if built sequentially, one line at a time, it is possible to create JSON representations of very complex objects. The string manipulation capabilities of LotusScript are more than adequate to build large JSON objects in this way. Reading a JSON String can also be accomplished utilizing the same set of LotusScript string functions, but it then requires a significant amount of filtering and manipulation to locate and retrieve the data you are looking for. The task becomes more and more difficult as the JSON becomes larger and more complex.

Starting with HCL Domino 10, LotusScript provided some basic components to read and assemble JSON known as the NotesJSONNavigator class, and this was a major improvement.  This effectively replaced the tedious process of string manipulation and treated JSON as objects for reading and writing. However, beyond the simple objects and arrays it was designed to handle, the tools provided within LotusScript are still very limited, especially compared to JavaScript.

As JavaScript developers, we wanted the LotusScript JSON parser to reflect the JSON processing functionality that was found in JavaScript. Since we had lots of experience manipulating JSON on the front-end (using JavaScript), that set our expectations for what was needed on the back-end. We modeled our approach on JavaScript, and that determined the methods that we had to implement in LotusScript.  After many years and many versions, we finally came up with the Flex JSON Parser.

So why did we call it the Flex JSON Parser? Because it was more flexible than our many other attempts in creating a JSON parser. Below is a comparison of the functions between JavaScript and the Flex JSON Parser. Note that spec is simply a string that uses dot notation to refer to a specific JSON object, array, or keyname, regardless of how many levels down it might be, for example, it could be "[0][25].grass.type"

JavaScript Flex Parser
Create a JSON Array
var a = []; or set a = new JSON(10)
var a = JSON.parser("[]"); Call a.parse(|[]|)

Create a JSON Object
var a = {}; or set a = new JSON(10)
var a = JSON.parser("{}"); Call a.parse(|{}|)

Convert JSON Object to JSON String
var b = JSON.stringify(obj); b = obj.stringify()

Enumberate an Object
Object.keys( obj ); obj.getKeys(spec)

Push Array
objs.push( obj ) objs.push( spec , obj )

Push Apply Arrays to Arrays
objs.push.apply(objs, bObjs ) objs.pushapply( spec , bObjs )

Length of Array
objs.length; objs.getCount(spec)

Get Value of Key
var a = obj["hello"]; a = obj.getValue("hello")

Set Value of Key
obj["hello"] = a; obj.setValue("hello", a)

We also adopted some methods that we utilize from the Dojo Toolkit Framework
lang.mixin( aObj , bObj) aObj.mixin(bObj )

But the extremely important methods that allow for significant processing of JSON for the Flex JSON Parser are:

set obj = objs.getElement( spec )
Call objs.setElement( spec , obj )
index = objs.getIndexByKeyValue(spec, key , value)

These functions allow us to extract JSON objects from larger JSON objects and then to insert them into specific locations within other JSON objects.

With the Flex JSON Parser we can manipulate and process JSON objects that include a mix of objects and arrays at any level. It gave us the processing capabilities that defined how iPhora works and opened up new approaches that we once assumed were not possible in LotusScript. So a LotusScript developer can now process JSON like a JavaScript developer.

Watch a comparison between JavaScript and the Flex JSON Parser in action

No comments:

CollabSphere 2022 Presentation: COL103 Advanced Automation and Cloud Service Integration for your Notes/Nomad Applications

Our presentation for CollabSphere 2022. Learn how to quickly add workflow automation into Notes/Nomad applications using No-code tools that ...