cold/cold_user_interface.html at main · caltechlibrary/cold · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
<!DOCTYPE html>
<html lang="en-US">
<head>
    <title>cold</title>
    <link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
    <link rel="stylesheet" href="https://media.library.caltech.edu/cl-webcomponents/css/code-blocks.css">
    <script type="module" src="https://media.library.caltech.edu/cl-webcomponents/copyToClipboard.js"></script>
    <script type="module" src="https://media.library.caltech.edu/cl-webcomponents/footer-global.js"></script>
</head>
<body>
<header>
<a href="https://library.caltech.edu"><img src="https://media.library.caltech.edu/assets/caltechlibrary-logo.png" alt="Caltech Library logo"></a>
</header>
<nav>
<ul>
    <li><a href="/">Home</a></li>
    <li><a href="index.html">README</a></li>
    <li><a href="LICENSE">LICENSE</a></li>
    <li><a href="INSTALL.html">INSTALL</a></li>
    <li><a href="user_manual.html">User Manual</a></li>
    <li><a href="about.html">About</a></li>
    <li><a href="search.html">Search</a></li>
    <li><a href="https://github.com/caltechlibrary/cold">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="cold-user-interface">COLD User Interface</h1>
<p>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.</p>
<ul>
<li><code>/people</code></li>
<li><code>/groups</code></li>
</ul>
<p>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</p>
<ul>
<li><code>/people/&lt;clpid&gt;</code></li>
<li><code>/groups/&lt;clgid&gt;</code></li>
</ul>
<p>For JSON data delivery you have a similar organization but the path
uses a prefix of <code>/api</code>. You can get back the list of people
and groups using the following paths.</p>
<ul>
<li><code>/api/people</code></li>
<li><code>/api/groups</code></li>
</ul>
<p>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.</p>
<h2 id="ui-implementations">UI implementations</h2>
<p>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”<a href="#fn1" class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a> directories.</p>
<p>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,
<code>deno task build</code>, 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.</p>
<p>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.</p>
<h3 id="mdt.js">mdt.js</h3>
<p><strong>cold</strong> use the <a
href="https://github.com/caltechlibrary/metadatatools">Metadata
Tools</a> project for validate various identifiers. While the JavaScript
module isn’t generated by the <strong>cold</strong> 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 <strong>cold</strong> 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.</p>
<section id="footnotes" class="footnotes footnotes-end-of-document"
role="doc-endnotes">
<hr />
<ol>
<li id="fn1"><p>COLD project is implemented as a collection of ES6
Modules<a href="#fnref1" class="footnote-back"
role="doc-backlink">↩︎</a></p></li>
</ol>
</section>
</section>
<footer-global></footer-global>
</body>
</html>