README.md 11.1 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
22

- [Viewer components](#viewer-components)
- [Latest version](#latest-version)
- [Integration](#integration)
23
24
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
schneider210's avatar
schneider210 committed
25
26
27
28
29
30
31
32
33
34
  - [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)
35
36
37
38
- [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
39
- [Architecture](#architecture)
40
41
42
43
44
45
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Authors](#authors)

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

schneider210's avatar
schneider210 committed
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
## Viewer components
![Viewer components](img/Viewer.png)

## Latest version
To embed the viewer for production, the latest compiled and minified version is
available at: https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/jobs/artifacts/develop/download?job=build

## Integration
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.
  	Please enable it to continue.
  </strong>
</noscript>

<script id="emo-config" type="application/json">
  {
	...
  }
</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.

mrodzis's avatar
mrodzis committed
79
80
81
82
83
84
## Getting Started

### Prerequisites

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

85
86
87
- **curl**
- **npm**
- **nvm**
mrodzis's avatar
mrodzis committed
88

89
**Note**:
mrodzis's avatar
mrodzis committed
90

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

schneider210's avatar
schneider210 committed
97
98
99
### Installation

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

101
102
103
104
105
  ```bash
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
  nvm install stable
  ```
**Note**:
mrodzis's avatar
mrodzis committed
106

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

schneider210's avatar
schneider210 committed
109
#### Set up `global` project requirements via `npm`
110
111
112
113
114
115
116
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

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

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

schneider210's avatar
schneider210 committed
130
That's it. You should now be able to run the Viewer.
131
132

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

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

Mathias Goebel's avatar
Mathias Goebel committed
136
```bash
137
npm run dev
Mathias Goebel's avatar
Mathias Goebel committed
138
```
139
(usually located at: `localhost:8080`)
Nils Windisch's avatar
Nils Windisch committed
140

schneider210's avatar
schneider210 committed
141
#### `Lint` the files
142

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

schneider210's avatar
schneider210 committed
147
#### `Build` the app for production
148

Mathias Goebel's avatar
Mathias Goebel committed
149
```bash
150
npm run build
Mathias Goebel's avatar
Mathias Goebel committed
151
152
```

schneider210's avatar
schneider210 committed
153
154
155
**Note**: The complete build is located at /dist/spa/.

## Customize the Configuration
156

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

159
160
## Configure the Viewer

schneider210's avatar
schneider210 committed
161
162
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 it's corresponding key-value to `false`.

163
164
Locate the `index.template.html` file inside the root of your project dir and find the script section:

165
166
167
**Note**:

It's a json object. So if you are going to make any changes and you have to quote these, use double quotes but single ones.
168

schneider210's avatar
schneider210 committed
169
```html
schneider210's avatar
schneider210 committed
170
<script id="emo-config" type="application/json">
schneider210's avatar
schneider210 committed
171
    {
172
173
174
      "entrypoint": "https://{server}{/prefix}/{collection}/collection.json",
      "headers": {
        "all": true,
schneider210's avatar
schneider210 committed
175
        "info": true,
176
177
178
179
180
181
182
        "navigation": true,
        "toggle": true
      },
      "labels": {
        "item": "Sheet",
        "manifest": "Manuscript"
      },
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
      "standalone": true
    }
    </script>
```

The data structure of the panels are inside app.vue component. You can work on this data structure to make any required changes.

```html
  data() {
    return {
      .
      .
      .
      panels: [
        {
          component: null,
          name: 'tabs',
          show: true,
          tabs: {
            children: [
              {
                component: Treeviewtab,
                label: 'Contents',
                name: 'content',
              },
              {
                component: Metadatatab,
                label: 'Metadata',
                name: 'meta',
              },
            ],
            model: 'content',
          },
          toolbar: 'Tabs',
217
        },
218
219
220
221
222
223
        {
          component: OpenSeadragon,
          name: 'image',
          show: true,
          tabs: [],
          toolbar: 'Image',
schneider210's avatar
schneider210 committed
224
        },
225
226
227
228
229
230
        {
          component: Content,
          name: 'text',
          show: true,
          tabs: [],
          toolbar: 'Content',
schneider210's avatar
schneider210 committed
231
        },
232
233
234
235
236
237
        {
          component: null,
          name: 'annotations',
          show: true,
          tabs: [],
          toolbar: 'Annotations',
schneider210's avatar
schneider210 committed
238
        },
239
      ],
schneider210's avatar
schneider210 committed
240
    }
241
  }
schneider210's avatar
schneider210 committed
242
```
243
244
245

### The keys in detail

246
- **entrypoint**
247

schneider210's avatar
schneider210 committed
248
249
	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))
250

schneider210's avatar
schneider210 committed
251
	**Note**: You have to provide at least a valid entrypoint (see above). Otherwise the Viewer won't show anything at all!
252

schneider210's avatar
schneider210 committed
253
- **headers**
254

schneider210's avatar
schneider210 committed
255
256
257
258
259
  - **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 />
    If it's set to *false*, the other settings for the individual bars are not taken into account.<br />
    *(A use case might be to embed the Viewer into an existing website and you simply need more screen space)*
260

schneider210's avatar
schneider210 committed
261
262
263
264
265
266
  - **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.
267

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

schneider210's avatar
schneider210 committed
270
    All header values default to `true`
271
272
273

- **labels**

schneider210's avatar
schneider210 committed
274
275
276
277
  - **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 />
278
    This change affects the captions of the navbuttons located in the headerbar and the metadata section.
279

280
    Defaults to `Sheet`
281

schneider210's avatar
schneider210 committed
282
283
  - **manifest**:<br />
    same as for `item` but related to the manifest title<br />
284

285
    Defaults to `Manuscript`
286

287
- **panels**
288

289
	It's keys correspond to the panelnames, e.g. "contents", "text", "image" and so on.
290
291
292
293
294
295
  <br />
  **Note:** Pls **leave these keys UNTOUCHED** since these are for internal use only!
  <br /><br />
	Each object inside panels consists of keys: `component`, `name`, `show`, `tab` and `toolbar`.
  	Change either name-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.

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

    ```json
    {
300
301
302
303
304
305
306
307
      panels: {
        {
          component: toC,
          name: 'text',
          show: false,
          tabs: false,
          toolbar: 'toC',
        },
schneider210's avatar
schneider210 committed
308
309
310
      }
    }
    ```
311

312
313
314
315
316
  - **Component** Refers to the required component that we are integrating.
  - **name** Refers to the caption in each panel's toolbar.
  - **show** toggles (show or rather hide) the appropriate panel respectively.
  - **tabs** denotes, if the panel will be grouped together with others inside a single panel.
  - **toolbar** displays the related component on toolbar and can able to toggle panels.
317

318
- **standalone**
319

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

322
	Defaults to **true**
323

324
## Dockerfile
Nils Windisch's avatar
Nils Windisch committed
325

326
327
The dockerfile is used at GitLab CI.
It needs to be updated, when either node or quasar-cli should be updated.
Nils Windisch's avatar
Nils Windisch committed
328
329

```bash
330
docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/qviewer/node .
331
332
docker push docker.gitlab.gwdg.de/subugoe/emo/qviewer/node
```
333

334
## Connecting the Viewer to a Backend
335
336
337
338
339
340
341
342
343
344

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.

345
346
347
348
## Architecture

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

349
350
351
352
353
354
355
356
357
358
359
## 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.