ADR 1: Model

Context

In the original IT4KT versions, all pages were generated using transformations (mostly XSLT). Source files were directly transformed into HTML files. In many cases, however, a resulting page needs to contain information from the other pages. For example, titles of pages displayed in the menu or list of all goals across the course. In the old implementations either XSL transformations accessed filesystem to read needed information, or the information was duplicated in the configuration file. The first solution leads to complex very XSLT files, the second solution leads to unnecessary duplication.

Decision

We decided to split transformation process into two phases and create a complete in-memory model of the course materials between them. The phases are therefore:

1. Read phase — read all pages and fill the model of the course.
2. Write phase — generate HTML pages based on the model.

Model, therefore, needs to contain all information needed to generate pages, including its title and content. Because of possible different formats of source pages (XML, Markdown, etc) content is stored in a format format that seems to be the most versatile — HTML. This means that in the read phase source representation should be transformed into HTML.

To support querying and transforming content of the page, the model contains not only a string representation of HTML, but also an element tree.

Status

Accepted.

Consequences

It would be possible to to automatically generate menus with page names, or an overview of the course with all activities (pages) organized by weeks. It is also possible to cache model elements if it would be needed.

Storing page content in HTML may be limiting for transformations that produce other output formats, for example LaTeX.