Balisage Paper: Extending the TEI Processing Model to Describe Digital Edition Interactions

Introduction

In the following paper I will discuss the question of how to extend the TEI Processing Model's (TEI PM) behaviours with interactive functionality. The TEI PM facilitates attaching behaviours to TEI XML elements (Turska, Cummings & Rahtz 2016); using these behaviours, projects can describe the desired presentation of their encoding. However, almost all behaviours that are currently available are static: there is no way for a project to describe how a user can interact with the generated site. I will discuss here some issues that arise when defining interactive behaviours and propose a number of experimental (but implemented) behaviours.

The paper is part of a project that proposes to create a fully declarative specification for the user interface of digital editions. Earlier work includes Boot 2024 and Boot [under review].^[1] Here, I begin with a brief recap of the TEI PM. Then we look at the problem formulated at a very abstract level, followed by a description of the (very concrete) interactive behaviours available in TEI Publisher, to date the only implementation of TEI PM. Then I discuss the various issues we'll have to deal with. Finally, I propose some experimental behaviours.

TEI Processing Model recapitulation

The TEI Processing Model (TEI Consortium 2026, section 23.5.4.1) makes it possible to provide a declarative specification for the presentation of XML documents.^[2] It describes a number of behaviours that can be attached to XML elements. Behaviours include general textual behaviours such as paragraph, block, and figure, as well as more specialised edition behaviours, such as alternate (inline element with default and alternate display) and note. TEI elements can be mapped to behaviours using the model element. The predicate attribute on the model element can contain an XPath expression that determines appropriate processing based on an element's position in the document.^[3] That makes it possible, for example, to handle the title of the TEI document itself (predicate="parent::titleStmt") and the titles of bibliographical items (predicate="parent::bibl") differently.

Models can have parameters (param elements) to further specify their behaviour. The most important parameter is content: if it isn't specified, the children of the currently processed element form the content of a model, but the PM can override that. For example, if we are processing a pb (page begin) element, we can use the corresponding graphic as its content. There are various hooks for attaching CSS styling, such as the cssClass attribute on the model element. The mapping of elements to behaviours is described in the TEI schema definition 'ODD' (One Document Does all) document. elementSpec elements describe the behaviours appropriate for that element. The model element that is applied is the first model where there is no predicate or where evaluation of the predicate results in true. As TEI schema definitions can import other schema definitions, it is possible to provide a set of standard behaviours for all elements, and selectively override these in the importing schema definition.

The behaviours included in the TEI PM are user-level behaviours. They offer functionality that a user would recognise and abstract away from implementation details. For example, the note behaviour takes care of the mechanics that implement the bidirectional link between the note and the note number. Although the processing might remind one of XSLT templates, the TEI PM is much closer to the world of the user. This becomes more important when we want to describe more complex aspects of edition functionality, such as interactivity.

Here are some examples. In the first example, we see that the predicate is used to distinguish the case where the TEI salute element is used inline or on its own:

                  
<elementSpec ident="salute" mode="change">
    <model predicate="parent::closer" behaviour="inline"/>
    <model behaviour="block"/>
</elementSpec>

In the following example, we see how parameters are used in the alternate behaviour. That behaviour is assigned to the choice element if it has sic and corr children (a mistake and its correction). The param's value attribute is again an XPath expression:

                  
<elementSpec ident="choice" mode="change">
    <model predicate="sic and corr" behaviour="alternate">
        <param name="default" value="corr[1]"/>
        <param name="alternate" value="sic[1]"/>
    </model>
</elementSpec>

The TEI PM is agnostic with respect to the implementation environment. Most of its behaviours could be realised on the web, in print or even in plain text. Where necessary, specific instructions for certain output environments can be created with the output attribute.

Projects that use the TEI PM will normally start from a default ODD (for instance, the ODD of the TEI simplePrint customisation or the default ODD used in TEI Publisher). They will create their own ODD that only defines those elements where they want the behaviour to be different from the default behaviour. The XML files that contain the edited texts remain untouched, they do not need to contain any processing information. The implementation will then jointly process the XML content files and the ODD files and produce the presentation.

As mentioned, TEI Publisher is an implementation of the TEI PM. TEI Publisher is used by an impressive number of edition projects. It is a tool maintained by the e-editiones non-profit organisation. Recently e-editiones announced the Open Processing Model, an initiative to create a second implementation of the TEI PM. Given the wide adoption and the existing software environment around it, TEI PM seems the natural starting point for a declarative interface specification.

The view from afar

Put at its most abstract, the issue that we discuss is how to describe changes of the digital edition from one state to another. Note that, for the purposes of this paper, we assume read-only interfaces. A state of the digital edition consists of three things: (i) the edition source data, presumably a collection of XML files, (ii) a hierarchically organised set of content panels, which I will assume are defined in HTML, combined with (iii) an internal state. The internal state can contain user preferences and other settings, as well as, for instance, a set of current search results. A change of state is a mapping from one state (source, HTML, internal state) to another. Modelling the interactive aspects of the edition implies describing how user actions trigger execution of these mappings. The user actions translate in events happening to nodes in the HTML tree. So, what we model is actually a function that maps events on nodes in the HTML tree to state transformations of the edition, that is: a new HTML tree and a new internal state. (In a read-only environment the sources remain unchanged.)

To make this more concrete, some examples:

The abstract formulation of what we are trying to achieve makes immediately clear that this task is much more complicated than what the TEI PM initially set out to do. The TEI PM currently describes a mapping of essentially a single XML source document to behaviours, which an implementation then translates into HTML. Some of these behaviours have interactive aspects (alternate, link, perhaps note) but by and large the result is a static tree. The predicate and value attributes that govern the generation of that tree contain XPath expressions that refer to a single source document. Describing interaction requires us to model the following aspects:

An example of an abstract high-level description of (modifying) user interfaces is given in the User Interface Markup Language (UIML) standard (Helms et al. 2009). UIML describes UIs in very generic terms as a hierarchy of parts under a structure element. These parts are of a certain class and these classes are meant to be mapped to the classes of specific user interface platforms such as HTML or GTK or Java Swing. parts have an id and can have various properties. Modifications of the interface (i.e., the result of interaction) are described in rules that are contained in behavior elements. Rules consist of conditions and actions. Conditions can refer to events (the occurrence of an event of a certain type to an object with a certain id) and to properties of parts, combined by simple ops (operations, such as equal, notequal, lessthan, etc.). Actions can change the values of properties, do a function call or restructure the interface. An interface restructure consists in deleting, replacing or adding structures in the parts hierarchy.

As far as I see, there are some obvious limitations to the usefulness of UIML for our case. For one thing, it doesn't describe how the user interface depends on the data that it needs to accommodate (it mentions at a very general level how this might be accomplished (page 4) but gives no details, not even that it is left to the implementation). It also describes all variation in interface construction as the result of first creating the interface and then changing it, rather than facilitating selection of parts in the initial creation of the interface. However, the ideas (i) of parts having properties that one can get and set, (ii) that one can combine with event logic using operators resulting in (iii) interface restructure operations are potentially very useful.

The view from close by

Fortunately, our modelling effort need not start at the most abstract level. There is a collection of user interface components available in TEI Publisher. Set the task of developing usable editions on the basis of the TEI PM, the creators of TEI Publisher have developed a set of web components that provide a large part of the interaction widgets without which the digital edition would be as static as its printed predecessors. These components are available in a separate library and documentation is available.^[4] Examples include:

Given the availability of these components, we could wonder whether the TEI couldn't just adopt the interactive components as defined by TEI Publisher and include these as new behaviours in the TEI Guidelines. Indeed, for some components that might be the case. But in general, I believe that we should not adopt these components wholesale but rather ask: if we would start anew, how would we design these behaviours? Maybe in some cases the TEI Publisher components, being part of a specific toolset, were designed with the choices of that toolset in mind. Or maybe in some cases the definitions include technicalities that do not belong in a more abstract specification.

Issues to consider

                     
<param name="content" value="tei:title"/>

                     
<param name="content">
    <if>
        <condition>
            <op name="equals">
                <property name="user-language" 
                        part-id="language-control"/>
                <constant type="string">nl</constant>
            </op>
        </condition>
        <then value="tei:title[@xml:lang='nl']"/> 
        <else value="tei:title[@xml:lang='en']"/> 
    </if>
</param>

                     
<elementSpec ident="title">
    <model behaviour="heading" predicate="@xml:lang=$user-language"/>
</elementSpec>

                     
<elementSpec ident="title">
    <model behaviour="heading" 
            predicate="@xml:lang=$context?user-language"/>
</elementSpec>

                     
<xsl:evaluate context-item="..." xpath="@predicate">
    <xsl:with-param name="context" select="$context"/>
</xsl:evaluate>

                     
<param name="displayiff">
    <condition>
        <property name="checked" part-id="cb-paranum"/>
    </condition>
</param>

                     
<param name="displayiff" value="$context?cb-paranum-checked"/>

Further interaction settings

Lazy or eager execution

For behaviours whose display is optional, it will usually be possible to tie their display to the state of a user interface component. If we think of the tabbed display used in the Van Gogh edition, the panel to be displayed depends on the state of the tabselector above the panels (Figure 1). In those cases, an implementation of the TEI PM will know that certain content is not needed in the initial display of the page. In other cases, it may be desirable to be able to explicitly indicate to the implementation that processing steps should be postponed until certain content is needed. And there will also be UI functionality whose display is not dependent on a specific state of a widget, e.g., most popups. For a complicated popup, we might also want to be able to provide a directive that its preparation should wait until the popup is requested.

Figure 1: Tabs in Van Gogh Letters

To indicate this situation to the implementation, it might be useful to add to the TEI model element an extra attribute loadpreference, with the values eager or lazy. The value eager directs the implementation to generate the content immediately; the value lazy means the generation should wait; without the attribute, the implementation is free to decide what seems most appropriate.

Theoretically, we could also use a param with name loadpreference rather than a model attribute. An attribute is more appropriate, I believe, because the params will only be evaluated when the decision to process a model has already been taken. An attribute can be evaluated before processing the model.

Immediate or deferred execution

Whereas the distinction between eager and lazy execution refers to the generation of a behaviour's own content, the distinction between immediate and deferred execution is relevant to behaviour widgets that govern the display of other behaviours. Suppose, for example, we have a widget that determines the sort order on our edition's persons overview page. When the user changes the desired order, is that to be effectuated immediately or only on the next page refresh?

I propose an extra param on the behaviour that defines the widget. The parameter name could be effective, its permitted values immediate or deferred. In this case the setting is only relevant if the behaviour is generated, so there is no need to define an extra attribute for the model element.

Maintaining settings

For widgets that allow users to choose certain settings for a display, we can ask another question. How permanent should these settings be? For instance, if we choose a text rendering that signals deletions and additions in the text, do we want that choice to be applied to the next text that we open? Do we want it to be applied when we come back to the text the following day? This can be indicated in another parameter, which we might call duration. Appropriate values could be page, session, browser, and user. The value user, in editions that have no login feature, would have the same effect as the value browser.

Proposed behaviours

Many of the questions that I have brought up above obviously need more discussion. One of the purposes of this paper is to get that discussion started. To provide some concrete food for thought, I propose the following behaviours: conditional-highlight, facs-link, i18n, language-control, margin-text, sort-control, sort-order, toggle.

conditional-highlight: The conditional-highlight behaviour is a minimal version of TEI Publisher's pb-highlight. It accepts the params additionalCSSClass (that describes the highlighting), key (elements with the same key will be highlighted), duration (duration of the highlight, in milliseconds), and trigger (click or mouseover). It can be activated in the following way:^[6]

                  
<model behaviour="paragraph">
    <param name="conditionalHighlight">
        <model behaviour="conditionalHighlight">
            <param name="additionalCSSClass">highlightclass</param>
            <param name="key" 
                value="concat('para',tokenize(@xml:id,'\.')[last()])"/>
            <param name="duration">1500</param>
            <param name="trigger">mouseover</param>
        </model>
    </param>
</model>

facs-link: The facs-link behaviour is inspired on TEI Publisher's pb-facs-link. Unlike pb-facs-link, it cannot, as yet, send data about a region to be highlighted in the image; it just sends the URL of the facsimile to be displayed to the facsimile behaviour. It accepts the parameters url and content.

i18n: The i18n behaviour is inspired on TEI Publisher's pb-i18n. It subscribes to changes in the language-control behaviour and when these occur, it changes the language of its text content to the new language. Currently it accepts content and language-control params. The language-control param, which points to the language-control behaviour, is probably superfluous. I should add a param for the key to be used in the translation table.^[7]

language-control: The language-control behaviour is inspired on TEI Publisher's pb-lang. At the moment, the implementation provides the information about languages that should be available. A parameter should be added to provide that information from the processing model.^[8]

margin-text: The margin-text behaviour has no equivalent in TEI Publisher. It can be used for paragraph numbers, line numbers, etc. It might also have been realised as an option on, for example, the paragraph behaviour, but a behaviour of its own seemed cleaner. Its invocation can look like this:

                  
<elementSpec ident="p">
    <model behaviour="paragraph" 
            predicate="ancestor::tei:text" cssClass="para-plus-num">
        <param name="paranum">
            <model behaviour="margin-text" 
                    cssClass="margin" conditional="yes">
                <param name="content" value="string(@n)"/>
                <param name="displayiff">
                    <epm:property 
                            part-id="showparanum" name="checked"/>
                </param>
            </model>
        </param>
    </model>
</elementSpec>

The epm:property (epm refers to the namespace for the Edition Publication Model) refers to the checked property of the widget with id showparanum.^[9] That widget is created by the toggle behaviour (see below).

sort-control and sort-order: The sort-control has no equivalent in TEI Publisher. Its only parameter at the moment is id. block behaviours that are to be sorted can refer to the id. The sort-control creates a drop-down list with the sort orders as defined on the referring block. sort-order as a behaviour has already been proposed in TEI GitHub issue 2773. That issue suggests we can leave it to the implementation to generate the sort-control. To have better control over the location of the sort-control, I now propose a separate behaviour. The sort-control behaviour is simple:

                  
<model behaviour="sortcontrol">
    <param name="id">sortselect</param>
</model>

The sort-order behaviour can be specified (repeatedly) as a parameter on the blocks that are to be sorted. The specification can have the form of the example below. Here we specify three possible orderings for an element. Each ordering is provided with a label (for the drop-down box) and a key for the sort-order.

                  
<model behaviour="block">
    ....
    <param name="sortcontrol">sortselect</param>
    <param name="ordering">
        <modelSequence>
            <model behaviour="sort-order">
                <param name="label">Date</param>
                <param name="key" 
                    value="string(analyze-string(tei:date/text(),
                        '\d{4}')/*[local-name()='match'][1]/text())"/>
                <param name="default" value="true()"/>
            </model>
            <model behaviour="sort-order">
                <param name="label">Illustration number</param>
                <param name="key" 
                    value="substring-before(
                        substring-after(
                            ./tei:head[@xml:lang='en'],'Ill. '),')')"/>
            </model>
            <model behaviour="sort-order">
                <param name="label">Title</param>
                <param name="key" 
                    value="substring-before(
                        ./tei:head[@xml:lang='en'],' (')"/>
            </model>
        </modelSequence>
    </param>        
</model>

toggle: The toggle behaviour is inspired on TEI Publisher's pb-toggle-feature. However, pb-toggle-feature (in its client-side version) toggles by setting a CSS class. The toggle behaviour that I propose here governs the behaviour of other behaviours that subscribe to it. (We saw above how the margin-text behaviour stated how its display depended on the state of a toggle behaviour with id showparanum.)

These behaviours have all been implemented in the Edition Publication Model.^[10] The behaviours can be seen at work in the Isaac Israëls letter demo. The demo is based on these PM definitions and has been generated by this implementation.

Conclusion and coda

We have seen that specifying interaction is, on various levels, more complicated than specifying static publications. There exists a great variety of interactive behaviours, and it is unlikely that at a first attempt we get everything right. Accordingly, I have ended this paper with a number of possible interactive behaviours; experimentation is probably the right approach. We're fortunate in being able to build on the work already done in TEI Publisher.

On a personal note: I started working with digital editions and XML in 1999. A few years later I began to think about a declarative specification for edition publication functionality, but that always remained at the level of speculation. Only with the advent of the TEI Processing Model a declarative specification began to seem feasible. And it took a few more years of incubation before I understood that. Now, I'm close to the age of retirement and finally working out these ideas. I also, finally, feel I may have something to contribute at Balisage—and apparently only just in time.

Figure 2: Gartner Hype Cycle 1999

Figure 3: Gartner Hype Cycle 2000

Figure 4: Gartner Hype Cycle 2001

When I joined the XML world, XML was, according to the Gartner hype cycle, just beyond the 'peak of inflated expectations' (Figure 2). In 2000 it was on the 'slope of enlightenment' (Figure 3) and in 2001 it had already progressed so much on the 'plateau of productivity' that it had dropped out of the picture (Figure 4). At least, that is how I interpret its absence from the figure. Apart from following my heart I had also, apparently, made a sensible decision careerwise. But since then, XML seems to have lost the attention of the world. I've sat through a number of presentations on digital edition conferences where someone argued, based on statistics from StackExchange, that XML was no longer hot and that we should switch to something else. And indeed, when I search on Google Scholar for terms relevant to this project, I tend to be shown publications from the early 2000's or even before.

Still, as long as people keep writing and reading, and therefore publishing, we'll need some form of markup. All word processor documents are XML documents internally. XML is no longer that hot, but how hot are, say, relational databases? And as long as we'll have the web, we'll have HTML, and XML will be just around the corner. I'm not too pessimistic about the future of markup languages.