Support multiple relation editors via relation widget registry (Request in QGIS)

[qgis-bot]

Request for documentation

From pull request qgis/QGIS#40721
Author: @suricactus
QGIS version: 3.18

Support multiple relation editors via relation widget registry

PR Description:

Description

With this change the current relation editor is no longer the only way to edit relations. Similarly to the way different field editors exist, one can develop and register their own widget, using the newly added classes:
QgsRelationWidget - the widget used in the attribute form
QgsRelationConfigWidget - the configuration widget shown in layer's attribute table configuration tab
QgsRelationWidgetFactory - a factory that creates the QgsRelationWidget and QgsRelationConfigWidget
QgsRelationWidgetRegistry - a registry where the factory is being registered.

The currently existing QgsRelationEditorWidget is deprecated and replaced with QgsBasicRelationEditorWidget, which is protected from accidentally being deleted and is used as fallback widget.

The most notable UI change allows the user to select the desired relation widget from the drag n drop form configuration:

Note the widget type and widget configuration UI.

Sample widget:

class QgsExampleRelationWidget(QgsRelationWidget):

    def __init__(self, config, parent):
        super().__init__(config, parent)

        self.setLayout(QGridLayout())
        self.label = QLabel()
        self.label.setText(f'According to the configuration, the checkboxin state was {str(config.get("checkboxin", "Unknown"))}')
        self.layout().addWidget(self.label)

    def config(self):
        return {

        }

    def setConfig(self, config):
        self.label.setText(f'According to the configuration, the checkboxin state was {str(config.get("checkboxin", "Unknown"))}')


class QgsExampleRelationConfigWidget(QgsRelationConfigWidget):

    def __init__(self, relation, parent):
        super().__init__(relation, parent)

        self.setLayout(QGridLayout())
        self.checkbox = QCheckBox('Is this checkbox checkboxin?')
        self.layout().addWidget(self.checkbox)

    def config(self):
        return {
            "checkboxin": self.checkbox.isChecked()
        }

    def setConfig(self, config):
        self.checkbox.setChecked(config.get('checkboxin', False))


class QgsExampleRelationWidgetFactory(QgsRelationWidgetFactory):
    def type(self):
        return "example"
    
    def name(self):
        return "Example Relation Widget"

    def create(self, config, parent):
        return QgsExampleRelationWidget( config, parent )

    def configWidget(self, relation, parent):
        return QgsExampleRelationConfigWidget( relation, parent )


registry = QgsGui.relationWidgetRegistry()
registry.addRelationWidget(QgsExampleRelationWidgetFactory())
widget = QgsGui.relationWidgetRegistry().create('example', {})
widgetConfig = QgsGui.relationWidgetRegistry().createConfigWidget('example', QgsRelation())

These changes are part of qgis/QGIS-Enhancement-Proposals#79 .

TODOs:

• improve documentation
• some basic unit tests
• improve backwards project compatibitlity with QGIS 3.10 and 3.16

Commits tagged with [need-docs] or [FEATURE]

[suricactus]

Please note the code to generate a new widget is sligtly different, please find the current version on https://github.com/qgis/QGIS/blob/master/tests/src/python/test_qgsrelationeditorwidgetregistry.py#L72-L131 . Please ping me if it needs further clarification.

[suricactus]

@DelazJ sorry, I am new to the docs process, why you added QGIS 3.22 label?

[DelazJ]

No worries. It's just the milestone; we release docs only for LTR and the first LTR including this feature will be 3.22 so describing this feature belongs to master only. It also helps to visualize the pending work at https://github.com/qgis/QGIS-Documentation/milestones
It shouldn't prevent you to provide documentation for it now. Not at all.

[3nids]

some modifications were brought to the creation of polymorphic relations in qgis/QGIS#43488
when no referenced layer is selected, you cannot define field pairs (widget disabled):

when one layer is selected, all fields can be used:

when more layers are selected, only the intersection of the fields are proposed:

if there is no field in common: