README.md 7.47 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
- **curl**
- **npm**
- **nvm**
mrodzis's avatar
mrodzis committed
46

Nils Windisch's avatar
Nils Windisch committed
47

48
**Note**:
mrodzis's avatar
mrodzis committed
49

50
51
52
53
54
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
55

56
#### Set up *nvm* and the recent stable version of *node.js*
mrodzis's avatar
mrodzis committed
57

58
59
60
61
62
  ```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
63

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

66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
#### Set up *global* project requirements via npm

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

### Installation

#### 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
  ```

That's it. You now should be able to run the Viewer.

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

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

95
96
#### Start a local instance of a dev server

Mathias Goebel's avatar
Mathias Goebel committed
97
```bash
98
npm run dev
Mathias Goebel's avatar
Mathias Goebel committed
99
```
100
(usually located at: `localhost:8080`)
Nils Windisch's avatar
Nils Windisch committed
101

102
#### Lint the files
103

Mathias Goebel's avatar
Mathias Goebel committed
104
105
106
107
```bash
npm run lint
```

108
#### Build the App for Production
109

Mathias Goebel's avatar
Mathias Goebel committed
110
```bash
111
npm run build
Mathias Goebel's avatar
Mathias Goebel committed
112
113
```

mrodzis's avatar
mrodzis committed
114
### Customize the Configuration
115

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

118
119
120
121
## Configure the Viewer

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

122
123
124
**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.
125

schneider210's avatar
schneider210 committed
126
127
128
```html
    <script id="emo-config" type="application/json">
    {
129
130
131
132
133
134
135
136
137
138
139
      "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
140
141
      "panels": {
        "image": true,
142
143
144
145
146
        "text": false,
        "metadata": true,
        "treeview": true
      },
      "standalone": true
schneider210's avatar
schneider210 committed
147
148
149
    }
    </script>
```
150
151
152

### The keys in detail

153
- **entrypoint**
154
155

	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))
156
157
- **headers**
  - **all**
158
159
160

		set this value to `false` if you want to completely switch off all the headerbars at once. This value takes precedence. 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 screen space)*
161
  - **info**
162
163

		set this value to `false` if you want to switch off the Infobar (breadcrumbs)
164
  - **navigation**
165
166

		set this value to `false` if you want to switch off the NavBar
167
168
  - **toggle**

169
170
171
172
173
		set this value to `false` if you want to switch off the ToggleBar.

		**Note**: if you turn this one off, you won't be able to toggle the panels anymore.

		All header values default to **true**
174
175

- **labels**
176
  - **item**: the label of the item respectively
177

178
179
		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.
180

181
		Defaults to **Sheet**
182

183
  - **manifest**: same as for `item` but related to the manifest title
184

185
		Defaults to **Manuscript**
186

187
- **panels**
188

189
190
191
192
	It's keys correspond to the panelnames, e.g. "treeview", "text", "image", "metadata".
  	Set either value to **false** if you don't want the Viewer to show the appropriate panel/s.

	Defaults to **true** for every panel
193

194
- **standalone**
195

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

198
	Defaults to **true**
199

200
## Dockerfile
Nils Windisch's avatar
Nils Windisch committed
201

202
203
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
204
205

```bash
206
docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/qviewer/node .
207
208
docker push docker.gitlab.gwdg.de/subugoe/emo/qviewer/node
```
209

210
## Connecting the Viewer to a Backend
211
212
213
214
215
216
217
218
219
220

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.

221
222
223
224
## Architecture

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

225
226
227
228
229
230
231
232
233
234
235
## 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.