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:

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

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

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

http://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 a valid audio filegroup (fileGrpAudio).

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.

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.

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

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:

XmlSchemesValidator

Kitodo\Dlf\Validation\XmlSchemesValidator 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 domDocumentValidationValidators.

plugin.tx_dlf {
    settings {
        domDocumentValidationValidators {
            validator {
               ...
            },
            validatorStack {
               ...
            },
            ...

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.

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: