Commons

is a group of classes that build upon the TYPO3 API, adding Kitodo-specific functions, such as handling METS structures and library metadata in various formats, or linking external resources, such as OAI-PMH interfaces or Solr search engines. The API extensions are available to all TYPO3 extensions, which means that they can be used not only by Kitodo.Presentation, but by other extensions as well. Thus, commercial or other very specific functions, which are only necessary in single installations, don't need to be part of the official Kitodo.Presentation release, but can be created as separate extensions.

Modules

is a group of components that are integrated into the TYPO3 backend and manage the configuration of extensions as well as of digital resources, clients and collections. Currently, there is a module for client management as well as integrations with the basic TYPO3 list module to manage the digital resources. In addition, they enable a highly granular configuration of structure and metadata handling as well as database management. Furthermore, a command line interface is provided, which allows automation of procedures, such as importing digital resources.

Plugins

are components that build the frontend output and provide various functions. All plugins can be precisely configured via GUI and freely dropped into TYPO3-managed web pages. All frontend outputs are based on design templates and are thus fully customizable.

Screenshots

Some examples of Kitodo.Presentation in action on the Digital Collection of SLUB Dresden:

https://digital.slub-dresden.de/id457052678

https://digital.slub-dresden.de/id416971482-19060601

https://digital.slub-dresden.de/id501434038

https://digital.slub-dresden.de/id501434038-1942

Composer Mode

It is highly recommended to install this extension by using composer. This is the only supported way.

Please run the following commands in your webroot where the TYPO3 composer.json is located:

1. Fetch Kitodo.Presentation with Composer

   composer require kitodo/presentation

   Copied!

2. Install and Activate the Extension

   ./vendor/typo3 extension:activate dlf

   Copied!

Version 3.3 -> 4.0

// Before
plugin.tx_dlf_pageview {
  features = OverviewMap
}

// After
plugin.tx_dlf_pageview {
  settings {
    features = OverviewMap
  }
}

page 1: Search Plugin (main column)
   |
   v
   +--> page 2: ListView Plugin (main column) | Search Plugin (sidebar) e.g with forceAbsoluteUrlHttps
   ^
   |
page 3: Collection Plugin (main column)

// Before
lib.imagemanipulation < tt_content.list.20.dlf_imagemanipulationtool

// After
lib.imagemanipulation < tt_content.list.20.dlf_toolbox {
  settings {
    tool = imagemanipulationtool
  }
}

Version 3.2 -> 3.3

Version 3.3 introduce the usage of the OCR Highlighting Plugin for Solr. The plugin can be found at GitHub: https://github.com/dbmdz/solr-ocrhighlighting. This plugin is now mandatory if you are using the full text feature.

Please note: The full text is stored in Solr index in a XML format (MiniOCR). This will rise the demand for storage space. You should therefore monitor the disc usage during reindexing.

Version 5.0 -> 5.1

Version 5.1 supports Apache Solr 9 (9.4+) now, a revised configuration for Apache Solr 8 (8.11+) is included and support for Apache Solr 7 and earlier is dropped.

Content Security Policy

In case a Content Security Policy is set on the Kitodo.Presentation instance, make sure that blob: URLs are allowed as img-src. Otherwise, the page view may remain blank.

Extension Configuration

You should check the extension configuration!

• go to the Extension Configuration (ADMIN TOOLS -> Settings -> Extension Configuration).
• open dlf
• check and save the configuration

Tenant Configuration

You must create a data folder for some Kitodo.Presentation configuration records like metadata, structures, solrCore and formats (namespaces). This can be achieved easily with the 'New Tenant' backend module on the left side in section 'Tools'.

Make sure, all fields are green. Then all necessary records are created.

TYPO3 Configuration

Disable caching in certain situations

Navigation Plugin

The navigation plugin provides a page selection dropdown input field. The resulting action url cannot contain a valid cHash value.

The default behaviour of TYPO3 is to call the pageNotFound handler and/or to show an exception:

This is not the desired behaviour. You should disable $TYPO3_CONF_VARS['FE']['pageNotFoundOnCHashError'] = 0 to show the requested page instead. The caching will be disabled in this case. This was the default behaviour before TYPO3 6.x.

This configuration is written to typo3conf/LocalConfiguration.php:

'FE' => [
        'pageNotFoundOnCHashError' => '0',
    ],

Copied!

Avoid empty Workview

You may notice from time to time, the viewer page stays empty even though you pass the tx_dlf[id] parameter.

This happens, if someone called the viewer page without any parameters or with parameters without a valid cHash. In this case, TYPO3 saves the page to its cache. If you call the viewer page again with any parameter and without a cHash, the cached page is delivered.

With the search plugin or the searchInDocument tool this may disable the search functionality.

To avoid this, you must configure tx_dlf[id] to require a cHash. Of course this is impossible to achieve so the system will process the page uncached.

Add this setting to your typo3conf/LocalConfiguration.php:

'FE' => [
    'cacheHash' => [
        'requireCacheHashPresenceParameters' => [
            'tx_dlf[id]',
        ],
    ],
]

Copied!

Tip: Use the admin backend module: Settings -> Configure Installation-Wide Options

routeEnhancers:
  KitodoWorkview:
    type: Plugin
    namespace: tx_dlf
    limitToPages:
      - 14
    routePath: '/{id}/{page}'
    requirements:
      id: '(\d+)|(http.*xml)'
      page: \d+
  KitodoWorkviewDouble:
    type: Plugin
    namespace: tx_dlf
    limitToPages:
      - 14
    routePath: '/{id}/{page}/{double}'
    requirements:
      id: '(\d+)|(http.*xml)'
      page: \d+
      double: '[0-1]'

Common Settings

Fluid Template Configuration

As of Kitodo.Presentation 4.0 the Fluid rendering engine is used. The former marker templates for plugins are not supported anymore.

Now, all HTML markup is done in Fluid. To use different templates, you have to overload the templates by the common TYPO3 way.

The following TypoScript defines additional paths inside an "example" extension:

plugin.tx_dlf {
   view {
      templateRootPaths {
         10 = EXT:example/Resources/Private/Plugins/Kitodo/Templates
      }
      partialRootPaths {
         10 = EXT:example/Resources/Private/Plugins/Kitodo/Partials
      }
   }
}

In this example, you place the customized fluid template into this file:

EXT:example/Resources/Private/Plugins/Kitodo/Partials/Navigation/Main.html

Audioplayer

The audioplayer plugin is only active if the selected document has valid audio file use groups (useGroupsAudio).

Basket

plugin.tx_dlf_basket.

Calendar

The calendar plugin may be used with newspaper and ephemeras (periodical published media). The plugin shows itself an overview of all available years or all issues in a calendar view of a selected year.

You can't place the plugin together with the pageview plugin on one page. But you can use TypoScript conditions on this page to select the proper plugin e.g by setting some specific FLUID variables.

This is an example usage of the TypoScript condition ("getDocumentType"):

[getDocumentType({$config.storagePid}) === 'ephemera' or getDocumentType({$config.storagePid}) === 'newspaper']
page.10.variables {
    isNewspaper = TEXT
    isNewspaper.value = newspaper_anchor
}
[END]

[getDocumentType({$config.storagePid}) === 'year']
page.10.variables {
    isNewspaper = TEXT
    isNewspaper.value = newspaper_year
}
[END]

[getDocumentType({$config.storagePid}) === 'issue']
page.10.variables {
    isNewspaper = TEXT
    isNewspaper.value = newspaper_issue
}
[END]

The {$config.storagePid} is a TypoScript constant holding the Kitodo.Presentation storage pid.

This way, the FLUID variable "isNewspaper" is set according to the given value. Inside the FLUID template it's possible to switch to the right plugin now.

plugin.tx_dlf_calendar.

Collection

The collection plugin shows one collection, all collections or selected collections.

plugin.tx_dlf_collection.

Embedded 3D Viewer

The embedded3dviewer plugin renders an iFrame in which the configured 3D viewer displays the model.

plugin.tx_dlf_embedded3dviewer.

Feeds

The feeds plugin renders a RSS 2.0 feed of last updated documents of all or a specific collection.

The following steps are necessary to activate the plugin:

a. Create a new page "Feed" with slug "feed". b. Create an extension template on this page and include the TypoScript template of the feeds plugin. c. Place the "Kitodo Feeds" plugin on it and configure it for your needs.

The TypoScript part is necessary to switch the page rendering to a different page object.

plugin.tx_dlf_feeds.

List View

plugin.tx_dlf_listview.

Media Player

The mediaplayer plugin is only active if the selected document has valid video file use groups (useGroupsVideo).

plugin.tx_dlf_mediaplayer.

Metadata

plugin.tx_dlf_metadata.

Navigation

plugin.tx_dlf_navigation.

OAI-PMH

plugin.tx_dlf_oaipmh.

Page Grid

plugin.tx_dlf_pagegrid.

Page View

plugin.tx_dlf_pageview.

Search

plugin.tx_dlf_search.

Statistics

plugin.tx_dlf_statistics.

Table Of Contents

plugin.tx_dlf_tableofcontents.

Toolbox

plugin.tx_dlf_toolbox.

Validation Form

The plugin renders an input field where a METS URL can be entered. After submission, the document is loaded and validated against the DOMDocumentValidation Middleware. For the validation to work, a corresponding configuration (see Configuration) must be present in TypoScript, and the type of this configuration must be provided to the plugin as a required parameter.

plugin.tx_dlf_validationform.

Index single document

The command kitodo:index is used for indexing a single document:

./vendor/bin/typo3 kitodo:index -d http://example.com/path/mets.xml -p 123 -s dlfCore1

Reindex collections

With the command kitodo:reindex it is possible to reindex one or more collections or even to reindex all documents on the given page.:

# reindex collection with uid 1 on page 123 with solr core 'dlfCore1'
# short notation
./vendor/bin/typo3 kitodo:reindex -c 1 -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --coll 1 --pid 123 --solr dlfCore1

# reindex collection with uid 1 on page 123 with solr core 'dlfCore1' in given range
# short notation
./vendor/bin/typo3 kitodo:reindex -c 1 -l 1000 -b 0 -p 123 -s dlfCore1
./vendor/bin/typo3 kitodo:reindex -c 1 -l 1000 -b 1000 -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --coll 1 --index-limit=1000 --index-begin=0 --pid 123 ---solr dlfCore1
./vendor/bin/typo3 kitodo:reindex --coll 1 --index-limit=1000 --index-begin=1000 --pid 123 --solr dlfCore1

# reindex collection with uid 1 and 4 on page 123 with solr core 'dlfCore1'
# short notation
./vendor/bin/typo3 kitodo:reindex -c 1,4 -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --coll 1,4 --pid 123 --solr dlfCore1

# reindex collection with uid 1 and 4 on page 123 with solr core 'dlfCore1' in given range
# short notation
./vendor/bin/typo3 kitodo:reindex -c 1,4 -l 1000 -b 0 -p 123 -s dlfCore1
./vendor/bin/typo3 kitodo:reindex -c 1,4 -l 1000 -b 1000 -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --coll 1,4 --index-limit=1000 --index-begin=0 --pid 123 ---solr dlfCore1
./vendor/bin/typo3 kitodo:reindex --coll 1,4 --index-limit=1000 --index-begin=1000 --pid 123 --solr dlfCore1

# reindex all documents on page 123 with solr core 'dlfCore1' (caution can result in memory problems for big amount of documents)
# short notation
./vendor/bin/typo3 kitodo:reindex -a -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --all --pid 123 --solr dlfCore1

# reindex all documents on page 123 with solr core 'dlfCore1' in given range
# short notation
./vendor/bin/typo3 kitodo:reindex -a -l 1000 -b 0 -p 123 -s dlfCore1
./vendor/bin/typo3 kitodo:reindex -a -l 1000 -b 1000 -p 123 -s dlfCore1
# long notation
./vendor/bin/typo3 kitodo:reindex --all --index-limit=1000 --index-begin=0 --pid 123 ---solr dlfCore1
./vendor/bin/typo3 kitodo:reindex --all --index-limit=1000 --index-begin=1000 --pid 123 --solr dlfCore1

Harvest OAI-PMH interface

With the command kitodo:harvest it is possible to harvest an OAI-PMH interface and index all fetched records.:

# example
./vendor/bin/typo3 kitodo:harvest --lib=<UID> --pid=<PID> --solr=<CORE> --from=<timestamp> --until=<timestamp> --set=<set>

In order to use the command, you first have to configure a library in the backend, setting at least a label and oai_base. The latter should be a valid OAI-PMH base URL (e.g. https://digital.slub-dresden.de/oai/).

Delete single document

The command kitodo:delete is used for deleting a single document:

./vendor/bin/typo3 kitodo:delete -d http://example.com/path/mets.xml -p 123 -s dlfCore1

Commit and/or optimize index

With the command kitodo:optimize it is possible to hard commit documents to and/or optimize the index.:

# example
./vendor/bin/typo3 kitodo:optimize --solr=<CORE> --commit --optimize

F-1-1 Metadata Search

F-1-1-1 Extended Search

Due to the document structure in the Solr index, you cannot combine the Full Text Search with the Extended Search.

F-1-3 Full Text Search

F-1-4 Facet Search

F-1-5 Search In Document

Basic Features

• Zoom and rotate

  • Buttons from Digital Collections template
  • Stepless: Drag the image while pressing Shift.
  • Zoom via mouse wheel
  • Zoom via + and - keys

• Pan the image

  • Pan by mouse dragging
  • Pan via arrow keys

Image Manipulation

In the Digital Collections template, activate the tool by clicking the slider button.

Full Text

In the Digital Collections template, the following full text features are available:

• Click the reading-glass icon on the left to toggle the fulltext overlay. When hovering a text line on the image, the corresponding part should be highlighted in the overlay.
• When showing an indexed document, click the search icon on the right to toggle in-document search. Search results should be highlighted on the page.
• In single page mode, click the download link and select "Fulltext page (TXT)" to download the raw text.

Overview Map and Zoom Buttons

Additional OpenLayers controls may be configured in TypoScript:

plugin.tx_dlf_pageview {
  settings {
    features = OverviewMap,ZoomPanel
  }
}

These are created in dlfViewer::createControls_().

Loading Indicator

A progress element may be configured to be used as loading indicator for static images. This requires CORS and possibly a non-mixed context, and the server must send a Content-Length header.

In TypoScript, set progressElementId to the ID of the <progress> element:

plugin.tx_dlf_pageview {
    settings {
        progressElementId = tx-dlf-page-progress
    }
}

The element may be placed anywhere on the page.

<progress id="tx-dlf-page-progress"></progress>

For styling, the CSS class loading is added whenever the loading indicator is in use:

#tx-dlf-page-progress {
    visibility: hidden;
}

#tx-dlf-page-progress.loading {
    visibility: visible;
}

Tools for Basket Plugin

There are additional tools for the basket plugin:

• Magnifier: Show zoomed page at mouse location in a separate panel.
• Cropping Tool: Select a region that should be added to the baseket.

To insert links for activating these tools into the default PageView template, the following settings may be used:

plugin.tx_dlf_pageview {
  settings {
    basket {
      magnifier = 1
      crop = 1
    }

    // The basket must be configured for these settings to take effect
    basketButton = 1
    targetBasket = 123
  }
}

Supported Formats

For adaptive bitrates, media content may be provided using either MPEG-DASH manifests or Apple HLS playlists (or both). While MPEG-DASH can nowadays be used in most browsers (via Media Source Extensions), HLS is still required for some iOS devices.

As a fallback or when adaptive bitrate streaming is not necessary, you may also supply a raw media file (such as MP3). What codecs can be used generally depends on the user's browser.

For more details on supported formats, see https://github.com/shaka-project/shaka-player.

MPEG-DASH

Add a separate <AdaptationSet> for each video track. In order to uniquely identify the track, the adaptation set must contain a special role ascription:

<Role schemeIdUri="urn:mpeg:dash:role:2011" value="dlf:key=TRACK_ID_HERE"/>

When adding a thumbnail adaptation set, it must contain the same role ascription to match it with the video track.

Other roles may be used:

• dlf:label=TEXT: Specify TEXT as a label that is shown to the user. If no label is given, the track ID is shown instead.
• dlf:label_XX=TEXT: Localized label, where XX is replaced by the two-letter ISO code of the langauge.

• Using prefix#group to match streams to video tracks
• WIP/TODO: Using <Label> and dlf:label role to set label of video track. (multiple languages?)

HLS

Similarly to MPEG-DASH, set the roles in the CHARACTERISTICS attribute of the video media and the thumbnail streams.

MPEG-DASH

<AdaptationSet mimeType="image/jpeg" contentType="image">
  <Representation bandwidth="2500" id="thumbnails_80x45" width="1600" height="900">
    <SegmentTemplate media="https://www.example.com/$RepresentationID$/tile_$Number$.jpg" duration="400" startNumber="1"/>
    <EssentialProperty schemeIdUri="http://dashif.org/thumbnail_tile" value="20x20"/>
  </Representation>
  <Representation bandwidth="5000" id="thumbnails_160x90" width="1601" height="900">
    <SegmentTemplate media="https://www.example.com/$RepresentationID$/tile_$Number$.jpg" duration="100" startNumber="1"/>
    <EssentialProperty schemeIdUri="http://dashif.org/thumbnail_tile" value="10x10"/>
  </Representation>
</AdaptationSet>

Basic

Generally speaking, syntax is oriented at the native <video> tag. Here is a simple example:

<dlf-media poster="https://www.example.com/poster.jpg" start="10">
  <source src="https://www.example.com/manifest.mpd" type="application/dash+xml">
  <source src="https://www.example.com/playlist.m3u8" type="application/x-mpegurl">
  <source src="https://www.example.com/static.mp4" type="video/mp4">
</dlf-media>

As with native videos, the sources are tried in order, and the first one that is supported is played. The MIME type must always be given. The poster image, if given, is shown until playback is first started.

Chapter Markers

To add chapter markers, use the <dlf-chapter> tag:

<dlf-media>
  <!-- snip: sources -->

  <dlf-chapter timecode="0" title="First"></dlf-chapter>
  <dlf-chapter timecode="23.5" title="Second"></dlf-chapter>
</dlf-media>

The timecode is given in seconds. Fractional numbers are possible.

Player Mode

There are two attributes to control player mode:

• mode: Either audio or video to use a fixed mode, or auto (default) to auto-determine the mode based on media content.
• mode-fallback: When setting mode="auto", this is the initial mode used until the media type is determined. To avoid flicker due to mode switching, it is best if the fallback mode already matches the media type.

<dlf-media mode="auto" mode-fallback="video">
  <!-- snip -->
</dlf-media>

Control Elements

To add control elements to the player, use the <dlf-media-controls> tag.

<dlf-media-controls>
  <!-- Use a predefined button via "data-type" -->
  <button data-type="volume"></button>
  <button data-type="mute"></button>
  <button data-type="fullscreen"></button>
  <!--
    Define a custom button:
    * data-t-title: Translation key of tooltip
    * data-action: Key for onclick action
  -->
  <button
   class="material-icons-round sxnd-help-button"
   data-t-title="control.help.tooltip"
   data-action="modal.help.open"
  >
    info_outline
  </button>
</dlf-media-controls>

Player View

The ID of a container element may be specified in player-view:

• The element is used when switching to full screen, so that additional elements besides the player may be used.
• It can be used to make sure that modals are sized and positioned appropriately even in audio mode.

<div id="tx-dlf-view" class="tx-dlf-view">
  <dlf-media player-view="tx-dlf-view">
    <!-- snip -->
  </dlf-media>
</div>

More

• end
• config

Metadata

Video metadata may be provided in the <dlf-meta> tag. This is used, for example, to imprint the video title on screenshots.

<slub-media>
  <!-- snip: sources -->

  <dlf-meta key="title" value="Schattensucher"></dlf-meta>
</slub-media>

Plugins

If you would like to extend the player, one way is to write a "player plugin". This is intended for situations where you would like to add functionality by using the existing DlfMediaPlayer API. It is, for example, used to provide an table to a marker table that connects to a player instance. Roughly:

class MarkerTable extends DlfMediaPlugin {
  constructor() {
    super();
  }

  /**
   * @override
   * @param {DlfMediaPlayer} player
   */
  attachToPlayer(player) {
    // Optionally, check player specifics
    if (!(player instanceof SlubMediaPlayer)) {
      return;
    }

    // Here you have access to all attributes and
    // DOM elements inside the custom element

    // Add actions that can be referenced in control elements or keybindings
    player.addActions({
      'marker-table.action': {
        isAvailable: () => {
          // Optionally, check preconditions for the action. If the action is not available,
          // the control element will be hidden, and the help entry will be grayed out.
          return true;
        },
        execute: () => {
          // ...
        },
      },
    });

    // Access the <media> element that underlies the player
    player.media.addEventListener('loadedmeta', () => {
      // ...
    });

    // Access the player environment, e.g., to translate a string
    const btn = document.createElement('button');
    btn.textContent = this.env.t('marker-table.button-text');
  }
}

customElements.define('dlf-marker-table', MarkerTable);

A plugin is attached to a player via the forPlayer attribute:

<dlf-marker-table forPlayer="playerOne"></dlf-marker-table>

<dlf-media id="playerOne">
  <!-- snip -->
</dlf-media>

Subclassing

If you would like to make more pervasive changes to the player, or if you would like to provide a player element containing all your customizations, you may also inherit from DlfMediaPlayer. This is done in SlubMediaPlayer to define an extended <slub-media> element.

class MyMediaPlayer extends DlfMediaPlayer {
  constructor() {
    super();
  }

  connectedCallback() {
    super.connectedCallback();
  }
}

customElements.define('my-media', MyMediaPlayer);

For styling, use the Less function dlf-media-base:

my-media {
  .dlf-media-base();
}

The new element <my-media> may then be used just as <dlf-media>, plus any additional attributes or child elements that you query within MyMediaPlayer.

lib

The lib/ folder contains functionality that either is used throughout or isn't strictly related to the player.

Notably, class Environment encapsulates quasi-global state such as the set of language strings. An instance of this is constructed at startup and passed down to where it is needed (in variables named env).

DlfMediaPlayer

class DlfMediaPlayer is the core player. It integrates Shaka Player, loads and plays media, and provides a UI.

class ShakaFrontend encapsulates the visible part of the player UI. It is based upon Shaka Player UI, configuring it and replacing, for example, the seek bar with a custom one (FlatSeekBar).

ShakaFrontend implements the interface dlf.media.PlayerFrontend, which I originally introduced when planning to write a separate frontend class for the audio player. This plan got dropped, and instead the frontend distinguishes between video and audio mode. Still, the interface is kept to help make sure the frontend handling isn't too reliant on Shaka internals.

SlubMediaPlayer

class SlubMediaPlayer derives from DlfMediaPlayer to customize and extend it, and to integrate it into the the Digital Collections page view. Currently, its tasks are:

• Read the initial timecode from the URL and pass it to DlfMediaPlayer.
• Integrate with the table of contents and page select (jump to chapter markers, highlight current chapter).
• React to keyboard events, using actions defined in DlfMediaPlayer.
• Add help, screenshot and bookmark modal.

Consideration/TODO: It may make sense to move some of this functionality into DlfMediaPlayer.

Localization

The player can be localized via TYPO3/XLIFF language files.

• There is a separate language file for the media player related translation strings. The file is located at dlf/Resources/Private/Language/locallang_media.xlf.

• Translation strings use the ICU MessageFormat syntax, which in particular supports pluralization, enumerations (via select), number formatting (e.g., percentages), and named placeholders. On the client, the strings are processed using the Intl MessageFormat library from FormatJS.

  (Consideration/TODO: Pre-process translation strings into JavaScript functions to dispense of the library and reduce bundle size.)

• The translations are collected and serialized into a JSON string in the MediaPlayerConfigViewHelper. The result array also contains the two-letter ISO code, which is passed to Shaka Player's UI.

• To access translation in the application, Environment is used:

  • Environment::setLang() is called at startup to store the translations.
  • Environment::t() translates a message key.

Keybindings

The keyboard shortcuts are registered in the top-level component to allow fine control of which component receives them. Existing keybindings (e.g., from Shaka Player) are disabled or overridden as far as possible.

The available keybindings are listed in keybindings.json:

• The result object is an array of type Keybinding, which is defined and documented in SlubMediaPlayer/types.d.ts.
• Keys are bound to an action, which are defined in DlfMediaPlayer::getActions() and extended in SlubMediaPlayer::getActions().
• Event handlers are registered in SlubMediaPlayer::configureFrontend().

Gestures

• The class Gestures defines the mechanics of several standard gestures (multi-tap, tap-and-hold, swipe).
• The available gestures are currently registered in DlfMediaPlayer::registerGestures(), which accesses a Gestures object on ShakaFrontend.
• ShakaFrontend constructs the Gestures object, registers event handlers on an appropriate DOM element, and checks whether or not a particular gesture is allowed (most importantly, to forbid gestures in the control button area).

DOM Handling

Generally speaking, DOM construction and manipulation is done in a "vanilla" way, though with some utilities to make this less tedious.

lib/util.js defines a utility function e() (e for "element") for constructing DOM elements and trees.

Overview

• Webpack 5 is used for building. Configuration file: /Build/webpack.config.js.
• Jest is used for unit tests. Configuration is embedded in /Build/package.json.
• TypeScript-flavored JSDoc and the TypeScript compiler are used for static typing. Configuration file: /jsconfig.json
• ESLint (eslint-plugin-compat) and Babel (via Webpack) are used to check and improve browser compatibility.

Webpack Dev Server

The Dev Server is intended for developing and testing the media player in a well-defined, standalone environment.

• To start the server, run npm run serve in the Build/ folder. This will watch, recompile and reload when source files change; other builds should not be run simultaneously.

• The live JavaScript and CSS builds are available at /JavaScript and /Css, for example:

  <script src="/JavaScript/DlfMediaPlayer/DlfMediaPlayer.js"></script>

  Copied!
• The server is configured in the devServer key in /Build/webpack.config.js.
• Resources to be served are located in Build/Webpack/DevServer/. This contains a symlink to /Resources, so that all resources can be accessed from a served page via a repository-relative path.

Command Reference

cd Build/

# Install/Use Node
nvm install
nvm use

# Install dependencies
npm ci

# Build in watch/development mode
npm run watch
# Build in production mode
npm run build
# Start Webpack Dev Server
npm run serve

# Check static types
npm run typecheck
# (Alternative) Watch mode
npm run tsc-watch

# Run unit tests
npm test
# (Alternative) Watch mode
npm test -- --watch
# With coverage report
npm test -- --coverage
xdg-open coverage/lcov-report/index.html

# Check browser compatibility
# - in source files:
npm run compat
# - in built files:
npm run compat-build

Testing

For testing that the equalizer produces a correct frequency response, check the "Equalizer Test" page (https://localhost:9000/equalizer.html) hosted in Webpack Dev Server, which plays sine waves at constant amplitudes and renders the FFT.

Class Overview

• EqualizerPlugin: Player plugin to set up the equalizer and connect it to an instance of DlfMediaPlayer.

  • EqualizerView: User interface for display and manipulation of EQ parameters and presets of an Equalizer.
  • Equalizer: Top-level class for actual equalization. Connects to an AudioContext, adds an FFT node that is used to test the frequency response, loads presets, and delegates to implementations of specific modes/filtersets (BandEq and RiaaEq).

Displaying Multiple Values

To allow TypoScript wrap to reference metadata values, all configured entries of the current metadata section are set as data before calling stdWrap. The index names are used as key. Whenever there are multiple values, they are joined by the separator that is configured in the metadata plugin.

To see where this is useful, consider the following MODS access condition.

<mods:accessCondition
   xmlns:xlink="http://www.w3.org/1999/xlink"
   type="use and reproduction"
   xlink:href="http://creativecommons.org/licenses/by-sa/4.0/"
>
    CC BY-SA 4.0
</mods:accessCondition>

In the metadata table, we may want to render an <a> tag that links to the license summary page and displays the license name as link text. To achieve this, we may create two metadata entries:

• Create a hidden entry called useandreproduction_link that has xpath set to ./mods:accessCondition[@type="use and reproduction"]/@xlink:href. This entry is used purely to extract the license URL.

• The main entry sets xpath to ./mods:accessCondition[@type="use and reproduction"] (so it extracts the license name) and uses a wrap along the lines of

  key.wrap = <dt>|</dt>
  value.required = 1
  value.typolink.parameter.field = useandreproduction_link
  value.wrap = <dd>|</dd>

  Copied!

DOMDocumentValidationStack

Kitodo\Dlf\Validation\DOMDocumentValidationStack implementation of Kitodo\Dlf\Validation\AbstractDlfValidationStack for validating DOMDocument against the configurable validators.

The configuration is an array validator configurations each with following entries:

XmlSchemasValidator

Kitodo\Dlf\Validation\XmlSchemasValidator combines the configured schemes into one schema and validates the provided DOMDocument against this.

The configuration is an array validator configurations each with following entries:

SaxonXslToSvrlValidator

Kitodo\Dlf\Validation\SaxonXslToSvrlValidator validates the DOMDocument against an XSL Schematron and converts error output to validation errors.

To use the validator, the XSL Schematron must be available alongside the XSL processor as a JAR file, and the required Java version of the processor must be installed.

Configuration

The validation middleware can be configured through the plugin settings in TypoScript with the block called domDocumentValidation. Under this block, configuration sections (referred to as type) for different validations can be defined. When directly referencing the middleware or using the Validation Form, this type must be provided as the type parameter.

plugin.tx_dlf {
    settings {
        domDocumentValidation {
            typeA {
               validator {
                  ...
               },
               validatorStack {
                  ...
               },
               ...
            },
            typeB {
               ...
            },
            ...

Copied!

Validators derived from Kitodo\Dlf\Validation\AbstractDlfValidator can be configured here. This also includes the use of validation stack implementations derived from Kitodo\Dlf\Validation\AbstractDlfValidationStack, which use DOMDocument as the valueClassName for validation. This allows for multiple levels of nesting.

In the background of the middleware, the Kitodo\Dlf\Validation\DOMDocumentValidationStack is used, to which the configured validators are assigned.

For each validator, the title and description can be defined as XLF labels and are returned in the response according to the selected site language.

The description label can include placeholders. The syntax changes slightly in this case: a separate block is used for the description, consisting of the XLF label as the key and an additional block containing arguments. These arguments are then inserted into the placeholders within the label in the given order. The EXT: prefix can also be used as an argument value, which will be replaced with the corresponding extension path.

plugin.tx_dlf {
    settings {
       domDocumentValidation {
           typeA {
              10 {
                 title = LLL:EXT:.../locallang.xlf:title
                 description = LLL:EXT:.../locallang.xlf:description
              }
              ...
           },
           typeB {
                10 {
                    title = LLL:EXT:.../locallang.xlf:title
                    description {
                        key = LLL:EXT:.../locallang.xlf:description
                        arguments {
                            0 = EXT:...
                            1 = Test
                            ...
                        }
                    }
                    ...

Copied!

Automatic selection of the viewer

Under the configuration of the dlf extension, you will find a tab to configure embedded 3D viewer implementation for automatic selection of 3D viewer.

With the configuration field "Viewer model format mapping," you can define a list of considered viewers from the dlf_3d_viewers folder along with their associated model formats. If there are multiple viewers that support the same model format, you can decide here which one is responsible for the specific format.

Additionally, a default viewer can be set, which serves as a fallback for all model formats that have not been mapped.

dlf-3d-viewer.yml

To configure the 3D viewer for Kitodo.Presentation, a dlf-3d-viewer.yml file must be present in the viewer directory.

viewer:
 base: main.html
 supportedModelFormats:
   - glf
   - ply

Placeholders

Placeholders can be used within the file which is define under the base key of dlf-3d-viewer.yml. The notation for placeholders is {{placeholderName}}. The following placeholders are available: