Installation Guide¶

Requirements¶

Before installing this bundle, ensure your environment meets the following requirements:

  • PHP: Version 8.1 or higher.

  • PHP Extensions: dom, mbstring, xml, xmlwriter

  • Composer: To manage dependencies.

  • Java: OpenJDK 11 or higher, required for running XSLT transformations with Saxon.

Installation¶

From the root directory of your Lodel application, declare the repository source:

$ composer config repositories.lodel/lodel-data-interoperability-bundle vcs https://github.com/operas-eu/lodel-data-interoperability-bundle.git

Then add the specific version tag vX.X.X:

$ composer require lodel/lodel-data-interoperability-bundle:vX.X.X

Make sure:

  • The tag vX.X.X exists in the GitHub repo.

  • The composer.json in that version contains the correct name:

"name": "lodel/lodel-data-interoperability-bundle"

Normally, the bundle will be automatically enabled and ready to use without requiring any additional configuration. However, if manual enabling is necessary, make sure the bundle is registered in your application as follows:

// config/bundles.php

return [
    // ...
    Lodel\DataInteroperabilityBundle\DataInteroperabilityBundle::class => ['all' => true],
];

Register routes¶

In order to enable the routes provided by this bundle, you need to explicitly import them in your Lodel application’s routing configuration. This is required because the bundle does not use automatic route import.

Create the file config/routes/lodel_data_interoperability.yaml in your application with the following content:

_lodel_data_interoperability:
    resource: '@DataInteroperabilityBundle/Resources/config/routing.yaml'

Defining transformations¶

Configuration¶

Transformations must be configured in src/Resources/config/packages/lodel_data_interoperability.yaml. Each transformation entry requires:

  • A unique identifier (the key, e.g., jatsToTei) used internally.

  • A human-readable label (label) that describes the transformation.

  • An operation type (operation) indicating whether the transformation is for import or export.

  • A list of XSLT files executed in order by Saxon. Each step processes the output of the previous one.

This structure allows chaining multiple transformation steps while keeping configuration centralized and explicit.

Example:

lodel_data_interoperability:
    (...)
    transformation:
        jatsToTei:
            label: JATS to TEI
            operation: import
            files:
                - jats_to_tei-1.xsl
                - jats_to_tei-2.xsl
        teiToJats:
            label: TEI to JATS
            operation: export
            files:
                - tei_to_jats.xsl

This example defines two transformations:

  • jatsToTei, which converts JATS XML into TEI XML using two sequential XSLT files for the import process,

  • teiToJats, which converts TEI XML back into JATS XML using a single XSLT for the export process.

Stylesheets¶

All XSLT files required for the transformation processes — including both the executable stylesheets (listed in the configuration) and any supporting/imported stylesheets — must be placed in the src/Resources/stylesheets/ directory. This ensures they are correctly located and accessible during Saxon processing.

JATS Export – Optional Twig Integration¶

If you want to add JATS export buttons directly in your content view templates, you can include the following line:

{% include '@DataInteroperabilityBundle/jats_export_buttons.html.twig' ignore missing %}

for example in:

vendor/lodel/lodel/src/Lodel/Bundle/CoreBundle/Resources/views/site/templates/views/_body.html.twig

Place it wherever you want the export buttons to appear (e.g. at the end of the content body).

This will display two buttons:

  • “View JATS” – to preview the JATS XML

  • “Download JATS” – to download the JATS file

Optional: This is not required for JATS export to work — use it only if you want to offer users quick access to the export directly in the interface.

After uninstalling the bundle, this line becomes inactive but harmless. You may leave it as is, or remove it manually if you want to keep your templates tidy.

External resources¶

Saxon script¶

The saxon-he-10.6.jar file is part of the Saxon-HE product, which is distributed under the Mozilla Public License version 2.0.