Step 1: Define UX Data

Working backwards from the client to the server, the first question we ask ourselves is "what information will I need to have in order to render a comprehensive summary of any given software package?"

We're not sure. But that's okay; the important thing is to capture the inspiration of the feature idea and get the pattern locked into place. Then, it can be easily refined.

So we go into the polytely/sources/common/iospecs/view directory and create a new JavaScript module called content-view-render-software-package-datasheet-spec.js. This module will be a filter spec that specifies the format of whatever JSON we decide is appropriate to describe our software packages.

Step 2: Define UX Component

Now that we have a basic idea of the data that we're going to display as HTML in the UX, we next move to the polytely/sources/view/elements/content folder and create a new JSX module for a new React component, HolisticSoftwarePackageOverview.jsx that will be responsible for converting messages of the format specified in step #1 into HTML.

Again we don't care too much about the details of the implementation of the React component here because it's pretty standard.

Step 3: Register The Association

Above holism, in code that currently resides in the polytely repository we define a so-called ContentRouter React component that's a little odd; it uses the spread operator to suck in whatever is passed to it uses a generic data feature extraction algorithm and an in-memory database of the known message formats to route messages to an appropriate React component for rendering.

This arrangement allows for us to add new content types into our display theme without having to alter any of the React components that reside above it in the render hierarchy; they just don't care because they can simply dish off whatever data they don't know how to deal with to the ContentRouter and it will end up in the DOM. Sometimes this is a <PRE/> of the raw JSON and an error message. But that's okay because you know what's going on without having to re-stage the test under the debugger and waste half an hour confirming the same information.

So we drop into the polytely/sources/common/view/elements/content-router directory and add an entry to index.js associating the filter spec from step #1 with the React component from step #2. The HTML rendering subsystem of our application server is now extended to render any data of format #1 via React component #2 that is produced as a result of a holism service filter.

Step 4: Create a new Service Filter

The holism application server is primary extended via specially constructed filter objects called services.

In our example, we have to this point extended the HTML render subsystem of our application server to handle "software package datasheets". What we now need is a way to read the datasheet JSON from the local filesystem (for now) and send it to the application server's HTML render subsystem.

This is a simple job for a holism service filter.

We drop into polytely/sources/server/services and create a new JavaScript module called software-package-datasheet-reader-filter.js.

In essence this is merely a JavaScript function that will be called by holism and passed a bunch of information with some prescriptive expectations about how the result (or error) produced by whatever operation(s) the service performs are reported back to the application server's message routing layer.

In this case it's pretty simple, we don't need any information from the client for this simple test so we disable the service's ability to accept URL-encoded query options, and parse any body data a client might send along with its request.

What we will need to know is where (and eventually how) to get the actual datasheet JSON data. For this, we'll just leverage the static registration options feature of holism services and define a simple options object on our filter that accepts a local filesystem path where the JSON is presumed to be.

The implementation is a bit verbose but the basic pattern is simple; read the file, parse the JSON, if successful call the result filter passed with the initial call from holism specifying the file contents as the response data.

This transfers the actual software package datasheet data back down to the holism message routing layer that routes the response through the extended HTML rendering subsystem.

Once working, this service can be registered on potentially many different holism routes specifying different package datasheets via options.

So let's try it.

Step 5: Register The Service

Now we have created a holism service filter to read software package datasheet JSON from local filesystem and return the deserialized JSON content back to the holism application server's message routing layer for further processing.

Note that our service filter specifies that the desired response encoding/type should be utf8/text/html but it has no idea how to render HTML.

Holism however does because it requires your application to register integration filter and it knows that if it sees data and the response target is utf8/test/html that it should delegate to the application's registered HTML render subsystem to transform that data into an HTML-encoded string.

So... we drop into polytely/sources/services/config and add an entry to service-filters.js and add an object that registers our service from step #4 on a route /test specifying a local software package datasheet JSON file polytely/docs/test-package-descriptor.js

We're now live-end-to-end and can make changes to our test JSON file, our React render component, and the filter spec that associates them to refine the specification of the information required, and ensure that it is presented nicely.

In part #2 we'll dig into this more and explain how we plan to generalize the software package datasheet filter spec and the React component to handle hierarchical packages w/sub-packages (e.g. ARCcore).