CHF Base 

Extension key

chf_base

Package name

digicademy/chf_base

Version

main

Language

en

Author

Jonatan Jalle Steller, CHF Base contributors

License

This document is published under the CC BY 4.0 license.

Rendered

Mon, 29 Sep 2025 13:37:02 +0000

The Cultural Heritage Framework (CHF) is a research software suite that helps you build web apps to produce and publish data in the humanities. It is designed for the needs of scholarly editing, lexicography, archives, GLAM institutions, and, more generally, projects interested in making cultural heritage, books, media, or annotated bibliographies available in their own web-based research platform. A key strength of the CHF is the ability to produce portals and multimodal editions that include various data types with historical points of reference in a single system, including editing interfaces, frontends, and serialisations. Specific data models are organised as additional components around the TYPO3 extension CHF Base, which provides central data types like Agent, Location, and Period, but also multiple types of Tag and Relation to structure and connect data as well as services like import and export routines. The various components are developed and maintained by the Digital Academy, a Digital Humanities department at the Academy of Sciences and Literature Mainz.

Overview 

The CHF consists of a set of interoperable extensions for the enterprise content management system TYPO3, which provides management of content, users, and files, a toolset to publish pages and content blocks, a thriving community, and an extension API. On top of these features, and using the same open-source licence, the CHF provides a set of modular components that you can orchestrate by adding your own so-called ‘sitepackage’: a small extension specific to your individual project that you may simply copy and adapt from a boilerplate included in the CHF. This process may be as simple as listing the components you need and using everything else out of the box, or you could radically overwrite layout and data templates, add database tables and rows, or integrate other extensions available in the TYPO3 extension repository.

The original idea for a CHF was presented in 2017 by Torsten Schrade, with a number of ideas implemented across several projects of the Digital Academy ahead of and after the presentation. Work on version 2 of the CHF began in 2023 in the form of a complete rewrite organised by Jonatan Jalle Steller - with the exception of LOD, which had been in development much earlier. The rewrite with a new set of components and a different set of features was needed to better adapt to various use cases and to provide a coherent whole. Work on version 2 of the CHF was accomplished as part of two projects financed by the German Academies Programme: the Digital Dictionary of Surnames in Germany and the Corpus Vitrearum Germany.

Components 

The modular architecture of the Cultural Heritage Framework follows the idea of a separation of concerns. There are three types of components you should know: specific data models, independent helpers, and the project-specific sitepackage.

The main set of available extensions are data models organised around CHF Base, which provides core data structures. The base component also includes its own user interface library for the web that is designed to be accessible, atomic, responsive, and GDPR-compliant, as well as a few tools needed by a number of dependent extensions. Each of these components targets a highly specific data domain and includes data models, editing interfaces, standard templates, common serialisations like TEI XML and embedded metadata, data import options, and search configuration. The following extensions of this category are available:

• CHF Base (resources, locations, periods, and actors; partly inspired by TEI)
• CHF Bib (bibliographies and Zotero import; based on Zotero TEI)
• CHF Lex (lexicographic resources with dictionary and/or encyclopedic entries; based on DMLex)
• CHF Map (geodata and image maps; based on GeoJSON)
• CHF Gloss (terms and their explanations)
• CHF Pub (volumes and essays to model books, book series, blogs, and journals)
• CHF Object (physical objects and related events)
• CHF Media (image, video, and 3D files, galleries, and collections)
• Not in development yet: CHF Music (MEI data)
• Not in development yet: CHF Letter (correspondences)

In addition to these data models, three optional helpers are available. They provide single-purpose additions to TYPO3's functionality that are useful in a Digital Humanities-focused web app. Using these helpers may require a bit of configuration in accordance with their individual documentation. They may also be used without any of the CHF data models listed above:

• Not in development yet: ENDPT (SPARQL, OAI-PMH, and SRU endpoints)
• DSH (quality assurance for data, dashboards)
• VIS (a set of visualisations)

Last but not least, each project needs its own sitepackage. In theory, every aspect of the other extensions may be overwritten in this extension. In practice, it is typically used to include and configure the extensions you need and to adapt a few minor template elements. The CHF includes a boilerplate that you can simply copy and adapt to your needs.

• CHF Project (sitepackage boilerplate)
• CHF Container (sample Podman or Docker container configuration)

Setup 

The CHF provides standard TYPO3 extensions, so the resulting web project will behave like a regular TYPO3 project. The official getting started guide provides system requirements and installation instructions.

To kickstart development, you may simply use the Podman or Docker containers provided CHF Container and/or the sitepackage boilerplate CHF Project. Please refer to the documentation of the container package to see how it works. Depending on your web server's set-up, the container may not be useful and you may simply need an adapted boilerplate extension and activate it in a PHP Composer environment.

For inspiration on how to use the CHF, feel free to take a look at two actual sitepackages based on the boilerplate code: namenforschung and corpusvitrearum.

Usage 

Specific usage instructions are provided in each component's documentation where necessary. There are a few central concept in the CHF and the TYPO3 world that may come in handy:

• Basic instructions for your own project and sitepackage are provided in the documentation for CHF Project.
• TYPO3 differentiates between frontend and backend, and editing is usually done in the latter.
• The content management system associates data with the page (or folder) it is added to.
• New major versions of TYPO3 are released every 1 1/2 years. Security updates are released every couple of weeks at the latest, and it is your responsibility to keep your project up to date.

Updates 

Any user-facing web project with dynamic components needs regular maintenance and a TYPO3 system is no different. You should regularly update your instance as instructed in TYPO3's getting started guide. The goal for CHF components is to always update all components for the latest release, but these updates may not always be ready on day 1. Feel free to step up and provide patches to aid this regular maintenance.

When components are upgraded and changes are made, the goal is to migrate any content and data automatically. But especially if you heavily customise the CHF in your sitepackage, you may face a bit of maintenance work to keep up with new releases as TYPO3 continuously modernises its APIs with each major version.

Development 

The following steps should help when you find yourself in the position of having to update an existing extension for a new major release of TYPO3. Before you start, make sure you know whether the upgraded extension needs to support more than one major release of the software.

1. Use TYPO3 Rector on the extension's code to get an idea of what needs to be changed. Rector can automatically implement a lot of necessary changes for you and will tell you about other things you need to change by hand.
2. When this is done, switch to a development environment updated according to the TYPO3 release's changed requirements. Use the updated system's integrated extension testing tools to see which further changes are required.
3. If you make changes that affect the database, make sure there is an automatic upgrade script in place.
4. Check that the extension is working as expected. This can be done manually or with the help of an automated testing pipeline.
5. Edit the metadata to increase the version numbers of both the extension and TYPO3. Add the changes to the changelog so other developers can see what changes were made when they use the extension.

Data models in TYPO3 

Data models in TYPO3 have to be maintained as two independent instruction sets. Any model needs one configuration file per database table called TCA in the TYPO3 lingo. These determine what properties (or rows) a given table has, what values are allowed, how they behave in the backend, and how they are stored in the database.

In addition, most custom extensions also implement an Extbase data model on top of this table configuration, which enables the clean getting and setting of values by means of one PHP object per database table. For each of these, and in addition to the TCA, Extbase needs a model and a repository. The model describes all properties, and a repository generates instances of objects from the database. In addition to these, controllers orchestrate how instances of objects may be accessed in the view. If the TCA configures tables with multiple types (different sets of properties based on the value of one property), these are implemented in models via inheritance: an Abstract class defines all basic properties and other classes extend the Abstract one to add the properties they need. While simple TCA tables and models are mapped automatically, rules for model inheritance need to be made explicit in the file Configuration/Extbase/Persistence/Classes.php.

Because the Extbase logic is built on top of a standard TCA, some aspects may need to be implemented in both: default sorting of object instances, for example, needs to be configured in both the TCA (for backend views) and the repository (for accessing object instances in code and in the frontend), multiple types in the same TCA table need to be adapted to class inheritance, required fields must be marked both in the TCA and in the __construct() method of a model, and if you want to limit the values that can be used in a given property, this needs to be implemented in the TCA (for backend users) and in the model's validators to allow for scenarios in which new object instances are added through import routines, for example. While models use camel case for properties (e.g., revisionDate), Extbase exptects their respective database columns to use underscores (e.g., revision_date).

The 'view' in Extbase's model/view/controller logic is realised by TYPO3's templating engine called Fluid. In theory, Fluid also works with basic TCA configuration without the Extbase overhead, but a full object model maked Fluid more comfortable and allows you to add data programmatically instead of straight into the database.

Design principles 

All data models in the Cultural Heritage Framework adhere to common design principles. They are documented below to help you understand a data model in question, to make informed decisions on how to implement changes, or to aid in designing a new addition to the CHF.

1. Ideally, CHF data models are either based on or inspired by an existing model that is widely used in a specific domain or, if possible, even standardised.
2. Generic classes that are reused across dependent data models are stored in CHF Base. If a class would need lots of overrides if it were included here, it may be better located in the dependent data models that actually need it, even if this means that a bit of code needs to be duplicated.
3. Models designed to store data sets should be held together by a central class Resource (e.g., BibliographicResource for a bibliography). This allows for multiple data sets in the same TYPO3 instance. If data sets should be kept fully separate, however, they should also be stored in different pages (or folders).
4. Another common pattern across the CHF is to allow the use of SameAs and Tag classes. The former helps identify entities in Linked Open Data scenarios through identifiers from authority files, and the latter offers generic and, in some cases, extensible keyword and label systems.
5. The data models tend to avoid extensive cross-dependencies. Using classes from CHF Base is common, though, and some models may also include SourceRelation from CHF Bib or Feature and MapResource from CHF Map where appropriate. GlossaryResource may be used across all other data models if needed.
6. A data model extension should contain the TCA, model/repository/controller files, import and export formats appropriate for the data model, generic Fluid templates for the frontend, a search configuration, and embedded metadata to make the views it provides as machine-readable as possible.
7. The goal is to keep as much logic as possible in PHP code since it is relatively easy to learn and maintain, even for newcomers. TypoScript, which is a very powerful tool in TYPO3, is reserved for configuration instructions.

Contribution 

The Cultural Heritage Framework is an open-source project. We encourage contributions and have listed a couple of ways in which you could contribute below. We only ask that the CHF community follows the Contributor Covenant code of conduct. Please contact us via the public email address in our GitHub profile if you encounter a violation of the code of conduct so we can enforce this shared set of rules. You are also free to contact us if you would like to contribute but do not want to engage in our public repositories.

1. Spread the word

   We love hearing from other projects using CHF components. Let us know or spread the word using the marketing resources we store in our code repositories.

2. Report an issue

   Found something that does not work as intended? Report the issue in the repository of the affected component. Try to be as specific as possible so we can reproduce and test the problem.

3. Add documentation

   Ran into a problem and wished the documentation was better? Help us improve by editing the documentation right in a component's repo and submitting a merge request. Or just message us.

4. Fix a bug

   Any help with bug fixes is appreciated. If you know how to reproduce an issue and fix it, feel free to create and submit a merge request.

5. Add a feature

   Feeling comfortable in the code base and need a feature other projects may benefit from as well? Just create an issue describing the enhancement and start working on a patch.

6. Share your expertise

   Have an idea for how to contribute to the project with any other skill not listed above? Just contact us, we appreciate it.

Introduction 

The extension provides a number of database tables and corresponding classes for use in the various dependent data models in the CHF. This includes humanities-specific data such as Location, Period, and Actor, but also more generic classes like SameAs. In the same vein of being a service extension for other data models, CHF Base also includes key third-party libraries like Leaflet, infrastructure to import and serialise data, to compile search configuration, and to build user interfaces. The latter is realised in the form of generic Fluid templates that sitepackages may use as-is, but also by means of a CSS library with complimentary JavaScript to build accessible and responsive web apps from atomic components.

Install and config 

1. Install the extension

   Add the package name to your composer.json or install the package manually.

2. Add specific data model extensions

   Select other chf_ extensions that you need for your project. They may extend and use the service classes implemented in this extension.

3. Optionally add an import task

   To import data once or periodically, go to the Task module in the backend and add a new task. Enter the fields required to perform the task and either start it manually or set an interval to run the task automatically.

Editing content 

Editors need access to the data folder in order to make changes. They may add and edit resources, locations, periods, actors, and other basic elements here.

TBD

Templates 

TBD

Data model 

This extension does not provide a fully rounded data model but a set of service classes. A Location may be organised hierarchically to model, for example, world regions, countries, regions, cities, and buildings. A Period may similarly be arranged in a hierarchy to model historical periods, phases, or dates. Actor objects, on the other hand, may be grouped together via Tag labels, but otherwise stand on their own. They may refer to organisations, individuals, or other entities in the sense of actor-network theory.

In addition, the model provides flexible Tag objects to group other classes, Relation objects connect classes with qualifications like the role of an Actor, and SameAs classes to connect entities to authority data. Simple Keyword objects may be used to interconnect labels.

Graphical overview 

API reference 

TBD

Maintenance 

Maintenance of the extension may include adapting it to new TYPO3 versions or updating dependencies and includes. The following include is used:

• Leaflet 1.9.4:

  • Content of images in Resources/Images/leaflet
  • File leaflet.js in Resources/Public/JavaScript
  • File leaflet.css in Resources/Public/Css with url() values changed to accommodate the new image location.

Sitemap