QFQ

h1. Renderer Refactoring

{{toc}}

Branch: https://git.math.uzh.ch/typo3/qfq/-/tree/F17252_Renderer_Refactoring

h2. Motivation

To achieve a more modern look and feel, QFQ Forms should support Bootstrap 5 in addition to the previously used Bootstrap 3.

However, implementing this functionality into the current codebase while still practicing "clean code" is not possible.

Therefore the current code is being refactored to support future expansion.

h2. Concept

Previously, preparation and rendering of the form with all its form elements was handled in AbstractBuildForm.php and BuildFormBootstrap.php.

The new concept introduces many new classes, making the code much more modular.

Most notably: *Separating Configuration and Rendering of Form and FormElements* !

By doing this, new Renderer Classes can be implemented in the future, which use the same AbstractFormElement objects to render the element in a different way (e.g. Bootstrap 5).

h3. Class diagram

See the class diagram below:

!renderer_class_diagram_update_2024.drawio.png!

h3. Sequence Diagram Form and FormElement Instantiation

tbd

h3. Sequence Diagram Rendering

The diagram below describes the rendering process.

* The BaseRenderer (or any specific implementation of it) takes the previously instantiated Form object that describes all aspects of the form that is to be rendered.

!renderer_sequence_diagram_update_2024.drawio.png!

h2. Dev Guide

This section should answer common questions on how to use the refactored code and how to expand upon it.

h3. Adding a New Form Element

This chapter describes how new form elements can be added into QFQ in the new model.

In this example we are assuming a new FormElement "Chat" should be implemented in QFQ.

Follow these steps:

# Create a new class ChatFormElement in the folder Core>Form>FormElement.

This class needs to extend AbstractFormElement and should call the parent's construct method when instantiated, as seen in the screenshot below.

If the form element you want to introduce is a ContainerFormElement, then extend ContainerFormElement instead of AbstractFormElement!

!clipboard-202406121148-aqvlm.png!

# Add a new CASE block to the SWITCH statement in FeFactory.php.

This way the factory will return an object of your newly created class when needed.

It is best to add a new constant in Constants.php that defines the new FE type. In this example the constant FE_TYPE_CHAT is simply defined as 'chat'.

!clipboard-202406121152-vlscn.png!

# Create a class ChatRenderer in the folder Core>Renderer>FormElement>Base

This class is supposed to render a chat element completely independent of the used CSS Framework.

In practice, this class might stay empty.

!clipboard-202406121158-y2gwo.png!