Skip to content
Snippets Groups Projects
Select Git revision
  • renovate/configure
  • Use-Typescript
  • develop default protected
  • omalkja/convert-ItemMeta,ManifestMeta,MetaItem-Typescript
  • omalkja/configuration-for-labels
  • omalkja/issue/#424/nested-metadata
  • omalkja/url_shortener
  • omalkja/issue/make-url-shorter-and-less-redundant
  • omalkja/issue/#424/nested-metadata-not-working-for-nesting-depth-greater-than-2
  • main protected
  • target_task
  • omalkja/issue/#308/disable-option-to-switch-off-all-panels
  • composition-api
  • update-range-highlighting
  • tree-lazy-loading
  • update-highlighting
  • multi
  • wip
  • embedding-fixes
  • readme
  • v3.3.0
  • v3.2.2
  • v3.2.1
  • v3.1.0
  • v3.2.0
  • v3.0.2
  • v3.0.1
  • v3.0.0
  • v2.5.2
  • v2.5.1
  • v2.5.0
  • v2.4.1
  • v2.4.0
  • v2.3.0
  • v2.2.4
  • v2.2.3
  • v2.2.2
  • v2.2.1
  • v2.2.0
  • v2.1.0
40 results
Compare
mrodzis's avatar
Merge branch 'feature/#203-ci-remove-entry-point-at-merge' into 'develop'
Michelle Weidling authored 
Feature/#203 ci remove entry point at merge

Closes #203

See merge request subugoe/emo/Qviewer!135
9b3e4104
History
mrodzis's avatar 9b3e4104
History
Name Last commit Last update
.ci-scripts
.gitlab
img
src
tests/unit
.babelrc
.editorconfig
.eslintignore
.eslintrc.js
.gitignore
.gitlab-ci.yml
.markdownlintignore
.markdownlintrc
.nvmrc
.postcssrc.js
.stylelintrc.json
.versionrc
CHANGELOG.md
CONTRIBUTING.md
Dockerfile
LICENSE
NOTICE.md
README.md
babel.config.js
jest.config.js
jsconfig.json
package-lock.json
package.json
quasar.conf.js
tweak_build.sh
README.md

TIDO

Text vIewer for Digital Objects.

Note: Although TIDO is designed as a generic viewer for digital editions, it is currently developed within the scope of the Ahiqar project.

This is the reason for "Ahiqar" being mentioned several times in the docs of this repo.

Demo: https://subugoe.pages.gwdg.de/emo/Qviewer/develop

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

Overview

Latest Version and Integration

There are two options - A) and B) - to get the Viewer depending on it's usage.

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

echo @subugoe:registry=https://gitlab.gwdg.de/api/v4/packages/npm/ >>.npmrc

Note: fire this command inside the root of your project directory.

Installation

npm i @subugoe/tido

B) Download the bundle

As an alternative to the npm package you can download the artifact: get the latest compiled and minified version

It is a zip archive. Extract the downloaded build by typing:

unzip artifacts.zip

This creates the following folder structure:

dist/
├── index.html
└── tido.js

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:

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:

<script src="dist/tido.js"></script>

Finally copy the config object into your entrypoint file (usually index.html):

<body>
  ...

  <noscript>
    <strong>We're sorry but TIDO doesn't work properly without JavaScript enabled.
      Please enable it to continue.
    </strong>
  </noscript>

  <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,
      "panelheadings": 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
      }
    },
    "panels": [
      {
        "connector": [1],
        "panel_label": "Contents",
        "show": true,
        "toggle": true
      },
      {
        "connector": [3],
        "panel_label": "Image",
        "show": true,
        "toggle": true
      },
      {
        "connector": [4],
        "panel_label": "Text",
        "show": true,
        "toggle": false
      },
      {
        "connector": [2],
        "panel_label": "Metadata",
        "show": true,
        "toggle": true
      }
    ],
    "rtl": false,
    "standalone": true
  }
  </script>

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

Note: Please make sure to provide a valid entrypoint that points to the manifest / collection that you want to be displayed.

Getting Started (Developers)

Prerequisites

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

  • curl
  • npm
  • nvm

Note:

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.

Environment setup

Set up nvm and the recent stable version of node.js 

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.

Set up global project requirements via npm 

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

Clone the repository

git clone git@gitlab.gwdg.de:subugoe/emo/Qviewer.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 typing:

cd /path/to/projectdir
npm install

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

Usage

development mode (hot reloading, error reporting, etc.)

npm run dev

(usually located at: localhost:8080 since this port isn't already occupied)

Linting 

npm run lint            # to lint all the files at once
npm run lint:js         # to lint js files only
npm run lint:markdown   # to lint the markdown
npm run lint:scss       # to lint the styles
npm run lint:vue        # to lint vue files only

Testing 

npm run test:unit

The Viewer makes use of jest in collaboration with the expect-library.
Tests reside under tests/unit/specs/ and are supposed to have a file ending of either *.test.js or *.spec.js.

Building the app for production

npm run build

Note: The complete build is located at /dist/spa/.

Configuration

The Viewer is build with Vue.js and Quasar. If you want to change the Quasar configuration, please refer to their respective docs (Configuring quasar.conf.js).

You can fully customize the Viewer's behaviour:

There are options to

  • change the color scheme
  • show or hide individual bars (info, navigation, toggles)
  • group multiple components inside a single panel
  • set the order of the panels
  • rename labels and / or panel headings
  • filter individual metadata fields
  • and more ...

As a rule of thumb, each key with a boolean value (e.g. true or false) defaults to true and denotes to show the appropriate element.

  <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,
      "panelheadings": 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
      }
    },
    "panels": [
      {
        "connector": [1],
        "panel_label": "Contents",
        "show": true,
        "toggle": true
      },
      {
        "connector": [3],
        "panel_label": "Image",
        "show": true,
        "toggle": true
      },
      {
        "connector": [4],
        "panel_label": "Text",
        "show": true,
        "toggle": false
      },
      {
        "connector": [2],
        "panel_label": "Metadata",
        "show": true,
        "toggle": true
      }
    ],
    "rtl": false,
    "standalone": true
  }
  </script>

Note: It's a JSON object. So if you are going to make any changes and you have to quote these (e.g. see labels or colors), please use double quotes only.

The Keys in Detail

  • entrypoint

    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)

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

  • colors

    Set the colors used in the frontend.

    primary and accent should be a darker tone, so that white text is visible if used as background. It's the other way around with secondary.

    Hex values (like #a1a1a1) or color names (like hotpink) are fine.

    If any value is left blank (e.g. "primary": "",), a default color scheme will be used.

  • headers

    • all

      set this value to false if you want to completely switch off all the headerbars at once.
      This value takes precedence over the other header-keys.
      If it is 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)

    • info

      set this value to false if you want to switch off the Infobar (a.k.a. breadcrumbs)

    • navigation

      set this value to false if you want to switch off the NavBar

    • panelheadings

      set this value to false if you want to switch off the panels' headings respectively

    • toggle

      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.

  • 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.
      This change affects the captions of the navbuttons located in the headerbar and the metadata section.

      Defaults to Sheet.

    • manifest:

      Same as for item but related to the manifest title.

      Defaults to Manuscript.

  • meta

    set either of the values to false to switch it off. if you set an all-key to false the other fields within the same object aren't taken into account.

    e.g. neither of collector, description and title will be displayed:

    "meta": {
  "collection": {
    "all": false,
    "collector": true,
    "description": true,
    "title": true
  }
}

  • rtl (right to left)

    refers to the direction the text inside the text panel will be displayed.

    set the value to true if you want text to be displayed from right to left; e.g. Arabic.

    Defaults to false.

  • standalone

    denotes if the Viewer will be used as a single page application 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.

Configure the Panels

"panels": [
  {
    "connector": [1],
    "panel_label": "Contents",
    "show": true,
    "toggle": true
  },
  {
    "connector": [3],
    "panel_label": "Image",
    "show": true,
    "toggle": true
  },
  {
    "connector": [4],
    "panel_label": "Text",
    "show": true,
    "toggle": false
  },
  {
    "connector": [2],
    "panel_label": "Metadata",
    "show": true,
    "toggle": true
  }
],

The panel-array consists of four objects according to the maximum number of panels, that can be shown at once.

Each object inside that constant consists of similar keys: connector, pane_label and show.

The Panel Keys in Detail

  • connector

    The numbers below reflect each component's (Text, Image, Meta, ...) id.

    • 1 = Treeview
    • 2 = Metadata
    • 3 = Image
    • 4 = Text
    • 5 = Annotations

    Note: These IDs are supposed to be unique, so please make sure not to repeat these!

    Example given:

    Assuming you want to combine the Metadata, Text and Annotations panels, the configuration could look like this:

      {
    connector: [2, 4, 5],
    panel_label: 'Meta, Text & Anno',
    show: true
  }

  • panel_label

    refers to the heading in each panel's toolbar. To rename it, change the corresponding panel_label according to your needs.

    Note: Please make sure to also change the name, if you are going to reorder the panels or turn them into tabs.

  • show

    toggles (show or rather hide) the appropriate panel respectively

  • toggle

    whether to show the related panel toggle or not

    Defaults to true.

Note:

Viewer Components

Viewer components

Dockerfile

The dockerfile is used for GitLab CI.
It needs to be updated when either node or quasar-cli should be updated.

docker build --pull -t docker.gitlab.gwdg.de/subugoe/emo/qviewer/node .
docker push docker.gitlab.gwdg.de/subugoe/emo/qviewer/node

Connecting the Viewer to a Backend

The viewer expects JSON that complies to the SUB's generic TextAPI 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:

"entrypoint": "https://{server}{/prefix}/{collection}/collection.json"

The entrypoint should point to the collection you want to be displayed.

Architecture

Architecture diagram of TIDO

Contributing

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

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

See the list of contributors who participated in this project.