Skip to content

Latest commit

 

History

History
37 lines (21 loc) · 4.05 KB

cold_user_interface.md

File metadata and controls

37 lines (21 loc) · 4.05 KB
title
COLD User Interface

COLD User Interface

COLD application can be thought of as a composit of parts. Dataset provides a JSON API at the backend for storing objects. What about the front end? The user interface itself can be thought of as the communication between the web service and the browser. On the web service side the path structures can be broken into two groups. Paths that result in HTML, CSS and JavaScript delivered to the browser and those which delivery data encoded as JSON. On the traditional content delivery side correspond to the objects they are managing.

  • /people
  • /groups

These two paths result is lists of objects of either type groups or people. Going a step further you can add an identifier to get to individual objects. For people this could be providing the value of the Caltech Library people identifier, "clpid". For groups it is providing the Caltech Library group identifier, "clgid". This is results in the path of the form

  • /people/<clpid>
  • /groups/<clgid>

For JSON data delivery you have a similar organization but the path uses a prefix of /api. You can get back the list of people and groups using the following paths.

  • /api/people
  • /api/groups

But unlike our content paths the API expect a query name as the next element in the paths. The query names are defined in the "cold_api.yaml" file and are used to retrieve data back from the Dataset JSON API service. In the cold web service code proxies to the permissable paths. Additional the "api" paths only support reading data needed for implementing the user interface in the browser itself.

UI implementations

The human user interface implemented in COLD is composed from HTML, CSS and JavaScript. HTML provides structure, CSS styling and layout while JavaScript is used to implement behaviors. A behavior could be as similar as validating the content of a field beyond that provided for by HTML 5 form elements (e.g. beyond simple regexp). The rendering capability in the cold web service provided populated forms where input is needed. However in cases of complex fields like a list of group names more is required. Before your save a record you want to know if the field values are correct. To support this requirement the "api" paths are provided and accessed by browser side JavaScript hosted in "htdocs/modules"1 directories.

The COLD project uses TypeScript as its primary programming language for implementation. It uses JSON and sometimes YAML for data representation. The Deno runtime provides a solid, safe, platform for running code server side. TypeScript though does not run natively in the browser. Where does the JavaScript come from? The COLD build process, deno task build, will transpile the TypeScript used by the web browser into JavaScript and write the resulting module to "htdocs/modules" directory. This ensure that code can be easily and reliably shared between the web services and web browser.

Inline JavaScript can be used to initialize module objects in a web page when needed. Inline code is implemented in the Handlebars "view" for the page (e.g. "views/people_edit.hbs"). While inline code is quick it and allows for configuration passed via the page template if the script element gains any level of complexity it becomes a maintenance burden. A separate file is more appropriate in this case. The "htdocs/js" directory is used for hand written JavaScript files which do not require transpiling from TypeScript.

mdt.js

cold use the Metadata Tools project for validate various identifiers. While the JavaScript module isn't generated by the cold build process the metadata tools project produces the "mdt.js" file as an ES6 module. It can be copied directly from the metadata tools repository and placed in "htdocs/modules/" along side the cold TypeScript modules that get transpiled to JavaScript. It should not be modified directly and bugs or change requests should go through the Metadata Tools project issues process.

Footnotes

  1. COLD project is implemented as a collection of ES6 Modules ↩