Hypermedia
Richly Typed Hypermedia
Consider the proposed output of a WebTerminal command like ls
(discussed in Structured Data):
[
{
name: path::"a.txt",
type: filetype::"file",
size: bytes::1234,
modified: 2001-01-01T
},
{
name: path::"b.txt",
type: filetype::"file",
size: bytes::4567,
modified: 2002-02-02T
}, // ...
]
We’d like to display this data to the user as an HTML table, with contents like:
name | type | size | modified |
---|---|---|---|
a.txt |
file | 1 KiB | 3 years ago |
b.txt |
file | 4 KiB | 2 years ago |
d |
directory | 8 KiB | 1 year ago |
Data Formats
File Paths
In the WebTerminal environment, strings with the path::
annotation represent files on disk.
By employing this annotation, programs can unambiguously express file names in their output;
and the WebTerminal UI will react to it and provide an intelligent experience.
When rendering a value like path::"foo.txt"
for display as HTML, WebTerminal might
employ data-*
microformats to capture the file’s absolute path, and/or the
current working directory when the path was produced as output.
For example, if the user’s current working directory is /users/alice
, and a program
produces a filename as output like path::"foo.txt"
, then WebTerminal might render this in HTML as:
<span class="path"
data-cwd="/users/alice/"
data-abs-path="/users/alice/foo.txt">
foo.txt
</span>
The element has a unique class="path"
which is applied to path::
values. It also has an
element data-cwd=
capturing the current working directory when the path was produced,
as well as a data-abs-path=
capturing the file’s absolute path.
Since files are displayed with class="path"
, the UI can intelligently style the element
and display actions relevant to files, such as:
- Copy as relative path (
./foo.txt
) - Copy as absolute path (
/users/alice/foo.txt
) - Open the file using
$EDITOR
- Navigate to the file
- An extended mouse-over of the file name might display a brief preview of the file contents
Even if the user changes their working directory, these functions will still operate correctly.
File Size
WebTerminal will take advantage of the bytes
annotation on file sizes, e.g. size: bytes::1048576
, to display the value in a human-readable way.
For example, when a program outputs a value like size: bytes::1048576
, then WebTerminal might render it as the human-readable 1 MiB
using the following HTML:
<span class="size"
data-raw="1048576">
1 MiB
</span>
This HTML element displays the human-formatted 1 MiB
, but also contains the raw value 1048576
.
When the user clicks on the element, then the UI might present an option to copy the raw value as well.
Timestamps
Ion directly provides a timestamp
type, so whenever a program displays time outputs, WebTerminal can display them intelligently.
For example, a timestamp value like 2022-01-01T18:00:00Z
might display as 1 year ago
.
<time class="modified-time"
datetime="2022-01-01T18:00:00Z>
1 year ago
>
Similarly to file sizes, clicking on the value will allow the user to copy the raw timestamp value to the clipboard.
Customizable Hypermedia Content and Style
Since WebTerminal employs typed and tagged output formats, the standard terminal environment can render stylized output using CSS in ways that are most useful to the user. Additionally, the user might customize their environment by supplying their own CSS style sheets. For example, the user might style the HTML elements described above:
.path {
color: blue;
cursor: pointer;
}
.path:hover {
text-decoration: underline;
}
.size {
font-weight: bold;
}
.modified-time {
color: grey;
}