README.md 6.46 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
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
**Overview:**

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

- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installing](#installing)
  - [Get the Dependencies](#get-the-dependencies)
  - [Start the App in Development Mode (Hot-Code Reloading, Error Reporting, etc.)](#start-the-app-in-development-mode-hot-code-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)
- [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)
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Authors](#authors)

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

mrodzis's avatar
mrodzis committed
37
38
39
40
41
42
## Getting Started

### Prerequisites

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

43
44
45
- npm
- vue-cli (globally installed)
- vue-cli-service-global (globally installed)
mrodzis's avatar
mrodzis committed
46
47

For using the development mode you also need
Nils Windisch's avatar
Nils Windisch committed
48

49
- quasar-cli (globally installed)
mrodzis's avatar
mrodzis committed
50
51
52
53
54
55
56
57
58
59

To get all dependencies via `npm`, simply run

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

### Installing

### Get the Dependencies
60

Mathias Goebel's avatar
Mathias Goebel committed
61
62
63
64
```bash
npm install
```

mrodzis's avatar
mrodzis committed
65
### Start the App in Development Mode (Hot-Code Reloading, Error Reporting, etc.)
66

Mathias Goebel's avatar
Mathias Goebel committed
67
68
69
```bash
quasar dev
```
Nils Windisch's avatar
Nils Windisch committed
70

schneider210's avatar
schneider210 committed
71
### Lint the files
72

Mathias Goebel's avatar
Mathias Goebel committed
73
74
75
76
```bash
npm run lint
```

mrodzis's avatar
mrodzis committed
77
### Build the App for Production
78

Mathias Goebel's avatar
Mathias Goebel committed
79
80
81
82
```bash
quasar build
```

mrodzis's avatar
mrodzis committed
83
### Customize the Configuration
84

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

87
88
89
90
## Configure the Viewer

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

91
*Please 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.
92

schneider210's avatar
schneider210 committed
93
94
95
```html
    <script id="emo-config" type="application/json">
    {
96
97
98
99
100
101
102
103
104
105
106
      "entrypoint": "https://{server}{/prefix}/{collection}/collection.json",
      "headers": {
        "all": true,
        "info": false,
        "navigation": true,
        "toggle": true
      },
      "labels": {
        "item": "Sheet",
        "manifest": "Manuscript"
      },
schneider210's avatar
schneider210 committed
107
108
      "panels": {
        "image": true,
109
110
111
112
113
        "text": false,
        "metadata": true,
        "treeview": true
      },
      "standalone": true
schneider210's avatar
schneider210 committed
114
115
116
    }
    </script>
```
117
118
119

### The keys in detail

120
- **entrypoint**
121
  - 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))
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
- **headers**
  - **all**
     - set this value to `false` if you want to completely switch off all the headerbars at once. This value is preceeding. If it's set to false, the other settings for the individual bars are not taken into account.
      *(A use case might be to embed the Viewer into an existing website and you simply need more space)*
  - **info**
     - set this value to `false` if you want to switch off the Infobar (breadcrumbs)
  - **navigation**
     - set this value to `false` if you want to switch off the NavBar
  - **toggle**
     - set this value to `false` if you want to switch off the ToggleBar. Please *note*: if you turn this one off, you won't be able to toggle the panels anymore

    All header values default to **true**

- **labels**
  - **item**
     - 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.
140
141
This change affects the captions of the navigational tools, e.g. the navbuttons in the header as well as the prefix of each treenode displayed and the metadata section

142
  Defaults to **Sheet**
143

144
145
  - **manifest**
     - same as for `item` but related to the manifest title
146

147
  Defaults to **Manuscript**
148

149
150
- **panels**
  - It's keys correspond to the panelnames, e.g. "treeview", "text", "image", "metadata".
151
152
153
154
  Set either value to **false** if you don't want the Viewer to show the appropriate panel/s.

  Defaults to **true** for every panel

155
156
157
158
159
160
  - **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.

  Defaults to **true**

161
## Dockerfile
Nils Windisch's avatar
Nils Windisch committed
162

163
164
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
165
166

```bash
167
docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/qviewer/node .
168
169
docker push docker.gitlab.gwdg.de/subugoe/emo/qviewer/node
```
170

171
## Connecting the Viewer to a Backend
172
173
174
175
176
177
178
179
180
181

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.

182
183
184
185
## Architecture

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

186
187
188
189
190
191
192
193
194
195
196
## 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.