Commit 071b2762 authored by schneider210's avatar schneider210
Browse files

Merge branch 'feature/#105-release-via-npm' into 'develop'

Feature/#105 release via npm

See merge request subugoe/emo/Qviewer!108
parents 9ef7209f 861d3d06
Pipeline #168503 passed with stages
in 2 minutes and 35 seconds
.DS_Store
.thumbs.db
.npmrc
node_modules
# Quasar core related directories
......
......@@ -15,7 +15,8 @@ build_test:
stage: build
script:
- npm install
- quasar build
- npm run build
- npm run tweak:build
artifacts:
paths:
- dist/
......@@ -28,7 +29,8 @@ build_main_and_develop:
stage: build
script:
- npm install
- quasar build
- npm run build
- npm run tweak:build
artifacts:
paths:
- dist/
......@@ -90,11 +92,12 @@ pushback:
script:
- npm install
- npm run build
- mkdir emo-viewer && mv dist/js/* emo-viewer/
- npm run tweak:build
- mkdir tido && mv dist/* tido/
artifacts:
expire_in: 5 yrs
paths:
- emo-viewer
- tido
# when a git flow release is made, a tag will be pushed starting this job. it
# will keep the resulting artifact from the job declared in `JOB_NUMBER_TO_PRESERVE`
......
//gitlab.gwdg.de/api/v4/projects/10921/packages/npm/:_authToken=$AUTH_TOKEN
//gitlab.gwdg.de/api/v4/packages/npm/:_authToken=$AUTH_TOKEN
@subugoe:registry=https://gitlab.gwdg.de/api/v4/packages/npm/
# EMo Viewer
# TIDO
Viewer for the modular framework to present digital editions.
Text vIewer for Digital Objects.
**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).
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).
This is the reason for "Ahiqar" being mentioned several times in the docs of this repo.
......@@ -17,11 +17,15 @@ Also the commit short hash can be used to see a demo.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Viewer Components](#viewer-components)
- [Latest Version and Integration](#latest-version-and-integration)
- [Getting Started](#getting-started)
- [A) Installation via npm](#a-installation-via-npm)
- [Registry setup](#registry-setup)
- [Installation](#installation)
- [B) Download the bundle](#b-download-the-bundle)
- [Integration](#integration)
- [Getting Started (Developers)](#getting-started-developers)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Environment setup](#environment-setup)
- [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)
......@@ -36,6 +40,7 @@ Also the commit short hash can be used to see a demo.
- [The Keys in Detail](#the-keys-in-detail)
- [b) Configure the Panels](#b-configure-the-panels)
- [The Panel Keys in Detail](#the-panel-keys-in-detail)
- [Viewer Components](#viewer-components)
- [Dockerfile](#dockerfile)
- [Connecting the Viewer to a Backend](#connecting-the-viewer-to-a-backend)
- [Architecture](#architecture)
......@@ -45,75 +50,133 @@ Also the commit short hash can be used to see a demo.
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Viewer Components
## Latest Version and Integration
![Viewer components](img/Viewer.png)
There are two options - **A)** and **B)** - to get the Viewer depending on it's usage.
## Latest Version and Integration
Please follow these steps to include it for production:
### A) Installation via npm
#### Registry setup
Since npm communicates with the package api, it's necessary to setup a valid entrypoint.
```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
```
### B) Download the bundle
To embed the viewer for production [get the latest compiled and minified version](https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/jobs/artifacts/develop/download?job=build_main_and_develop)
It is a zip archive. You can extract the build by typing:
As an **alternative** to the npm package you can download the artifact: [get the latest compiled and minified version](https://gitlab.gwdg.de/subugoe/emo/Qviewer/-/jobs/artifacts/develop/download?job=build_main_and_develop)
It is a zip archive. Extract the downloaded build by typing:
```bash
unzip artifacts.zip
```
This creates the following folder structure containing the actual build:
This creates the following folder structure:
```bash
dist/spa/
├── css
│   ├── 2.5b2a42f3.css
│   ├── app.222a6363.css
│   └── vendor.2303fac8.css
dist/
├── index.html
└── js
├── 2.5d86d581.js
├── app.297a75a4.js
└── vendor.f055a028.js
└── tido.js
```
To include the viewer on a website add the following to your `index.html` file:
### Integration
The integration depends on the option you chose from above; e.g. installation via npm or rather bundle download.
**A)** If you installed *TIDO* with **npm**, add this line to your **main.js** file:
```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.
**B)** If you **downloaded** *TIDO* as a **bundle**, reference the js file accordingly at the end of the body tag inside your **index.html** file:
```html
<head>
...
<script src="dist/tido.js"></script>
```
<link href=css/app.[CHECKSUM].css rel=stylesheet>
<link href=css/vendor.[CHECKSUM].css rel=stylesheet>
</head>
**Finally** copy the config object into your entrypoint file (usually **index.html**):
...
```html
<body>
...
<noscript>
<strong>We're sorry but TextViewer doesn't work properly without JavaScript enabled.
Please enable it to continue.
</strong>
</noscript>
<noscript>
<strong>We're sorry but TIDO doesn't work properly without JavaScript enabled.
Please enable it to continue.
</strong>
</noscript>
<script id="emo-config" type="application/json">
<script id="tido-config" type="application/json">
{
...
"entrypoint": "https://subugoe.pages.gwdg.de/emo/backend/sampledata/collection.json",
"colors": {
"primary": "",
"secondary": "",
"accent": ""
},
"headers": {
"all": true,
"info": true,
"navigation": true,
"toggle": true
},
"labels": {
"item": "Sheet",
"manifest": "Manuscript"
},
"meta": {
"collection": {
"all": true,
"collector": true,
"description": true,
"title": true
},
"manifest": {
"all": true,
"creation": true,
"editor": true,
"label": true,
"location": true,
"origin": true
},
"item": {
"all": true,
"label": true,
"language": true
}
},
"standalone": true
}
</script>
</script>
<div id=q-app></div>
<div id="q-app"></div>
</body>
<script src=js/app.[CHECKSUM].js></script>
<script src=js/vendor.[CHECKSUM].js></script>
```
and replace `[CHECKSUM]` with the values from the release you are going to use.
**Note**:
**Note**: Please make sure to provide a valid *entrypoint* that points to the manifest / collection that you want to be displayed.
The **CHECKSUMs** change in each build. So please make sure to copy the ones from **dist/spa/index.html**.
## Getting Started
## Getting Started (Developers)
### Prerequisites
To get the EMo Viewer up and running you should have the following software installed:
To get TIDO up and running you should have the following software installed:
- **curl**
- **npm**
......@@ -126,20 +189,17 @@ The main purpose of `nvm` is to have multiple node versions installed in regards
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.
### Installation
### Environment setup
#### Set up `nvm` and the recent stable version of `node.js`
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
nvm install node
nvm install stable
```
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
nvm install stable
```
**Note**:
After the nvm installation is done, please `restart` your shell session once.
That's due to changes to your profile environment.
After the nvm installation is done, please `restart` your shell session once. That's due to changes to your profile environment.
#### Set up `global` project requirements via `npm`
......@@ -201,8 +261,8 @@ npm run build
## Configuration
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) (Configuring quasar.conf.js).
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).
There are two files in regards to configuration:
......@@ -225,7 +285,7 @@ Locate the `script` section in the `index.template.html` file:
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.
```html
<script id="emo-config" type="application/json">
<script id="tido-config" type="application/json">
{
"entrypoint": "https://{server}{/prefix}/{collection}/collection.json",
"colors": {
......@@ -271,7 +331,7 @@ As a rule of thumb, every key with a boolean value (e.g. *true* or *false*) defa
**Note**:
It's a *JSON* object. So if you are going to make any changes and you have to quote these (see *labels* or colors), please use *double quotes* only.
It's a *JSON* object. So if you are going to make any changes and you have to quote these (see *labels* or *colors*), please use *double quotes* only.
#### The Keys in Detail
......@@ -450,6 +510,10 @@ Assuming you want to combine the *Metadata*, *Text* and *Annotations* panels:
To rename a panel heading, change the corresponding `panel_label` according to your needs.
If you intend to hide a component, just toggle its corresponding *show-key* to `false`.
## Viewer Components
![Viewer components](img/Viewer.png)
## Dockerfile
The dockerfile is used for GitLab CI.
......@@ -473,7 +537,7 @@ The entrypoint should point to the collection you want to be displayed.
## Architecture
![Architecture diagram of the EMo viewer](img/emo_architecture.png)
![Architecture diagram of TIDO](img/emo_architecture.png)
## Contributing
......
File mode changed from 100755 to 100644
{
"name": "@subugoe/qviewer",
"version": "1.4.5",
"name": "@subugoe/tido",
"version": "1.4.21",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
......
{
"name": "@subugoe/qviewer",
"version": "1.4.5",
"description": "Viewer for the modular framework to present digital editions",
"productName": "EMo Viewer",
"name": "@subugoe/tido",
"version": "1.4.21",
"description": "Text vIever for Digital Objects",
"productName": "TIDO",
"keywords": [
"viewer",
"emo",
"digital editions",
"vue",
"quasar",
"openseadragon",
"sub"
"quasar",
"subugoe",
"TIDO",
"viewer",
"vue"
],
"cordovaId": "de.uni-goettingen.sub.emo",
"capacitorId": "",
......@@ -86,19 +85,25 @@
"scripts": {
"build": "quasar build --modern",
"dev": "quasar dev --modern",
"lint": "npm run lint:vue && npm run lint:js && npm run lint:scss && npm run lint:markdown",
"test": "npm run test:unit",
"fix": "npm run fix:vue && npm run fix:js && npm run fix:scss",
"write-changelog": "HUSKY_SKIP_HOOKS=1 standard-version",
"fix:vue": "eslint --fix --ext .vue src",
"fix:js": "eslint --fix --ext .js src",
"fix:scss": "node_modules/.bin/stylelint --fix 'src/**/*.scss'",
"lint:vue": "eslint --ext .vue src",
"fix:vue": "eslint --fix --ext .vue src",
"lint": "npm run lint:vue && npm run lint:js && npm run lint:scss && npm run lint:markdown",
"lint:js": "eslint --ext .js src",
"lint:scss": "node_modules/.bin/stylelint 'src/**/*.{scss,vue}'",
"lint:markdown": "node_modules/.bin/markdownlint '**/*.{md,markdown}'",
"test:unit": "jest --updateSnapshot"
"lint:scss": "node_modules/.bin/stylelint 'src/**/*.{scss,vue}'",
"lint:vue": "eslint --ext .vue src",
"release": "npm run build && npm run tweak:build && npm publish",
"test": "npm run test:unit",
"test:unit": "jest --updateSnapshot",
"tweak:build": "./tweak_build.sh",
"write-changelog": "HUSKY_SKIP_HOOKS=1 standard-version"
},
"files": [
"dist",
"src/statics/support.css"
],
"publishConfig": {
"@subugoe:registry": "https://gitlab.gwdg.de/api/v4/projects/10921/packages/npm/"
},
......
......@@ -12,28 +12,22 @@ module.exports = function (ctx) {
// https://quasar.dev/quasar-cli/quasar-conf-js#Property%3A-css
css: [
'/style.scss'
'style.scss'
],
// https://github.com/quasarframework/quasar/tree/dev/extras
extras: [
// 'ionicons-v4',
// 'mdi-v4',
// 'fontawesome-v5',
// 'eva-icons',
// 'themify',
// 'line-awesome',
// 'roboto-font-latin-ext', // this or either 'roboto-font', NEVER both!
// 'roboto-font', // optional, you are not bound to it
// 'material-icons' // optional, you are not bound to it
],
// extras: [],
// components: [],
cssAddon: true,
dark: 'auto', // or Boolean true/false
// directives: [],
// https://quasar.dev/quasar-cli/quasar-conf-js#Property%3A-framework
framework: {
iconSet: 'fontawesome-v5',
lang: 'en-us', // Quasar language pack
// Possible values for "all":
// * 'auto' - Auto-import needed Quasar components & directives
// (slightly higher compile time; next to minimum bundle size; most convenient)
......@@ -43,21 +37,24 @@ module.exports = function (ctx) {
// (not treeshaking Quasar; biggest bundle size; convenient)
all: 'auto',
dark: 'auto', // or Boolean true/false
// components: [],
// directives: [],
// Quasar plugins
plugins: [],
cssAddon: true,
config: {
brand: {
primary: '#212121',
secondary: '#eee',
accent: '#1a3771'
}
}
},
iconSet: 'fontawesome-v5',
lang: 'en-us', // Quasar language pack
// Quasar plugins
// plugins: []
},
htmlVariables: {
title: 'TIDO'
},
// https://quasar.dev/quasar-cli/cli-documentation/supporting-ie
......@@ -65,33 +62,39 @@ module.exports = function (ctx) {
// Full list of options: https://quasar.dev/quasar-cli/quasar-conf-js#Property%3A-build
build: {
distDir: 'dist',
vueRouterMode: 'hash', // available values: 'hash', 'history'
// analyze: true,
// gzip: true,
// rtl: false, // https://quasar.dev/options/rtl-support
// showProgress: false,
// gzip: true,
// analyze: true,
// Options below are automatically set depending on the env, set them if you want to override
// preloadChunks: false,
// extractCSS: false,
extractCSS: false,
// https://quasar.dev/quasar-cli/cli-documentation/handling-webpack
extendWebpack (cfg) {
cfg.output = {
filename: '[name].js',
},
cfg.resolve.alias = {
...cfg.resolve.alias, // This adds the existing alias
'@': path.resolve(__dirname, './src/'),
},
cfg.module.rules.push({
enforce: 'pre',
test: /\.(js|vue)$/,
loader: 'eslint-loader',
exclude: /node_modules/,
options: {
formatter: require('eslint').CLIEngine.getFormatter('stylish')
cfg.module.rules.push(
{
enforce: 'pre',
exclude: /node_modules/,
loader: 'eslint-loader',
options: {
formatter: require('eslint').CLIEngine.getFormatter('stylish')
},
test: /\.(js|vue)$/
}
})
)
}
},
......@@ -102,9 +105,13 @@ module.exports = function (ctx) {
open: false // opens browser window automatically
},
vendor: {
disable: false,
},
// animations: 'all', // --- includes all animations
// https://quasar.dev/options/animations
animations: [],
// animations: [],
// https://quasar.dev/quasar-cli/developing-ssr/configuring-ssr
ssr: {
......@@ -116,9 +123,9 @@ module.exports = function (ctx) {
workboxPluginMode: 'GenerateSW', // 'GenerateSW' or 'InjectManifest'
workboxOptions: {}, // only for GenerateSW
manifest: {
name: 'EMo Viewer',
short_name: 'EMo Viewer',
description: 'Viewer for the modular framework to present digital editions',
name: 'TIDO',
short_name: 'TIDO',
description: 'Text vIever for Digital Objects',
display: 'standalone',
orientation: 'portrait',
background_color: '#ffffff',
......@@ -184,7 +191,7 @@ module.exports = function (ctx) {
builder: {
// https://www.electron.build/configuration/configuration
appId: 'viewer'
appId: 'q-app'
},
// More info: https://quasar.dev/quasar-cli/developing-electron-apps/node-integration
......
......@@ -16,11 +16,11 @@
<q-card>
<q-card-section>
<h1 class="text-h5 q-pb-md">
EMo Viewer
TIDO
</h1>
<p class="text-weight-bold">
Slim, easy to use and mobile-friendly text and image viewer
Text vIewer for Digital Objects
</p>
<p>Copyright (c) 2020 Göttingen University - Göttingen State and University Library</p>
......
<!DOCTYPE html>
<html>
<head>
<title>EMO Viewer</title>
<title><%= title %></title>
<meta charset="utf-8">
<meta name="description" content="<%= htmlWebpackPlugin.options.productDescription %>">
......@@ -9,17 +9,17 @@
<meta name="msapplication-tap-highlight" content="no">
<meta name="viewport" content="initial-scale=1, maximum-scale=5, minimum-scale=1, width=device-width<% if (ctx.mode.cordova || ctx.mode.capacitor) { %>, viewport-fit=cover<% } %>">
<link rel="icon" type="image/x-icon" href="statics/icons/favicon.ico">
<link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
<noscript>
<strong>We're sorry but TextViewer doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
<strong>We're sorry but <%= title %> doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
</noscript>
<script id="tido-config" type="application/json">
{
"entrypoint": "https://ahikar-test.sub.uni-goettingen.de/api/textapi/ahikar/3r9ps/collection.json",
"entrypoint": "",
"colors": {
"primary": "",
"secondary": "",
......@@ -61,7 +61,6 @@
}
</script>
<!-- DO NOT touch the following DIV -->
<div id="q-app"></div>
</body>
</html>
#!/bin/bash
# set exit code !== 0; bash emits '0' on success
BAD_PARAM=127
# the script relies on a properly set up package scope and name
# filter the package name
PKG_NAME=$(grep '\bname\b' './package.json' | cut -d '"' -f4)
# split up scope and name
PKG_SCOPE=${PKG_NAME%/*}
PROD_NAME=${PKG_NAME#*/}
# filter distribution dir
DIST_DIR=$(grep distDir './quasar.conf.js' | cut -d "'" -f2) || dist
# get all the js files put out from the build step
declare -a FILES=( ${DIST_DIR}/*.js )
# concatenate all js files
for i in "${FILES[@]}"; do
cat $i >> ${DIST_DIR}/${PROD_NAME}.js
done