Document management system

[m-kuhn]

QGIS Enhancement: Attached documents

Date 2016/10/24

Author Matthias Kuhn (@m-kuhn)

Contact [email protected]

maintainer @m-kuhn

Version QGIS 3.0

Summary

Documents like text, images, videos or any type of file can currently be linked with an external resource widget into QGIS projects. For domain specific modules, it is often required to attach multiple documents to an entity. QGIS offers 1:N relations which handles this kind of requirement.

At the moment, this requires one document table per feature table. This sometimes (almost) duplicates the number of tables inside a database. To keep the models more simple, this QEP proposes to offer the possibility to maintain all documents in a single document table (or more generally, any type of attached fields and not only documents).

The management of this will introduce a new kind of dynamic relation where the referenced table is not fixed but determined by an expression at runtime.

Proposed Solution

Dynamic relations

A dynamic relation consists of the same properties like an ordinary relation except for the referenced layer which is calculated based on a field of the referencing layer. In its most simple form, the referencing layer will just insert the layer id of the referenced layer into this field.

By using an expression this can be adjusted to match other properties of the the referenced layer like the table name, schema, uri, layer id, ...

An example configuration could look like this:

• referencing_layer: documents_layer_id_20161030928471
• referencing_field: fk_feature_id
• referenced_field: id
• referenced_layer
  • referenced_layer_field: table_name
  • referenced_layer_expression: CONCAT( "schema", '.', "table_name" )

Layer metafeatures

To be able to compute expressions on layers, layers need to be exposed as features. To do this, the QgsLayerRegistry will receive a new method getFeatures() that returns a QgsFeatureIterator which will iterate over layers.

Each "feature" has attributes like

• id
• uri
• schema
• table_name
• file_name
• ...

Embedding the document layer

A document layer will be available as relation editor (n-side) for all other layers in a project by default if the “referenced field" is available on the layer.

When using the drag and drop designer, it is available the same way like ordinary relations are now already.

In an embedded document layer, only features where both conditions (referencing_field = referenced_field and referenced_layer_expression( parent form layer ) = referenced_layer_field ) match will be shown.

When adding a new entry, both fields (referencing_field and referenced_layer_field) will be prefilled.

The document layer form

On the document layer, the relation reference widget does not receive any integration.
This may be part of future work where the shown form changes with the feature.

Performance Implications

None foreseen.

Backwards Compatibility

• Existing relations will continue to work as before.
• Loops over relations in a project will have to be updated to deal appropriately with the fact of dynamic layers. They will either have to skip dynamic relations or deal with features from different layers when looping over related features.

API Changes

The QgsRelation API will be updated:

    /**
     * Will return the referenced layer. For dynamic relations it is required to pass the feature
     * or the return value will be a nullptr.
     */
    QgsVectorLayer* referencedLayer( const QgsFeature& feature = QgsFeature() );

    /**
     * In case of dynamic layers the resulting feature or request depends on the layer
     * derived from attrs. The layer can be retrieved with the method referencedLayer( feature )
     */
    xxx getReferencedFeature[xxx]( const QgsAttributes& attrs )

    /**
     * For dynamic relations, a layer will be required to successfully build the filter to get
     * features from the document layer.
     */
    xxx getRelatedFeatures[xxx]( const QgsFeature& feature, QgsVectorLayer* layer = nullptr );

Aggregate functions

Aggregate functions might not fully support dynamic layers for now. Support might be added where trivial.

Votes

(required)