README.md 10.9 KB
Newer Older
1
# EMo Viewer
Mathias Goebel's avatar
Mathias Goebel committed
2

mrodzis's avatar
mrodzis committed
3
Viewer for the modular framework to present digital editions.
Mathias Goebel's avatar
Mathias Goebel committed
4

5
6
7
8
**Note:**
Although the EMo Viewer 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).
This is the reason for "Ahiqar" being mentioned several times in the docs of this repo.

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

11
12
(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
13

14
15
16
17
18
**Overview:**

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

schneider210's avatar
schneider210 committed
19
20
21
- [Viewer components](#viewer-components)
- [Latest version](#latest-version)
- [Integration](#integration)
22
23
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
schneider210's avatar
schneider210 committed
24
25
26
27
28
29
30
31
32
33
  - [Installation](#installation)
    - [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)
- [Usage](#usage)
  - [Start the Viewer in `development` mode (hot reloading, error reporting, etc.)](#start-the-viewer-in-development-mode-hot-reloading-error-reporting-etc)
    - [`Lint` the files](#lint-the-files)
    - [`Build` the app for production](#build-the-app-for-production)
- [Customize the Configuration](#customize-the-configuration)
34
35
36
37
- [Configure the Viewer](#configure-the-viewer)
  - [The keys in detail](#the-keys-in-detail)
- [Dockerfile](#dockerfile)
- [Connecting the Viewer to a Backend](#connecting-the-viewer-to-a-backend)
schneider210's avatar
schneider210 committed
38
- [Architecture](#architecture)
39
40
41
42
43
44
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Authors](#authors)

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

schneider210's avatar
schneider210 committed
45
## Viewer components
46

schneider210's avatar
schneider210 committed
47
48
49
![Viewer components](img/Viewer.png)

## Latest version
50

schneider210's avatar
schneider210 committed
51
To embed the viewer for production, the latest compiled and minified version is
52
available at: <https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/packages/25>
schneider210's avatar
schneider210 committed
53
54

## Integration
55

schneider210's avatar
schneider210 committed
56
57
58
59
60
To include the viewer on a website add the following to your `index.html` file:

```html
<noscript>
  <strong>We're sorry but TextViewer doesn't work properly without JavaScript enabled.
61
  Please enable it to continue.
schneider210's avatar
schneider210 committed
62
63
64
65
66
  </strong>
</noscript>

<script id="emo-config" type="application/json">
  {
67
    ...
schneider210's avatar
schneider210 committed
68
69
70
71
72
73
74
75
76
77
78
79
80
  }
</script>

<div id=q-app></div>

<script src=js/app.[CHECKSUM].js></script>
<script src=js/runtime.[CHECKSUM].js></script>
<script src=js/vendor.[CHECKSUM].js></script>

```

and replace `[CHECKSUM]` with the values from the release you are going to use.

81
82
<!-- TODO: looking at https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/packages/25 I'm not sure I get where I should look for for the checksums. in the release's index.html? -->

mrodzis's avatar
mrodzis committed
83
84
85
86
87
88
## Getting Started

### Prerequisites

To get the EMo Viewer up and running you should have the following software installed:

89
90
91
- **curl**
- **npm**
- **nvm**
mrodzis's avatar
mrodzis committed
92

93
**Note**:
mrodzis's avatar
mrodzis committed
94

schneider210's avatar
schneider210 committed
95
We recommend to make use of `nvm`, since there might be issues with npm regarding permissions.
96
97
98
99
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
100

schneider210's avatar
schneider210 committed
101
102
103
### Installation

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

105
106
  ```bash
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
107
  nvm install node
108
109
  nvm install stable
  ```
110

111
**Note**:
mrodzis's avatar
mrodzis committed
112

113
114
After the nvm installation is done, please `restart` your shell session once.
That's due to changes to your profile environment.
115

schneider210's avatar
schneider210 committed
116
#### Set up `global` project requirements via `npm`
117
118
119
120
121
122
123
124
125
126
127
128
129

  ```bash
  npm install -g @vue/cli @vue/cli-service-global @quasar/cli
  ```

#### Clone the repository

  ```bash
  git clone git@gitlab.gwdg.de:subugoe/emo/viewer.git
  ```

#### Get the dependencies

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

  ```bash
  cd /path/to/projectdir
  npm install
  ```

schneider210's avatar
schneider210 committed
137
That's it. You should now be able to run the Viewer.
138
139

## Usage
Mathias Goebel's avatar
Mathias Goebel committed
140

schneider210's avatar
schneider210 committed
141
### Start the Viewer in `development` mode (hot reloading, error reporting, etc.)
142

Mathias Goebel's avatar
Mathias Goebel committed
143
```bash
144
npm run dev
Mathias Goebel's avatar
Mathias Goebel committed
145
```
146

147
(usually located at: `localhost:8080`)
Nils Windisch's avatar
Nils Windisch committed
148

schneider210's avatar
schneider210 committed
149
#### `Lint` the files
150

Mathias Goebel's avatar
Mathias Goebel committed
151
152
153
154
```bash
npm run lint
```

schneider210's avatar
schneider210 committed
155
#### `Build` the app for production
156

Mathias Goebel's avatar
Mathias Goebel committed
157
```bash
158
npm run build
Mathias Goebel's avatar
Mathias Goebel committed
159
160
```

161
**Note**: The complete build is located at `/dist/spa/`.
schneider210's avatar
schneider210 committed
162
163

## Customize the Configuration
164

Mathias Goebel's avatar
Mathias Goebel committed
165
See [Configuring quasar.conf.js](https://quasar.dev/quasar-cli/quasar-conf-js).
mrodzis's avatar
mrodzis committed
166

167
168
## Configure the Viewer

169
Locate the `index.template.html` file inside the root of your project dir and find the script section.
170

171
172
**Note**:

173
174
175
It's a JSON object.
<!-- TODO: I'm not sure what the following sentence means. Should I use double or single quotes? Or should I use double quotes only once instead of escaping them? -->
So if you are going to make any changes and you have to quote these, use double quotes but single ones.
176

schneider210's avatar
schneider210 committed
177
```html
dindigala's avatar
dindigala committed
178
  <script id="emo-config" type="application/json">
schneider210's avatar
schneider210 committed
179
    {
180
181
182
      "entrypoint": "https://{server}{/prefix}/{collection}/collection.json",
      "headers": {
        "all": true,
schneider210's avatar
schneider210 committed
183
        "info": true,
184
185
186
187
188
189
190
        "navigation": true,
        "toggle": true
      },
      "labels": {
        "item": "Sheet",
        "manifest": "Manuscript"
      },
191
192
      "standalone": true
    }
dindigala's avatar
dindigala committed
193
  </script>
194
195
```

dindigala's avatar
dindigala committed
196
197
## Configure Panels

198
In order to configure the panels, locate the `panels.js` file inside the `src/config` of your project dir and find the panels section.
dindigala's avatar
dindigala committed
199
200
201

**Note**:

202
203
As a rule of thumb, every key with a boolean value (e.g. *true* or *false*) defaults to `true` and denotes to show the appropriate component.
If you intend to hide a component, just toggle its corresponding key-value to `false`.
dindigala's avatar
dindigala committed
204

205
It's an array structure.
206
207

```html
dindigala's avatar
dindigala committed
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
  const panels = [
    {
      id: uuidv4(),
      connector: [1, 2],
      panel_label: 'Tabs',
      show: true,
      tab_model: null,
    },
    {
      id: uuidv4(),
      connector: [3],
      panel_label: 'Image',
      show: true,
    },
    {
      id: uuidv4(),
      connector: [4],
      panel_label: 'Text',
      show: true,
    },
    {
      id: uuidv4(),
      connector: [5],
      panel_label: 'Annotations',
      show: true,
    },
  ];
schneider210's avatar
schneider210 committed
235
```
236

237
238
### The keys in detail

239
- **entrypoint**
240

schneider210's avatar
schneider210 committed
241
242
	to link the viewer to a backend, the entrypoint should point to the collection you want to be displayed.<br />
	(Further details below: [Connecting the Viewer to a Backend](#connecting-the-viewer-to-a-backend))
243

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

schneider210's avatar
schneider210 committed
246
- **headers**
247

schneider210's avatar
schneider210 committed
248
249
250
  - **all**<br />
    set this value to `false` if you want to completely switch off all the headerbars at once.<br />
    This value takes precedence over the other *header-keys*.<br />
251
    If it is set to *false*, the other settings for the individual bars are not taken into account.<br />
schneider210's avatar
schneider210 committed
252
    *(A use case might be to embed the Viewer into an existing website and you simply need more screen space)*
253

schneider210's avatar
schneider210 committed
254
255
256
257
258
259
  - **info**<br />
    set this value to `false` if you want to switch off the Infobar (a.k.a. breadcrumbs)
  - **navigation**<br />
    set this value to `false` if you want to switch off the NavBar
  - **toggle**<br />
    set this value to `false` if you want to switch off the ToggleBar.
260

schneider210's avatar
schneider210 committed
261
    **Note**: if you turn this one off, you won't be able to toggle the panels anymore.
262

263
    All header values default to `true`.
264
265
266

- **labels**

schneider210's avatar
schneider210 committed
267
268
269
270
  - **item**:<br />
    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.<br />
271
    This change affects the captions of the navbuttons located in the headerbar and the metadata section.
272

273
    Defaults to `Sheet`.
274

schneider210's avatar
schneider210 committed
275
276
  - **manifest**:<br />
    same as for `item` but related to the manifest title<br />
277

278
    Defaults to `Manuscript`.
279

dindigala's avatar
dindigala committed
280
281
282
283
- **standalone**

	denotes if the Viewer will be used as a single page application on it's own or if it will be embedded into an existing page. If you want to use it in the latter case, please toggle the value to "false". That way the language toggle in the footer section will not show up.

284
	Defaults to **true**.
dindigala's avatar
dindigala committed
285
286
287
288

- **Panels Configure**

  - **panels**
289

290
  Its keys correspond to the panelnames, e.g. "contents", "text", "image" and so on.
291
  <br />
292
  **Note:** Please **leave these keys UNTOUCHED** since these are for internal use only!
293
  <br /><br />
dindigala's avatar
dindigala committed
294
295
	Each object inside panels consists of keys: `id`, `connector`, `pane_label`, `show` and `tab_model`.
  	Change either panel_label-key according to your liking and set either show-key to **false** if you don't want the Viewer to show the appropriate panel/s.
296

schneider210's avatar
schneider210 committed
297
298
299
300
  	Example given:

    ```json
    {
dindigala's avatar
dindigala committed
301
      panels: [
302
        {
dindigala's avatar
dindigala committed
303
304
305
306
307
          id: uuidv4(),
          connector: [1, 2],
          panel_label: 'Tabs',
          show: true,
          tab_model: null,
308
        },
dindigala's avatar
dindigala committed
309
      ]
schneider210's avatar
schneider210 committed
310
311
    }
    ```
312

313
  - **id** Provides unique id always instead of hard coded IDs.
dindigala's avatar
dindigala committed
314
315
  - **connector** Groups together the panels as tabs (works on user configure as well).
  - **panel_label** Refers to the caption in each panel's toolbar
316
  - **show** toggles (show or rather hide) the appropriate panel respectively.
dindigala's avatar
dindigala committed
317
  - **tab_model** Represents to displays panels in a tab when loading for the first time.
318

319
## Dockerfile
Nils Windisch's avatar
Nils Windisch committed
320

321
322
The dockerfile is used for GitLab CI.
It needs to be updated when either `node` or `quasar-cli` should be updated.
Nils Windisch's avatar
Nils Windisch committed
323
324

```bash
325
docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/qviewer/node .
326
327
docker push docker.gitlab.gwdg.de/subugoe/emo/qviewer/node
```
328

329
## Connecting the Viewer to a Backend
330
331
332
333
334
335
336
337
338
339

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

340
341
342
343
## Architecture

![Architecture diagram of the EMo viewer](img/emo_architecture.png)

344
345
346
347
348
349
350
351
352
353
354
## Contributing

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

## Versioning

We use [SemVer](https://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/tags).

## Authors

See the list of [contributors](https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/graphs/develop) who participated in this project.