View source for QtDesignStudio/BackendApi

= Backend API and Simulation =

== Overview ==
The Backend API mechanism separates UI presentation from application data layer by routing data through a centralized singleton.

Instead of hardcoding the values directly in QML, properties are delegated to a BackendApi which then reads values from the Backend implementation (by default, BackendSimulation, but any other implementation might be used).

This enables designers to work with live-editable data and allows developers to easily replace the simulation with a real backend written in either QML or C++. Most importantly, without touching the UI code.

== Architecture ==
<syntaxhighlight lang="bash">
UI Components ---binding---> BackendApi <---propagates--- Backend (e.g. Simulation) ---reads---> backend.json
</syntaxhighlight>Where:
{| class="wikitable"
|+
!Component
!Component
!Relation
|-
|UI Components
|BackendApi
|A UI component binds to BackendApi.<propertyName>
|-
|BackendApi
|Backend
|BackendApi declares properties that are bound to Backend.<propertyName>
|-
|Backend
|backend.json
|BackendSimulation reads values from the backend.json at runtime, loads them into internal properties and automatically propagates them to UI components through the BackendApi bindings.
|}

== Converting a property into a Backend property ==

=== User Scenario ===
Given a QML component of type Text, its text property is set to "Hello". You want to move that value to the backend so it can be managed centrally and supplied by a real data source.

# You select the Text component in the Qt Design Studio Form Editor or Navigator.
# In the Property editor of the Text component, find text property and click on a small gear icon button next to it.
# From the context menu, select "Convert to Backend property".
# A dialog appears prompting you to enter a backend property name.
# Click "Convert".

=== What happens next? ===
A new property is inserted in between the @properties-begin and @properties-end markers in the BackendApi.qml file of your project:<syntaxhighlight lang="qml">
QtObject {
    // @properties-begin
    property string text: Backend.text
    // @properties-end
}
</syntaxhighlight>Where:

# The property name is what you entered into the dialog.
# The property type is inferred from the original property (text property of the Text component in that case).

Next, the backend.json file gets updated:<syntaxhighlight lang="json">
{
    "text": "Hello"
}
</syntaxhighlight>Where:

# The property name is what you entered into the dialog.
# The value is same as the original value of the text property of the Text component.

Next, the property binding in your Text component is updated:<syntaxhighlight lang="qml">
Text {
    text: BackendApi.text
}
</syntaxhighlight>

=== Duplicates handling ===
If a backend property with the same name already exists, the system reuses it, i.e. it's not added again to BackendApi. The component's property is still re-bound to BackendApi.<propertyName> tough.

=== Enumeration values ===
Enumeration properties are automatically converted to their integer representation before adding them to BackendApi or backend.json.

=== Files ===
BackendApi.qml, BackendSimulation.qml and backend.json files are all stored under:<syntaxhighlight lang="bash">
/qt-automotive-studio/share/qtcreator/qmldesigner/studio_templates/projects/shared-plugin/name/
</syntaxhighlight>

==== BackendApi.qml ====
Public API singleton that exposes all backend properties to the UI components.

# Registered as singleton.
# UI components bind to BackendApi.<propertyName>.
# Each property delegates to Backend.<propertyName>, creating a layer of indirection. The Backend singleton can be swapped out without changing any UI bindings.
# The @properties-begin and @properties-end comment markers are used by the code generator to locate and insert new properties. '''Do not remove or reorder these markers.'''
# You may manually add properties between the markers as long as you also add corresponding entries to backend.json.

==== BackendSimulation.qml ====
Default implementation of the Backend singleton. Loads values from backend.json.

# Registered as singleton Backend in the module (note: the QML type name is Backend, not BackendSimulation).
# Uses FileReader from QtQuick.Studio.Utils to load backend.json.
# Reloads automatically when backend.json changes on disk.
# Properties are '''read-only.'''

==== backend.json ====
Data file that stores the property values used by BackendSimulation.

=== Replacing BackendSimulation with a Custom Backend ===
The default BackendSimulation is a convenience for prototyping in Qt Design Studio. For production applications, you will typically replace it with a backend that connects to real data sources like REST APIs, databases, vehicle bus systems, or application logic.

The key requirements are:

# your replacement must be a QML singleton registered as Backend in the module,
# it must expose the same property names that BackendApi.qml references.

==== Example ====
<syntaxhighlight lang="c++">
#pragma once

#include <QObject>
#include <QQmlEngine>

class Backend : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON

    Q_PROPERTY(QString text READ text NOTIFY textChanged)

public:
    explicit Backend(QObject *parent = nullptr) : QObject{parent} {}

    QString text() const { return m_text; }

signals:
    void textChanged();

private:
    QString m_text = "Hello";
};

</syntaxhighlight>To use your Custom Backend C++ implementation, it's enough to remove BackendSimulation and backend.json from your project and build it with your custom implementation instead.