README.md 17 KB
Newer Older
1
# TIDO
Mathias Goebel's avatar
Mathias Goebel committed
2

3
Text vIewer for Digital Objects.
Mathias Goebel's avatar
Mathias Goebel committed
4

5
**Note:**
6
Although TIDO is designed as a generic viewer for digital editions, it is currently developed within the scope of the [Ahiqar project](https://gitlab.gwdg.de/subugoe/ahiqar).
nwindis's avatar
nwindis committed
7

8
9
This is the reason for "Ahiqar" being mentioned several times in the docs of this repo.

nwindis's avatar
nwindis committed
10
Demo: <https://subugoe.pages.gwdg.de/emo/tido/develop>
Nils Windisch's avatar
MINOR    
Nils Windisch committed
11

12
13
(For newer branches the demo is deployed in a directory named with branch name lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-` (CI_COMMIT_REF_SLUG).
Also the commit short hash can be used to see a demo.
mrodzis's avatar
mrodzis committed
14

nwindis's avatar
nwindis committed
15
## Overview
16
17
18
19

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

20
- [Latest Version and Integration](#latest-version-and-integration)
Mathias Goebel's avatar
Mathias Goebel committed
21
  - [Get the Viewer](#get-the-viewer)
22
23
24
    - [Registry setup](#registry-setup)
    - [Installation](#installation)
  - [Integration](#integration)
Mathias Goebel's avatar
Mathias Goebel committed
25
  - [Config](#config)
26
- [Getting Started (Developers)](#getting-started-developers)
27
  - [Prerequisites](#prerequisites)
28
  - [Environment setup](#environment-setup)
schneider210's avatar
schneider210 committed
29
30
31
32
    - [Set up `nvm` and the recent stable version of `node.js`](#set-up-nvm-and-the-recent-stable-version-of-nodejs)
    - [Set up `global` project requirements via `npm`](#set-up-global-project-requirements-via-npm)
    - [Clone the repository](#clone-the-repository)
    - [Get the dependencies](#get-the-dependencies)
33
34
  - [Usage](#usage)
    - [`development mode` (hot reloading, error reporting, etc.)](#development-mode-hot-reloading-error-reporting-etc)
schneider210's avatar
schneider210 committed
35
36
    - [`Linting`](#linting)
    - [`Testing`](#testing)
37
38
    - [`Building` the app for production](#building-the-app-for-production)
- [Configuration](#configuration)
39
40
  - [The Keys in Detail](#the-keys-in-detail)
  - [Configure the Panels](#configure-the-panels)
41
    - [The Panel Keys in Detail](#the-panel-keys-in-detail)
Mathias Goebel's avatar
Mathias Goebel committed
42
- [Viewer Architecture](#viewer-architecture)
43
44
- [Dockerfile](#dockerfile)
- [Connecting the Viewer to a Backend](#connecting-the-viewer-to-a-backend)
schneider210's avatar
schneider210 committed
45
- [Architecture](#architecture)
46
47
48
49
50
51
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Authors](#authors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

52
## Latest Version and Integration
53

Mathias Goebel's avatar
Mathias Goebel committed
54
TiDO is provided as **npm package**. Please follow the steps below to include it for production:
schneider210's avatar
schneider210 committed
55

Mathias Goebel's avatar
Mathias Goebel committed
56
### Get the Viewer
57
58
59

#### Registry setup

Mathias Goebel's avatar
Mathias Goebel committed
60
Since npm communicates with the package API, it is necessary to setup a valid endpoint.
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

```bash
echo @subugoe:registry=https://gitlab.gwdg.de/api/v4/packages/npm/ >>.npmrc
```

**Note**: fire this command inside the **root** of your **project directory**.

#### Installation

```bash
npm i @subugoe/tido
```

### Integration

Mathias Goebel's avatar
Mathias Goebel committed
76
Add this line to your **main.js** file:
77
78
79
80
81
82
83

```js
import '@subugoe/tido/dist/tido'
```

**Note**: `main.js` serves as your *entrypoint* usually located at **/[projectdir]/src/main.js**. It depends on your individual project setup.

Mathias Goebel's avatar
Mathias Goebel committed
84
### Config
schneider210's avatar
schneider210 committed
85

Mathias Goebel's avatar
Mathias Goebel committed
86
Copy the config object into your **index.html** and follow the instructions given [here](#configuration).
schneider210's avatar
schneider210 committed
87

88
**Note**: Please make sure to provide a valid *entrypoint* that points to the manifest / collection that you want to be displayed.
nwindis's avatar
nwindis committed
89

90
## Getting Started (Developers)
mrodzis's avatar
mrodzis committed
91
92
93

### Prerequisites

94
To get TIDO up and running you should have the following software installed:
mrodzis's avatar
mrodzis committed
95

96
97
98
- **curl**
- **npm**
- **nvm**
mrodzis's avatar
mrodzis committed
99

100
**Note**:
mrodzis's avatar
mrodzis committed
101

nwindis's avatar
nwindis committed
102
103
104
105
We recommend to make use of `nvm`, since there might be issues with npm regarding permissions.  
The main purpose of `nvm` is to have multiple node versions installed in regards to different projects which might demand some sort of backwards compatibility.  
It enables you to just switch to the appropriate node version.  
Besides it also keeps track of resolving permission issues, since all your global installations go to your home directory (~/.nvm/) instead of being applied systemwide.
mrodzis's avatar
mrodzis committed
106

107
### Environment setup
schneider210's avatar
schneider210 committed
108
109

#### Set up `nvm` and the recent stable version of `node.js`
mrodzis's avatar
mrodzis committed
110

111
112
113
114
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
nvm install stable
```
115

116
**Note**:
117
After the nvm installation is done, please `restart` your shell session once. That's due to changes to your profile environment.
118

schneider210's avatar
schneider210 committed
119
#### Set up `global` project requirements via `npm`
120

nwindis's avatar
nwindis committed
121
122
123
```bash
npm install -g @vue/cli @vue/cli-service-global @quasar/cli
```
124
125
126

#### Clone the repository

nwindis's avatar
nwindis committed
127
```bash
nwindis's avatar
nwindis committed
128
git clone git@gitlab.gwdg.de:subugoe/emo/tido.git
nwindis's avatar
nwindis committed
129
```
130
131
132

#### Get the dependencies

133
Head over to your project directory, where you just cloned the repository to as described above and get all the dependencies needed by typing:
134

nwindis's avatar
nwindis committed
135
136
137
138
```bash
cd /path/to/projectdir
npm install
```
139

schneider210's avatar
schneider210 committed
140
That's it. You should now be able to run the Viewer.
141

142
### Usage
Mathias Goebel's avatar
Mathias Goebel committed
143

144
#### `development mode` (hot reloading, error reporting, etc.)
145

Mathias Goebel's avatar
Mathias Goebel committed
146
```bash
147
npm run dev
Mathias Goebel's avatar
Mathias Goebel committed
148
```
149

schneider210's avatar
schneider210 committed
150
(usually located at: `localhost:8080` since this port isn't already occupied)
Nils Windisch's avatar
Nils Windisch committed
151

schneider210's avatar
schneider210 committed
152
#### `Linting`
153

Mathias Goebel's avatar
Mathias Goebel committed
154
```bash
155
156
npm run lint            # to lint all the files at once
npm run lint:js         # to lint js files only
157
npm run lint:markdown   # to lint the markdown
158
159
npm run lint:scss       # to lint the styles
npm run lint:vue        # to lint vue files only
Mathias Goebel's avatar
Mathias Goebel committed
160
161
```

schneider210's avatar
schneider210 committed
162
163
164
165
166
167
#### `Testing`

```bash
npm run test:unit
```

Mathias Goebel's avatar
Mathias Goebel committed
168
169
The Viewer uses **jest**; a JavaScript test suite.

schneider210's avatar
schneider210 committed
170
171
Tests reside under **tests/unit/specs/** and are supposed to have a file ending of either `*.test.js` or `*.spec.js`.

172
#### `Building` the app for production
173

Mathias Goebel's avatar
Mathias Goebel committed
174
```bash
175
npm run build
Mathias Goebel's avatar
Mathias Goebel committed
176
177
```

Mathias Goebel's avatar
Mathias Goebel committed
178
**Note**: The complete build is located at `/dist/`.
schneider210's avatar
schneider210 committed
179

180
## Configuration
181

182
183
The Viewer is build with **Vue.js** and **Quasar**.
If you want to change the Quasar configuration, please [refer to their respective docs](https://quasar.dev/quasar-cli/quasar-conf-js) (Configuring quasar.conf.js).
mrodzis's avatar
mrodzis committed
184

185
You can fully customize the Viewer's behaviour:
186

187
There are options to
188

189
- change the color scheme
190
- show or hide individual bars (titles, navigation, toggles)
191
192
193
- group multiple components inside a single panel
- set the order of the panels
- rename labels and / or panel headings
nwindis's avatar
nwindis committed
194
- switch project header on or off and provide descriptive strings
195
- and **more** ...
196

197
As a rule of thumb, each key with a boolean value (e.g. *true* or *false*) defaults to `true` and denotes to show the appropriate element.
198

schneider210's avatar
schneider210 committed
199
```html
200
  <script id="tido-config" type="application/json">
schneider210's avatar
schneider210 committed
201
  {
202
    "entrypoint": "https://subugoe.pages.gwdg.de/emo/backend/sampledata/collection.json",
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
      "annotations": {
        "show": true,
        "types": [
          {
            "contenttype": "Person",
            "icon": "fasUser",
            "label": "Names"
          },
          {
            "contenttype": "Place",
            "icon": "fasMapMarkerAlt",
            "label": "Places"
          },
          {
            "contenttype": "Editorial Comment",
            "icon": "fasComment",
            "label": "Comments"
          },
          {
            "contenttype": "Motif",
            "icon": "fasHighlighter",
            "label": "Motifs"
          }
        ],
        "tabs":{
          "Editorial": ["Person", "Place", "Editorial Comment"],
          "Motif": ["Motif"]
        }
      },
      "breadcrumbNavigation": {
        "show": true,
        "title_homepage_key": "title_homepage",
        "title_viewer_key": "title_viewer",
        "website": "https://ahikar.sub.uni-goettingen.de/website/"
      },
      "colors": {
        "primary": "",
        "secondary": "",
        "accent": ""
      },
      "header_section": {
        "show": true,
        "navigation": true,
        "panelheadings": true,
        "titles": true,
        "toggle": true
      },
      "labels": {
        "item": "Sheet",
        "manifest": "Manuscript"
      },
      "lang": "de-de",
      "language-switch": true,
      "meta": {
        "collection": {
          "all": true
        },
        "manifest": {
          "all": true
        },
        "item": {
          "all": true
        }
      },
      "notificationColors": {
        "info":"blue-9",
        "warning":"red-9"
      },
      "panels": [
Mathias Goebel's avatar
Mathias Goebel committed
272
        {
273
274
275
276
          "connector": [1, 2],
          "panel_label": "contentsMetadata",
          "show": true,
          "toggle": true
Mathias Goebel's avatar
Mathias Goebel committed
277
278
        },
        {
279
280
281
282
          "connector": [3],
          "panel_label": "Image",
          "show": true,
          "toggle": true
Mathias Goebel's avatar
Mathias Goebel committed
283
284
        },
        {
285
286
287
288
          "connector": [4],
          "panel_label": "Text",
          "show": true,
          "toggle": true
Mathias Goebel's avatar
Mathias Goebel committed
289
290
        },
        {
291
292
293
294
          "connector": [5],
          "panel_label": "Annotations",
          "show": true,
          "toggle": true
Mathias Goebel's avatar
Mathias Goebel committed
295
296
        }
      ],
297
      "rtl": false
298
  }  </script>
299
300
```

dindigala's avatar
dindigala committed
301
**Note**: its a *JSON* object. So if you are going to make any changes and you have to quote these (e.g. see *labels* or *colors*), please use **double quotes** only.
302

303
### The Keys in Detail
304

305
- **entrypoint**
306

nwindis's avatar
nwindis committed
307
308
  to link the viewer to a backend, the entrypoint should point to the collection you want to be displayed.
  (Further details below: [Connecting the Viewer to a Backend](#connecting-the-viewer-to-a-backend))
309

310
  **Note**: You have to provide at least a valid entrypoint (see below). Otherwise the Viewer won't show anything at all!
311

Mathias Goebel's avatar
Mathias Goebel committed
312
313
314
315
316
317
318
319
320
321
322
323
- **annotations**

  - **types**

      the types-array consists of an arbitrary number of objects, each representing an annotation type (e.g. Person, Place, Organization, ...).

      each object in turn consists of similar building blocks:

    - **content-type**

        refers to the **x-content-type** in the **API** you are using.

dindigala's avatar
dindigala committed
324
        **Note**: This content-type has to match its API-counterpart explicitely, otherwise TIDO isn't able to show the related annotations.
Mathias Goebel's avatar
Mathias Goebel committed
325
326
327
328
329
330
331
332
333

    - **icon**

        TIDO uses [Font Awesome Icons](https://fontawesome.com/). Choose an icon that fits your needs.

    - **label**

        The label of the annotation type respectively

334
335
336
337
  - **tabs**

    the tabs-object represents different types of annotations to be displayed in tabs accordingly.
    it consists of further extensible sub keys called group labels, either of it representing a single group of annotations, e.g. *editorial*, *motifs*.
dindigala's avatar
dindigala committed
338
    these labels act as your tab heading and its naming is up to your liking.
339
340
341
342
343
344
345
346
347
348

    e.g.

  ```JSON
  "tabs": {
    "First group": ["Person", "Place", "Editorial Comment"],
    "Second one": ["Motif"]
  }
  ```

dindigala's avatar
dindigala committed
349
  **Note**: The strings contained within the group label keys (e.g. *Person*, *Place*, ...) have to match its API-counterpart explicitely. Please refer to the note above (content-type).
350

351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
- **breadcrumbNavigation**

  - **show**

    defines if a project header should be shown or not.

    Defaults to `false`

  - **title_homepage_key**

    defines the string shown as first item in the breadcrumb. Shows a "Home Icon"

    Note: To change this title please navigate to "tido/src/i18n/en or tido/src/i18n/de" and find "title_homepage".

    Has to be set!

  - **title_viewer_key**

    defines the string shown as last item in the breadcrumb. Shows a "Document Icon"

    Note: To change this title please navigate to "tido/src/i18n/en or tido/src/i18n/de" and find "title_viewer".

    Has to be set!

  - **website**

    Navigates to the Home Page page on website.

379
380
- **colors**

Mathias Goebel's avatar
Mathias Goebel committed
381
  set the colors used in the frontend.
382

dindigala's avatar
dindigala committed
383
  `primary` and `accent` should be a darker tone, so that white text is visible if used as background. its the other way around with `secondary`.
384
385
386
387
388

  Hex values (like `#a1a1a1`) or color names (like `hotpink`) are fine.

  If any value is left blank (e.g. `"primary": "",`), a default color scheme will be used.

389
- **header_section**
390

Mathias Goebel's avatar
Mathias Goebel committed
391
  - **show**
nwindis's avatar
nwindis committed
392

Mathias Goebel's avatar
Mathias Goebel committed
393
394
395
      set this value to `false` if you want to completely switch off all the headerbars at once.  
      This value takes **precedence** over the other *header-keys*.  
      If it is set to `false`, the other settings for the individual bars are not taken into account.
nwindis's avatar
nwindis committed
396

Mathias Goebel's avatar
Mathias Goebel committed
397
      *(A use case might be to embed the Viewer into an existing website and you simply need more screen space)*
398

nwindis's avatar
nwindis committed
399
400
  - **navigation**

Mathias Goebel's avatar
Mathias Goebel committed
401
      set this value to `false` if you want to switch off the NavBar
nwindis's avatar
nwindis committed
402

403
404
405
406
  - **panelheadings**

    set this value to `false` if you want to switch off the panels' headings respectively

407
408
409
410
    - **titles**

    set this value to `false` if you want to switch off the Titlebar (a.k.a. breadcrumbs)  

nwindis's avatar
nwindis committed
411
412
  - **toggle**

Mathias Goebel's avatar
Mathias Goebel committed
413
      set this value to `false` if you want to switch off the ToggleBar.
nwindis's avatar
nwindis committed
414

Mathias Goebel's avatar
Mathias Goebel committed
415
      **Note**: if you turn this one off, you won't be able to toggle the panels anymore.
416

Mathias Goebel's avatar
Mathias Goebel committed
417
    All header values default to `true`
418
419
420

- **labels**

nwindis's avatar
nwindis committed
421
  - **item**:
422

Mathias Goebel's avatar
Mathias Goebel committed
423
424
425
      The label of the item respectively  
      Assuming your collection consists of letters, you'd maybe want to name it "letter" or just "sheet" for instance.  
      This change affects the captions of the navbuttons located in the headerbar and the metadata section.
426

Mathias Goebel's avatar
Mathias Goebel committed
427
      Defaults to `Sheet`
428

nwindis's avatar
nwindis committed
429
  - **manifest**:
430

Mathias Goebel's avatar
Mathias Goebel committed
431
      Same as for `item` but related to the manifest title.
schneider210's avatar
schneider210 committed
432

Mathias Goebel's avatar
Mathias Goebel committed
433
      Defaults to `Manuscript`
nwindis's avatar
nwindis committed
434

435
436
437
438
439
440
441
442
443
444
445
446
447
448
- **lang (language)**

  refers to the default language of the application.

  set the value to `de-de` if you would like to turn the viewer into "German" language by default.

  Defaults to `en-us`

- **language-switch**

  set this value to `false` if you don't want to switch the language. this setting hides the appropriate toggle.

  Defaults to `true`

449
450
451
452
453
454
- **notificationColors**

  sets the colors used in frontend to apply for icons in notification messages.

  `info` and `warning` are set to `blue-9` `red-9` respectively which can be changed according to the project requirements.

dindigala's avatar
dindigala committed
455
  There is a re-usable component called notification.vue (src/components/notification.vue) which receives the type of notification (ex: `info` or `warning`). Based on the type we send, this component searches for it and its respective icon which in turn gets displayed before the title message of Notifications.
456
457
458
459
460

  If we do not send any type, than there is no `icon` set to the notification message.

  **Note**: Can add additional types ex: `success`, `error`, `positive`, `negative`. Based on these we need to add them at the component level as well and their icons respectively.

461
- **rtl (right to left)**
nwindis's avatar
nwindis committed
462

Mathias Goebel's avatar
Mathias Goebel committed
463
    refers to the direction the text inside the text panel will be displayed.
nwindis's avatar
nwindis committed
464

Mathias Goebel's avatar
Mathias Goebel committed
465
    set the value to `true` if you want text to be displayed from right to left; e.g. Arabic.
schneider210's avatar
schneider210 committed
466

Mathias Goebel's avatar
Mathias Goebel committed
467
    Defaults to `false`
468
469

### Configure the Panels
schneider210's avatar
schneider210 committed
470

471
472
473
474
475
```json
"panels": [
  {
    "connector": [1],
    "panel_label": "Contents",
476
477
    "show": true,
    "toggle": true
478
479
480
481
  },
  {
    "connector": [3],
    "panel_label": "Image",
482
483
    "show": true,
    "toggle": true
484
485
486
487
  },
  {
    "connector": [4],
    "panel_label": "Text",
488
    "show": true,
Mathias Goebel's avatar
Mathias Goebel committed
489
    "toggle": true
490
491
492
493
  },
  {
    "connector": [2],
    "panel_label": "Metadata",
494
495
    "show": true,
    "toggle": true
496
497
  }
],
schneider210's avatar
schneider210 committed
498
499
500

```

501
The panel-array consists of four objects according to the maximum number of panels, that can be shown at once.
nwindis's avatar
nwindis committed
502

Mathias Goebel's avatar
Mathias Goebel committed
503
Each object inside that constant consists of similar keys: `connector`, `panel_label`, `show` and `toggle`.
nwindis's avatar
nwindis committed
504

505
#### The Panel Keys in Detail
nwindis's avatar
nwindis committed
506
507

- **connector**
dindigala's avatar
dindigala committed
508

509
  The numbers below reflect each component's (Text, Image, Meta, ...) id.
510

nwindis's avatar
nwindis committed
511
512
  - 1 = Treeview
  - 2 = Metadata
513
514
  - 3 = Image
  - 4 = Text
nwindis's avatar
nwindis committed
515
  - 5 = Annotations
516

517
518
519
  **Note**: These **IDs** are supposed to be **unique**, so please make sure not to repeat these!

  Example given:
520

521
522
  Assuming you want to combine the **Metadata**, **Text** and **Annotations** panels, the configuration could look like this:

Mathias Goebel's avatar
Mathias Goebel committed
523
  ```json
524
    {
Mathias Goebel's avatar
Mathias Goebel committed
525
526
527
528
      "connector": [2, 4, 5],
      "panel_label": "Meta, Text & Anno",
      "show": true,
      "toggle": true
529
530
    }
  ```
531

nwindis's avatar
nwindis committed
532
533
- **panel_label**

Mathias Goebel's avatar
Mathias Goebel committed
534
  refers to the heading in each panel's *toolbar*. To rename it, change the corresponding `label` according to your needs.
535
536

  **Note**: Please make sure to also change the name, if you are going to reorder the panels or turn them into tabs.
nwindis's avatar
nwindis committed
537
538
539
540
541

- **show**

  toggles (`show` or rather `hide`) the appropriate panel respectively

542
543
544
545
546
547
- **toggle**

  whether to show the related panel toggle or not

  Defaults to `true`.

nwindis's avatar
nwindis committed
548
**Note**:
549

Mathias Goebel's avatar
Mathias Goebel committed
550
## Viewer Architecture
551
552
553

![Viewer components](img/Viewer.png)

554
## Dockerfile
Nils Windisch's avatar
Nils Windisch committed
555

nwindis's avatar
nwindis committed
556
The dockerfile is used for GitLab CI.  
557
It needs to be updated when either `node` or `quasar-cli` should be updated.
Nils Windisch's avatar
Nils Windisch committed
558
559

```bash
nwindis's avatar
nwindis committed
560
561
docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/tido/node .
docker push docker.gitlab.gwdg.de/subugoe/emo/tido/node
562
```
563

564
## Connecting the Viewer to a Backend
565

nwindis's avatar
nwindis committed
566
The viewer expects JSON that complies to the [SUB's generic TextAPI](https://subugoe.pages.gwdg.de/emo/text-api/) in order to function properly.  
567
568
569
570
571
572
573
574
To establish a link to the backend, the viewer's entrypoint in `src/index.template.html` has to be modified:

```html
"entrypoint": "https://{server}{/prefix}/{collection}/collection.json"
```

The entrypoint should point to the collection you want to be displayed.

575
576
## Architecture

577
![Architecture diagram of TIDO](img/emo_architecture.png)
578

579
580
581
582
583
584
## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

nwindis's avatar
nwindis committed
585
We use [SemVer](https://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://gitlab.gwdg.de/subugoe/emo/tido/-/tags).
586
587
588

## Authors

nwindis's avatar
nwindis committed
589
See the list of [contributors](https://gitlab.gwdg.de/subugoe/emo/tido/-/graphs/develop) who participated in this project.