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
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
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
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
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).