Skip to content

Renderers

The default response format for the document endpoint is XML/TEI.

The optional DTS mediaType query parameter can be used to retrieve the response (document or passage) in another format (e.g. HTML or TXT), provided that a renderer is configured.

A renderer can provide different transformations and renderings (CSS, XSLT, JS) of the XML/TEI source.

Example: HTML export of the abstract of Michel Pastoureau's thesis
https://dots.chartes.psl.eu/demo/api/dts/document?resource=ENCPOS_1972_18&mediaType=html

Different renderers can be installed, and:

  • a default renderer can be configured for each mediaType value;
  • a specific renderer can be specified using the optional DoTS renderer query parameter.

Example: HTML document rendering using the teic renderer (TEI Consortium Stylesheets)
https://dots.chartes.psl.eu/demo/api/dts/document?resource=ENCPOS_1972_18&mediaType=html&renderer=teic

DoTS renderers

By default, DoTS does not provide any renderers upon installation.
However, DoTS provides documented procedures for the simplified installation of two renderers:

⌄ renderer | mediaType > tei html txt
teic-oxygen X - -
teic - X X

teic-oxygen renderer

teic-oxygen renderer is used to render documents and passages in XML/TEI. These CSS stylesheets are maintained by the TEI Consortium for display in editing mode in Oxygen XML Editor.

Install

cd dots/webapp/static/renderers/teic-oxygen

curl -o tei.css https://raw.githubusercontent.com/TEIC/oxygen-tei/refs/heads/master/oxygen-tei/frameworks/tei/xml/tei/css/tei.css
cp ../renderer_config_template.xml ../renderer_config.xml

Test

Default DTS response. XML/TEI document without rendering https://dots.chartes.psl.eu/demo/api/dts/document?resource=ENCPOS_1972_18

renderer parameter. XML/TEI document rendered using the `teic-oxygen renderer
https://dots.chartes.psl.eu/demo/api/dts/document?resource=ENCPOS_1972_18&renderer=teic-oxygen

teic renderer

The TEI Consortium maintains generic XSLT transformations for various formats: https://github.com/TEIC/Stylesheets
DoTS provides a simplified installation procedure for these stylesheets, for the HTML and TXT formats.

Install

cd dots/webapp/static/renderers/teic

git clone https://github.com/TEIC/Stylesheets.git

Edit the configuration file renderer_config.xml and uncomment the following lines:

<dots:renderers xmlns:dots="https://github.com/dots-suite/dots">
  <dots:renderer name="teic" mediaType="html" path="teic_html.xsl" default="true"/>
  <dots:renderer name="teic" mediaType="txt" path="Stylesheets/txt/tei-to-text.xsl" default="true"/>
</dots:renderers>
  • The @path attribute specifies the relative path to the transformation (i.e. path="Stylesheets/txt/tei-to-text.xsl") or to an “adapter” required for the stylesheets to work properly in the DoTS context (i.e. path="teic_html.xsl").
  • The @default attribute declares the renderer as the default renderer for the corresponding mediaType.

Test

mediaType and renderer parameters. HTML document rendered using the teic renderer
https://dots.chartes.psl.eu/demo/api/dts/document?resource=racine_andromaque&mediaType=html&renderer=teic

mediaType and renderer parameters. TXT export using the teic renderer
https://dots.chartes.psl.eu/demo/api/dts/document?resource=racine_andromaque&mediaType=txt&renderer=teic

Custom renderers

To create a custom renderer, e.g. for HTML5 export and rendering, simply:

1. Create the dots/webapp/static/renderers/my-custom-html-renderer directory
The directory contains the transformations and stylesheets, e.g.:

dots/webapp/static/renderers/
    my-custom-html-renderer/
        tei2html.xsl                # XML/TEI and dts:wrapper element processing
        theme/                      # some js + css for presentation

2. Edit the renderer_config.xml configuration file
The renderer can be configured as the default renderer for the html mediaType, e.g.:

<dots:renderers xmlns:dots="https://github.com/dots-suite/dots">
  <dots:renderer name="my-custom-html-renderer"
    mediaType="html"
    path="tei2html.xsl"
    default="true"/>
</dots:renderers>

Project renderers and overrides

For each project (top-level DTS collection), it is possible to:

  • configure a dedicated renderer;
  • override an available renderer.

In both cases, the procedure is the same.

1. Create the dots/webapp/static/transform/{project-id} directory.
Note: {project-id} MUST match the DTS identifier of the target project.

2. Add your custom XSL stylesheet {project-id}.xsl to this directory.
This XSL stylesheet will be used for all documents in the project-id collection.
You can also add CSS and JS for rendering.

For example:

dots/webapp/static/transform/
    {project-id}/
        {project-id}.xsl            # XML/TEI and dts:wrapper element processing
        theme/                      # some js + css for presentation

In dots/webapp/static/transform/{project-id}/{project-id}.xsl, you can:

  • Project renderer. Implement export and rendering logic specific to your project.
  • Renderer override. Call a renderer such as teic and define override rules.

Example. For my “theater” project, I want to use the teic renderer while defining custom templates. I simply need to edit the following XSL stylesheet: dots/webapp/static/transform/theater/theater.xsl.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:transform version="1.1"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:tei="http://www.tei-c.org/ns/1.0"
  exclude-result-prefixes="tei"
  >
  <!-- teic renderer import -->
  <xsl:import href="../../renderers/teic/teic_html.xsl"/>

  <!-- theater project custom templates -->
  <!-- add class to HTML li castItem -->
  <xsl:template match="tei:castItem">
      <li class="castItem"><xsl:apply-templates/></li>
  </xsl:template>

</xsl:transform>

Document-specific templates

To define transformations for a single document, simply edit the XSL stylesheet: dots/webapp/static/transform/{project-id}/{document-id}.xsl

  • {project-id} MUST match the DTS identifier of the target project.
  • {document-id} MUST match the DTS identifier of the target document.

This XSL stylesheet can:

  • implement export and rendering templates specific to the document;
  • call the project renderer (i.e. dots/webapp/static/transform/theater/) and define override templates;
  • call a renderer (i.e. dots/webapp/static/renderers/teic) and define override templates.