oXbytei

tl;dr

Install from

https://scdh.github.io/oxbytei/descriptor.xml

STATE: in production

An oXygen framework configured by TEI

oXbytei [ɔx bʌtaj] (greco-english tongue and french ears) is a generic oXygen framework for editing TEI. It offers high-level functions that facilitate everyday work on TEI documents. Its name originates from the idea, to use as much information as we can from the TEI header to configure the framework's actions. But since the header's information is not sufficient for most editing actions, oXbytei also introduces a configuration file to oXygen frameworks, which makes it the next generation framework. You can read more about the design principles in the Wiki.

Features / Functions

• Critical apparatus: According to what is stated in <variantEncoding> a new apparatus entry is generated from the user selection and inserted into the document. The selected text goes into <lem>. Supported variant encodings: all but external location-referenced. @wit can be selected based on the witnesses supplied via sourceDesc/listWit//witness.
• Suggestions: A flexible and extensible plugin system generates suggestions for attribute values etc. in a context-aware manner. E.g. the framework by default sets up suggestions for @ref of <persName>, <placeName> or @corresp of <bibl> by evaluating prefix definitions in the document header. The plugin system is flexible enough to add plugins for querying RESTful webservices. Available plugins range from generating suggestions via XSLT, XQuery, XPath, from CSV, from SPARQL over local files or a remote endpoint, etc.
• Configurable user dialogs: Simply declare by configuration which type of dialog you want to have for a specific editing context, e.g. a multiple select dialog for @wit on <rdg>. Dialogs are plugins that implement an interface for communicating with plugins that provide suggestions for content completion. There're combo boxes, editable combo boxes, multi select dialogs based on check boxes etc.
• Attribute editor: These configurable dialogs and suggetions are used in a generic schema-aware attribute editor.
• Language: Set @xml:lang by selecting a language registered in the header by langUsage
• Different markup styles: When annotating persons, places etc. you can choose between markup styles: E.g. in aggregative style (default) the user selection is wrapped into an element if and only if the selection's start and end point are on the same parent node. Otherwise, each text node between is wrapped and the elements are linked by @next and @prev. Alternative styles include att.spanning and anchor-based markup.
• Annotations: Surround the user selection with empty <anchor> elements carrying unique IDs and then insert a <span> referencing the anchors somewhere else in the document. Also select span/@ana from <interp> elements in the document (default). Other sources/references for @ana can be configured.
• Navigation in anchor-based markup: a) Find annotations and apparatus entries for the current position; b) highlight (select) the span of text referenced by an annotation or apparatus entry.
• Multiple level inheritance: Instead of an oxbytei.framework file, oXbytei uses an extension script as introduced in oXygen 23.1. This makes it possible to inherit from base frameworks on multiple levels. You're able to write your own framework on top of oXbytei, which operates on top of TEI P5.
• Powerful author operations: The Java code base defines some powerful author operations, that you can re-use for your own actions.

On the road map:

• a plugin for getting content completion suggestions from RDF endpoints
• editor operations for generating RDF/OWL based annotations (see branch annotation-rdf)
• Melt and cristallize anchors: The anchors inserted for your double end-point attached apparatus, for your annotations or for other markup, will pollute your edited text. Melting is the process of joining anchors, which are direct siblings, into one anchor or even integrating the ID into another tag. Cristallizing is the process of giving a referring element back its own anchors, after there was a melting. This is needed when a reference point to the edited text has to be moved.
• exploit <tagsDecl> etc.
• Index

Read more in the Wiki.

You should also have a look at oXbytao, which might already extend oXbytei to your project-specific needs.

Why to try

Novice oXygen users: You want to customize a bit, e.g. provide a select box for an attribute like rdg/@wit and add some CSS. However, you don't want to invest into framework customization but stay with X technologies like XQuery or XSLT.

Then the configurable plugin system of oXbytei will give you what you need and oXbytao will offer you simple CSS customization on a project/user basis.

Experienced users: Are you tired of framework development, where you define tons of author actions for setting attribute values and where you have to hard-code content into ${ask(...)} or write nested ${ask(...${xpath_eval(...)}...} which are so complicated that you don't understand them any more on the next day? Or, are you sick of coding form components with hard-coded content or complex XPath expressions in them into a flavoured CSS?

Then you should give oXbytei a try: It lets you generate the values for selection for a specific editing context like rdg/@wit with a plugin that e.g. evaluates one of your XQuery scripts. And it lets you declare which UI form (free type, single select, multiple select) you want to have for an editing context, e.g. multiple select for rdg/@wit. In the config file you can just tie the generation of selection options and the appropriate UI form together for a specific editing context. oXbytei's design is all about separation of concerns and consistent interfaces.

Package

Requirements

oXbytei requires oXygen >= 23.1, because it makes use of an extension script for framework configuration. With extension scripts you gain multiple level inheritance and transparent updates, i.e. updates on lower level frameworks can be installed without the need to update the stack of frameworks based on it.

Installation

The framework can be installed with <oXygen/>'s installation and update mechanism. Therefore, the following URL has to be entered into the form Show addons from: of the dialogue box from Help -> Install new addons....

https://scdh.github.io/oxbytei/descriptor.xml

Note: The framework is not signed with a key. You can simply ignore the warning, which oXygen throws during the installation process.

As an alternative, the framework can be packaged locally for installation or it can be installed for hacking.

Packaging locally

Packaging is done with maven.

mvn generate-sources
mvn package

This will create a file named oxbytei-<VERSION>-package.zip in the target folder. This zip-File is the same as the one distributed under the above mentioned URL.

In order to use oXbytei with older versions of oXygen, you can generate an old-school dot-framework file from the extension script using the Compile Framework Extension script as described in the documentation and then use local packaging.

Hacking / Development

Installing the framework as an <oXygen/> package will make it read-only. For hacking on it's code you can install it by registering the path to the cloned repository in <oXygen/>'s settings.

• 1. Clone this repository into a subfolder of an <oXygen/> project, e.g. oxbytei. (It may also be sym-linked there.)
• 2. Start <oXygen/> and select Options -> Preferences from the menu. Expand Document Type Association on the left and select Locations [P] under it. Click Add to add a new additional framework directory. Enter ${pdu}/oxbytei as directory and click OK. (Note: ${pdu} is an editor variable and points to the root folder of the current project.)
• 3. Run maven to get dependencies

mvn generate-sources
mvn package

• 4. Create symbolic links for all the jar files from the folder target/lib to the folder frameworks/oxbytei:

cd frameworks/oxbyt