The teletext-repository-base-config project
To provide a working setup which can be imported into a pristine Sophora repository as is, or which can be imported and adjusted to specific customer needs in an existing Sophora repository, a project containing the required node types and configuration is available.
The project is available as maven artifact com.subshell.sophora.teletext:teletext-repository-base-config (bin classifier).
Preconditions
Before importing the documents contained in the project, please consider the following steps first.
Components
Before attempting to import any node types into an empty repository, connect to the repository with the DeskClient and register the Components document extension (Administration View -> Document configuration -> Document extensions).
Integrated Teletext Editor
In order to use the integrated teletext editor, the following key-value-pair has to be added to the global configuration document (Administration View -> System -> Konfiguration -> Konfiguration) if it is not yet present:
| Key | Value |
|---|---|
addon.IntegratedTeletextEditor.purchased | true |
Importing the node types
The content of the directory base-repo-config can be imported to a pristine Sophora repository as is. We recommend using a Sophora importer and simply copy the repository base config into the import folder. (You may also manually import the files using the DeskClient; however, note that some of the files require to be imported in the correct order.)
Main Teletext Node Types
The main teletext documents are index pages (sophora-teletext-nt:index) and stories (sophora-teletext-mix:story).
They can be extended by customer-specific properties and/or childnodes. Do not use the sophora-teletext-nt, sophora-teletext-mix, or sophora-teletext namespaces for this, as they are reserved for teletext core features.
Index Pages (sophora-teletext-nt:index)
An index page provides an overview for a set of teletext stories. For instance, this could be a news overview page where the headline for each story is shown, together with the corresponding slot of the story.
Index pages are responsible for distributing their managed stories into a range of teletext slots. That means that story documents usually do not have their slot set directly in the story document. Instead, the slots are assigned in the order in which the stories are referenced from the index page.
If customers wish to extend the index node type, we recommend doing so by adding mixins to the node type. The CND of the sophora-teletext-nt:index node type itself should not be changed.
Stories (sophora-teletext-mix:story)
The main teletext contents (in the form of text) are stored as teletext stories.
Customers may decide to combine teletext stories with other types of stories, e.g., news stories for web distribution. In this way, both the teletext and web content covering the same news event can be maintained in a single Sophora document, facilitating easier teletext/web content migration and maintenance. On the other hand, document locking issues may occur if different persons are responsible for maintaining the teletext and web content.
To allow both ways of managing teletext stories (combined or discrete teletext stories), all required teletext properties are provided as a mixin. Customers must configure this mixin to a customer-specific story node type. Furthermore, the story node type needs the following mixins:
sophora-teletext-mix:canOccupySlotssophora-teletext-mix:canUseTemplatesophora-mix:document
For a detailed discussion on the advantages/disadvantages of both approaches and further customer-specific teletext node types, please contact subshell.
To manage teletext stories at index pages stories should be referenced by the reference node type sophora-teletext-nt:storyRef. Customers may also declare their own reference node type to refer stories with customer specific properties. In this case the declared reference node type must have an according Java model and RenderableIndexElement Java class registered via the index element factory. For a detailed description see Plugin Api.
Templates (sophora-teletext-nt:template)
Teletext templates define the layout of a teletext page (story, diagram, index or any self-defined teletext document type).
To define the visual appearance of a specific document, the field "Teletext: Layout der Seite" can be adjusted by selecting one of the available teletext templates. By default this field is placed on the Teletext tab, but may also be placed on the Metadata tab when there are very few occasions where the template needs adjusting.
Available for selection are all documents of the type sophora-teletext-nt:template. These documents (not to be mistaken for Sophora document templates) can be maintained and created by administrators. They are based on a template file (Texas-XML or ETP) that needs to be uploaded (in binary form) into the corresponding teletext template document. Also, there are fields for the number of header lines and footer lines that define how many lines from the top or bottom of the template document are imported into documents that use this template.
For example, if you define 3 header lines and 2 footer lines and apply this template to a teletext document, then the first three lines of the resulting teletext page are taken from the template file, followed by content from the actual document. Finally, the last two lines are taken from the template file again. The number of header and footer lines also determines the space that is left for content on each resulting teletext page.
On top of this, it is possible to adjust the header and footer lines without having to create different template documents. This is done by placing a variable name between two dollar-signs ($) inside the template file. Variables across line breaks are not supported. The dollar-signs and everything in between them will be substituted in the rendering process of the resulting teletext page. The space available for substitution can be defined by padding the variable name between the dollar-signs with whitespace. The alignment of the variable name corresponds to the alignment of the substituted content. Here's an example:
If the template file contained a line like the following
start $var1 $ end
and the assignment for var1 was "middle", the result would be
start middle end
If, on the other hand, the line in the template looked like this (variable name right aligned)
start $ var1$ end
the substitution would result in
start middle end
The assignment for each variable is determined by the customer-specific plugin code and may consist of any content from the document to be rendered or other sources.
Fragments (sophora-teletext-nt:fragment)
A fragment document is intended to be used as a part of an index page that contains content imported from an external source. A fragment contains only a block of text and can only be used as part of an index page. It cannot be on a teletext slot by itself.
Raw Data (sophora-teletext-nt:RawData)
Raw data documents can be used to store ETP or Texas XML files in a sophora document and assign a slot and a name (only for internal use) to the data. The raw data will be rendered to the assigned slot without any modifications. This is particularly useful for pages that will never be touched and need to be migrated from a legacy system and for pages that are imported into sophora in ETP or Texas XML format.
Please keep in mind, that since the slot number is defined through a separate field in the containing sophora document, slot numbers specified in the raw data won't have any effect.
The teletext configuration document
The teletext configuration document provides means of configuration of the Teletext Generator using the "Administration" view of the DeskClient. Once the document is imported, the Administration view will provide a "Teletext-Konfiguration" section.
Slot whitelist
Probably the most important setting in this section is the "slot whitelist". The Teletext Generator will only operate on slots that are whitelisted here. If any document is assigned a slot which is not whitelisted here, no teletext content will be generated for this slot. On the other hand, for every slot that is listed here, teletext content will be generated. Even if that means that the resulting teletext page will be empty, because no sophora document was assigned to the corresponding slot.
The format of the slot whitelist is a comma-separated list of slots and/or slot ranges. A valid example would be:
100, 102-105, 600-602, 700
Site filter
Teletext documents considered by the Teletext Generator can be filtered by the Sophora site they are located in. The property sophora:validSites specifies Sophora sites that will be considered. Teletext documents located in not selected sites will be ignored by the Teletext Generator.
If no sites are selected, all sites are considered.
Example Document Types
The example-nt:story node type is included only to provide a working example of a node type representing the main story of a typical repository. This kind of node type will usually already exist in a non-empty repository.
Therefore, the example-nt:story node type should usually not be imported into an existing repository. Instead, the teletext mixins and reference type have to be configured for the existing story node type.
Solr configuration
The Teletext Generator requires no special Solr cores to be present and uses internal cores default and default-live existing in Sophora configuration by default.
Texas XML
The Texas XML is an XML format developed by subshell for exchanging teletext files. For more information see the documentation of the Teletext Converter.
