diff --git a/docs/docs/assets/menu.png b/docs/docs/assets/menu.png index b7f132297..9868d85b8 100644 Binary files a/docs/docs/assets/menu.png and b/docs/docs/assets/menu.png differ diff --git a/docs/docs/assets/plugin_manager.png b/docs/docs/assets/plugin_manager.png new file mode 100644 index 000000000..6f2bb54c9 Binary files /dev/null and b/docs/docs/assets/plugin_manager.png differ diff --git a/docs/docs/assets/toolbar.png b/docs/docs/assets/toolbar.png index 7c22332fa..fa6748675 100644 Binary files a/docs/docs/assets/toolbar.png and b/docs/docs/assets/toolbar.png differ diff --git a/docs/docs/assets/usabilityhub-abstract-metaconfig.png b/docs/docs/assets/usabilityhub-abstract-metaconfig.png new file mode 100644 index 000000000..2b066f604 Binary files /dev/null and b/docs/docs/assets/usabilityhub-abstract-metaconfig.png differ diff --git a/docs/docs/assets/usabilityhub-abstract-modelselection.png b/docs/docs/assets/usabilityhub-abstract-modelselection.png new file mode 100644 index 000000000..67ff648fd Binary files /dev/null and b/docs/docs/assets/usabilityhub-abstract-modelselection.png differ diff --git a/docs/docs/assets/usabilityhub-abstract-projecttopping.png b/docs/docs/assets/usabilityhub-abstract-projecttopping.png new file mode 100644 index 000000000..a94437a3c Binary files /dev/null and b/docs/docs/assets/usabilityhub-abstract-projecttopping.png differ diff --git a/docs/docs/assets/usabilityhub-abstract-referenceddata.png b/docs/docs/assets/usabilityhub-abstract-referenceddata.png new file mode 100644 index 000000000..915b6663e Binary files /dev/null and b/docs/docs/assets/usabilityhub-abstract-referenceddata.png differ diff --git a/docs/docs/assets/usabilityhub-abstract-toppingdownload.png b/docs/docs/assets/usabilityhub-abstract-toppingdownload.png new file mode 100644 index 000000000..f26e0d08f Binary files /dev/null and b/docs/docs/assets/usabilityhub-abstract-toppingdownload.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-additive-settings.png b/docs/docs/assets/usabilityhub-exporter-additive-settings.png new file mode 100644 index 000000000..d93439df5 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-additive-settings.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-generated.png b/docs/docs/assets/usabilityhub-exporter-generated.png new file mode 100644 index 000000000..fe3066be6 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-generated.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-ili2db.png b/docs/docs/assets/usabilityhub-exporter-ili2db.png new file mode 100644 index 000000000..105d96ffd Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-ili2db.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-layer-styleicon.png b/docs/docs/assets/usabilityhub-exporter-layer-styleicon.png new file mode 100644 index 000000000..f357a21d6 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-layer-styleicon.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-layer.png b/docs/docs/assets/usabilityhub-exporter-layer.png new file mode 100644 index 000000000..e11706b23 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-layer.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-model.png b/docs/docs/assets/usabilityhub-exporter-model.png new file mode 100644 index 000000000..c48028284 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-model.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-project.png b/docs/docs/assets/usabilityhub-exporter-project.png new file mode 100644 index 000000000..2d0b24962 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-project.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-reference.png b/docs/docs/assets/usabilityhub-exporter-reference.png new file mode 100644 index 000000000..8912defd8 Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-reference.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-repo.png b/docs/docs/assets/usabilityhub-exporter-repo.png new file mode 100644 index 000000000..0cc36a14a Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-repo.png differ diff --git a/docs/docs/assets/usabilityhub-exporter-target.png b/docs/docs/assets/usabilityhub-exporter-target.png new file mode 100644 index 000000000..3883ad55d Binary files /dev/null and b/docs/docs/assets/usabilityhub-exporter-target.png differ diff --git a/docs/docs/assets/usabilityhub_exporter_target.png b/docs/docs/assets/usabilityhub_exporter_target.png new file mode 100644 index 000000000..d41a323f5 Binary files /dev/null and b/docs/docs/assets/usabilityhub_exporter_target.png differ diff --git a/docs/docs/assets/validation_exportmodels.png b/docs/docs/assets/validation_exportmodels.png new file mode 100644 index 000000000..540a9b1c0 Binary files /dev/null and b/docs/docs/assets/validation_exportmodels.png differ diff --git a/docs/docs/assets/workflow_wizard_export_data_base.png b/docs/docs/assets/workflow_wizard_export_data_base.png new file mode 100644 index 000000000..5f9bd131c Binary files /dev/null and b/docs/docs/assets/workflow_wizard_export_data_base.png differ diff --git a/docs/docs/assets/workflow_wizard_intro.png b/docs/docs/assets/workflow_wizard_intro.png index 99bed338a..540fa6505 100644 Binary files a/docs/docs/assets/workflow_wizard_intro.png and b/docs/docs/assets/workflow_wizard_intro.png differ diff --git a/docs/docs/assets/workflow_wizard_schema_import_linked_models.png b/docs/docs/assets/workflow_wizard_schema_import_linked_models.png new file mode 100644 index 000000000..277e89864 Binary files /dev/null and b/docs/docs/assets/workflow_wizard_schema_import_linked_models.png differ diff --git a/docs/docs/background_info/faq.md b/docs/docs/background_info/faq.md new file mode 100644 index 000000000..1b4c4e25d --- /dev/null +++ b/docs/docs/background_info/faq.md @@ -0,0 +1,7 @@ + + +Q: Why t_basket columns are created for `STRUCTURE` tables? Since those entries belong to objects anyway, they have already the basket of the owner object. + +A: So it's easier (e.g. for ili2db) to delete all data of a basket... diff --git a/docs/docs/background_info/meta_attributes.md b/docs/docs/background_info/meta_attributes.md index 4abc71248..e7d9bdcda 100644 --- a/docs/docs/background_info/meta_attributes.md +++ b/docs/docs/background_info/meta_attributes.md @@ -57,8 +57,11 @@ Some additional non standard meta attributes are understood by the Model Baker a ### List of specific Attributes - **qgis.modelbaker.dispExpression** -Used as the display expression for a layer. The display expression is the *name* that is used to identify a feature by text. One of the places where this is used is the combobox that is shown for a Relation Reference Widget on feature forms. ![relation reference](../assets/meta_attributes_relation_reference.png) + Used as the display expression for a layer. The display expression is the *name* that is used to identify a feature by text. One of the places where this is used is the combobox that is shown for a Relation Reference Widget on feature forms. ![relation reference](../assets/meta_attributes_relation_reference.png) +- **qgis.modelbaker.formOrder** + + Used to define the order of the attributes in the form like `!!@qgis.modelbaker.formOrder=1`. If you define the order of an attribute, all other attributes in the class will have a lower priority, what means when you set the order for one single attribute (the value doesn't matter) it will appear as the first attribute in the corresponding form. ## Extra Meta Attribute File diff --git a/docs/docs/background_info/usabilityhub/modelbaker_integration.md b/docs/docs/background_info/usabilityhub/modelbaker_integration.md index d686ba350..103901a3f 100644 --- a/docs/docs/background_info/usabilityhub/modelbaker_integration.md +++ b/docs/docs/background_info/usabilityhub/modelbaker_integration.md @@ -1,24 +1,9 @@ -According to a model name, paths to *metaconfiguration files* are found in *ilidata.xml*. These *metaconfiguration files* contain, besides configuration parameters, *DatasetMetadata-Ids*. Based on these *DatasetMetadata-Ids* the paths to the *Toppingfiles* are found in the *ilidata.xml*. +## Metaconfiguration -> Other tools might use a different workflow. For example, the *ili2db* is passed the *metaconfiguration file*. There in the *metaconfiguration* then also the model is defined. - -![uml](../../assets/usabilityhub_uml_modelbaker.png) - -#### Workflow -1. The user enters the model name in the [dialog](../../../user_guide/import_workflow/#metaconfiguration-topping). -2. The *ilidata.xml* is parsed for links to *metaconfiguration files* according to the model name. -3. The user selects a *metaconfiguration file*. -4. The *metaconfiguration file* is downloaded. -4. The configurations are read from the *metaconfiguration file*. -5. The configurations are considered in the creation of the physical model. -6. The DatasetMetadata-Ids to the *topping files* are read from the *metaconfiguration file*. -7. The *ilidata.xml* is parsed for links to the *topping files* based on the DatasetMetadata-Ids. -8. The *topping files* are downloaded -9. The information is read from the *topping files* and included in the generation of the QGIS project. - -## ili2db configuration +... and how it's handled in Model Baker. ### General Handling + ili2db configurations are defined in the *metaconfiguration file*. ```ini [ch.ehi.ili2db] @@ -67,16 +52,20 @@ When this parameter is set the *Advanced Options* and *CRS* settings are disable ### Refrencing other INTERLIS models Using the ili2db settings, it is possible to reference other models from *metaconfiguration files*. If the setting contains the value `models=KbS_LV95_v1_4;KbS_Basis`, then this is also adjusted in the Model Baker input mask. Of course, a search for possible *metaconfiguration files* on UsabILIty Hub will be started again, according to the currently set models. See also for that [Multiple Models and their Toppings](#multiple-models-and-their-toppings). -## Toppings and their Configuration -*Topping files* are files that are referenced in the *metaconfiguration* or in other *topping files* like e.g. the *project topping file* and contain the configuration information of the GIS project or parts of it. So they can be form configurations, style attributes, legend tree structures as well as data files. Individual topping files can be used for each tool. +## Toppings + +... and their configuration. + +*Topping files* are files that are referenced in the *metaconfiguration* or in other *topping files* like e.g. the *project topping file* and contain the configuration information of the GIS project or parts of it. So they can be form configurations, style attribute as well as the legend tree structure. Individual topping files can be used for each tool. The Model Baker supports these kinds of *topping files*: - Project topping files: `yaml` files for project settings like legend display, linking to layer configuration files and layer order - QML layer style: `qml` files for layer configurations - Layer definition: `qlr` files for layer definitions -- Data files: `xtf`/`xml`/`itf` files for data import + ### Project Topping (`yaml`) + Information about the project like the layer tree, the layers in the layer tree and the display order may be contained in a *toppingfile*. The `DatasetMetadata-Id` of the file is defined in the *metaconfiguration file* via the parameter `qgis.modelbaker.projecttopping` (or the deprecated `qgis.modelbaker.layertree`). The file is written in `yaml`: @@ -143,6 +132,7 @@ layerorder: ``` #### Layertree + The layertree is described using a tree structure in the `yaml` format. Top level entry is `layertree` (or outdated: `legend`). This entry is not shown in the legend. @@ -173,6 +163,7 @@ The `yaml` file shown above results in a legend structure in *QGIS*. ![uml](../../assets/usabilityhub_qgis_legend.png) ##### Renaming of layers + Usually the existing layers are recognized by the names. This works fine for the most cases. But sometimes (e.g. when having an extended model with layers having the same name like the base model) the layers need to be recognized by other parameters. This gives the possiblity to name the layer as you want. It recognizes layers from the database optionally by `tablename` and `geometrycolumn`. INTERLIS based layers can be identified by the `iliname` as well. It takes the first match of `tablename` or `iliname` and otherwise it looks for the layername. @@ -201,6 +192,7 @@ See the example: Be aware that relations loaded over qml style files rely on the layer names. This means, that you have to be carefull when the style files have been exported with other layer names than defined in the YAML. #### Display Order + The display order of the layers is defined as simple list: ``` layer-order: @@ -209,11 +201,13 @@ layer-order: ``` #### Multiple Models with multiple Project Toppings + Layers with the same data source will not be added twice when the project is regenerated. New layers and subgroups are - if possible - loaded into already existing groups. Otherwise geometry layers are added above and the groups "tables" and "domains" below. Thus legend structures from several *project topping files* are merged. ### Layer Properties Topping (`qml`) + For layer properties like form configurations, symbology etc. `qml` files are loaded as *topping files*. *Right-click on the layer > Export > Save as QGIS Layer Style File...* @@ -251,30 +245,14 @@ The `qlr` topping files are assigned directly in the layertree of the *project t !!! Note The datasource in the QLR file is relative. This means you have to be carefull with QLR files providing file based datasources. -### Catalogs and transfer files -Catalogs and transferfiles (and other `itf`/`xtf`/`xml` files) can also be loaded as *toppingfiles*. The `DatasetMetadata-Ids` are defined in the *Metaconfigurationfile* via the global parameter `ch.interlis.referenceData`. Multiple ids and file paths can be specified (separated by `;`). -These data files are added to the list of files to import in the [wizard](../../../user_guide/import_workflow/#import-of-interlis-data). +## Referenced Data -## Multiple Models and their Toppings -Currently, a list of "LegendeEintrag_PlanGewaesserschutz_V1_1;KbS_LV95_V1_4;KbS_Basis_V1_4" lists the *metaconfiguration files* for all these models. -![multimodels](../../assets/usabilityhub_multimodels.png) -But then only one can be selected. If you want to select multiple *metaconfiguration files*, you have to import the models one after the other. - -### Best Practice -It is best to make a *metaconfiguration file* that applies to the import of all models you usually choose. And to make the whole thing even more convenient, you can also configure the additional model in the *metaconfiguration file*. -If a *metaconfiguration file* is valid for the import of both models "KbS_LV95_V1_4;KbS_Basis_V1_4", you can also configure both models in it: -```ini -[ch.ehi.ili2db] -models = KbS_Basis_V1_4;KbS_Basis_V1_4 -``` -Thus the *Metaconfigurations* is found by both model names and when reading in "KbS_LV95_V1_4;KbS_Basis_V1_4" is loaded into the input mask of the Model Baker. - -## Using a local repository -It can be useful for testing purposes to be able to use a local repository. This is configured as a [custom model directory](../../../user_guide/plugin_configuration/#custom-model-directories). `ilidata.xml` and `ilimodels.xml` are searched and parsed in it. +Catalogs and transferfiles (and other `itf`/`xtf`/`xml` files) can also be loaded. The `DatasetMetadata-Ids` are defined in the *Metaconfigurationfile* via the global parameter `ch.interlis.referenceData`. Multiple ids and file paths can be specified (separated by `;`). +These data files are added to the list of files to import in the [wizard](../../../user_guide/import_workflow/#import-of-interlis-data). -## Directly Referenced Catalogues +### Directly Referenced Catalogues Catalogues can be linked directly in the ilidata.xml to the model names (without using a meta configuration file). Just add them as `referenceData` and add the model names in the `categories`. @@ -325,3 +303,21 @@ But already before the data import, the Model Baker checks the UsabILIty Hub for ``` + +## Multiple Models and their Toppings + +Currently, a list of "LegendeEintrag_PlanGewaesserschutz_V1_1;KbS_LV95_V1_4;KbS_Basis_V1_4" lists the *metaconfiguration files* for all these models. +![multimodels](../../assets/usabilityhub_multimodels.png) +But then only one can be selected. If you want to select multiple *metaconfiguration files*, you have to import the models one after the other. + +### Best Practice +It is best to make a *metaconfiguration file* that applies to the import of all models you usually choose. And to make the whole thing even more convenient, you can also configure the additional model in the *metaconfiguration file*. +If a *metaconfiguration file* is valid for the import of both models "KbS_LV95_V1_4;KbS_Basis_V1_4", you can also configure both models in it: +```ini +[ch.ehi.ili2db] +models = KbS_Basis_V1_4;KbS_Basis_V1_4 +``` +Thus the *Metaconfigurations* is found by both model names and when reading in "KbS_LV95_V1_4;KbS_Basis_V1_4" is loaded into the input mask of the Model Baker. + +## Using a local repository +It can be useful for testing purposes to be able to use a local repository. This is configured as a [custom model directory](../../../user_guide/plugin_configuration/#custom-model-directories). `ilidata.xml` and `ilimodels.xml` are searched and parsed in it. diff --git a/docs/docs/background_info/usabilityhub/overview.md b/docs/docs/background_info/usabilityhub/overview.md new file mode 100644 index 000000000..fff51a388 --- /dev/null +++ b/docs/docs/background_info/usabilityhub/overview.md @@ -0,0 +1,114 @@ +## What is it about? + +With Model Baker ***additional information*** for models can be found automatically via the web. + +***Additional information*** such as: + +- ili2db settings ([Metaconfiguration](#metaconfiguration)) +- Data files, like catalogs ([Referenced Data](#referenced-data)) +- QGIS project configurations (so called [Toppings](#toppings)) + +This means that complex configurations can be made *once* and used *multiple times*. + +### Metaconfiguration + +The metaconfiguration can be found before creating the physical data model on the *Schema Import Configuration* page. + +![metaconfig](../../assets/usabilityhub-abstract-metaconfig.png) + +The metaconfiguration can contain the ili2db settings as well as links to the required QGIS project configurations (toppings) and data files (referenced data). + +Find technical background and detailed information about the metaconfiguration [here](../modelbaker_integration/#metaconfiguration) + +### Referenced data + +The referenced data required for a model, such as catalogs and codelists, can be found in the *Data Import Configuration*. + +![referenced data](../../assets/usabilityhub-abstract-referenceddata.png) + +They may already have been linked via the [metaconfiguration](#metaconfiguration) before as well. + +Find technical background and detailed information about the referenced data integration [here](../modelbaker_integration/#referenced-data). + +### Toppings + +The QGIS project configurations or so called "toppings" can - if not already linked via the [metaconfiguration](#metaconfiguration) - be found each time on the *Project Generation* page via a "projecttopping" file. + +![projecttopping](../../assets/usabilityhub-abstract-projecttopping.png) + +The projecttopping defines general project configurations such as layertree, variables etc. and links to the required toppings such as layerstyle etc. which are then downloaded and applied when the project is generated. + +![topping download](../../assets/usabilityhub-abstract-toppingdownload.png) + +Find technical background and detailed information about the toppings [here](../modelbaker_integration/#toppings). + +## Where do those additional information come from? + +Just as we can now find INTERLIS models by searching the ilimodels.xml files on the repositories we can find this additional information via the `ilidata.xml` file. + +It filters the entries by the ***name*** of the used INTERLIS ***model***. + +More information about the technical background you can find [here](../../background_info/usabilityhub/technical_concept.md) + +## What are the Workflows? + +All these ***additional information*** are concernig a specific model. That's why they are found according to the selected model's name. + +![model selection](../../assets/usabilityhub-abstract-modelselection.png) + +### On choosing a metaconfiguration + +...that links to *referenced data* and a *projecttopping* the workflow looks like this: + +1. User enters the model name in the ***Source Selection*** +2. *ilidata.xml* is parsed for links to *metaconfiguration files* according to the model name +3. User selects a *metaconfiguration* + + ![metaconfig](../../assets/usabilityhub-abstract-metaconfig.png) + +4. *Metaconfiguration file* is downloaded and the ili2db settings are read from the *metaconfiguration* +5. ili2db settings are considered in the creation of the physical model +6. Links to the *referenced data* are read from the *metaconfiguration* +7. *ilidata.xml* is parsed for links to the *referenced data* +8. *Referenced data files* are downloaded and imported +9. Links to the *projecttopping* is read from the *metaconfiguration* +10. *ilidata.xml* is parsed for links to the *projecttopping* +11. *Projecttopping file* is downloaded and links to the *other toppings* (like layerstyles etc.) is read from the *projecttopping* +12. *ilidata.xml* is parsed for links to the *toppings* +13. *Topping files* are downloaded +14. The information is read from the *projettopping* and the linked *toppings* and included in the generation of the QGIS project + +### On choosing referenced data directly + +...from the repositories in the ***Data Import Configuration*** the steps are: + +1. *ilidata.xml* is parsed for links to the *referenced data* according to the model name. +2. User selects *referenced data* + + ![referenced data](../../assets/usabilityhub-abstract-referenceddata.png) + +3. *Referenced data files* are downloaded and imported + +!!! Note + The links to the *referenced data* are found according to the used model name. + +### On choosing project topping directly + +... from the repositories in ***Project Generation*** the steps are: + +1. *ilidata.xml* is parsed for links to the *projecttoppings* according to the model name +2. User selects a *projecttopping* + + ![projecttopping](../../assets/usabilityhub-abstract-projecttopping.png) + +3. *Projecttopping file* is downloaded and links to the *other toppings* (like layerstyles etc.) is read from the *projecttopping* +4. *ilidata.xml* is parsed for links to the *toppings* +5. *Topping file* are downloaded +6. The information is read from the *projettopping* and the linked *toppings* and included in the generation of the QGIS project. + +!!! Note + A *projecttopping* can be chosen from the local system as well. + +## How to make my own Toppings? + +This can be easily made with the [Model Baker Topping Exporter](../../user_guide/topping_exporter.md) from an exiting QGIS Project. diff --git a/docs/docs/background_info/usabilityhub/technical_concept.md b/docs/docs/background_info/usabilityhub/technical_concept.md index 6a1a919fc..d1c30e2d2 100644 --- a/docs/docs/background_info/usabilityhub/technical_concept.md +++ b/docs/docs/background_info/usabilityhub/technical_concept.md @@ -1,5 +1,7 @@ -The idea of the UsabILIty Hub is to receive additional information for implemented INTERLIS models automatically via the web. -Just as we can get models by linking the ilimodels.xml file from http://models.interlis.ch and the linked repositories, we can get the additional information with the ilidata.xml file on the UsabILIty Hub (currently https://models.opengis.ch) and the linked repositories. +Just as we can now find INTERLIS models by searching the ilimodels.xml file from models.interlis.ch and the linked repositories, we can find additional information via the `ilidata.xml` file. + +!!! Note + The entry point is not models.interlis.ch but models.opengis.ch, which in turn links to models.interlis.ch. Settings for tools (like ili2db or Model Baker) are configured in a metaconfiguration file, as well as links to topping files that contain information about GIS project (such as symbologies or legend structures). Thus, this additional information usually consists of a metaconfiguration and any number of toppings. @@ -90,7 +92,7 @@ In the UsabILIty Hub implementation of the Model Baker, the following types are #### Generic However, the content of the `Code_` element is not strictly defined. As long as it is a URL, it is up to the tool developer how she wants to use it. -> At the moment the Model Baker does not use generic categories. +> At the moment the Model Baker uses a generic category to know for what data source this topping is made for: `http://codes.modelbaker.ch/preferredDataSource` what can be `pg` and `gpkg`. ## The ilisite.xml The *ilisite.xml* is based on the model `IliSite09`. It contains the class (elements) `SiteMetadata` where URLs to other repositories are defined. These repositories in turn manage an *ilimodel.xml* or - likewise - an *ilidata.xml*. diff --git a/docs/docs/background_info/usabilityhub/user_guide.md b/docs/docs/background_info/usabilityhub/user_guide.md index 770bbbdb4..3b83e2c59 100644 --- a/docs/docs/background_info/usabilityhub/user_guide.md +++ b/docs/docs/background_info/usabilityhub/user_guide.md @@ -169,7 +169,7 @@ ili2db.mapping=MultiSurface #### Transfer files (e.g. Catalogs) (`xtf`/`xml`/`itf` Files) Transfer files such as catalogs can also be used as toppings. In the project *Nutzungsplanung_V310*, however, none were specified. -For information and examples about the referencing of those files see in the [Model Baker Integration](../modelbaker_integration/#catalogs-and-transfer-files) +For information and examples about the referencing of those files see in the [Model Baker Integration](../modelbaker_integration/#referenced-data) ### 3. Storage and Indexing of the Toppings diff --git a/docs/docs/user_guide/export_workflow.md b/docs/docs/user_guide/export_workflow.md index 61699e94a..8c09e8464 100644 --- a/docs/docs/user_guide/export_workflow.md +++ b/docs/docs/user_guide/export_workflow.md @@ -1,5 +1,12 @@ -You can export your data from an physical database into an `xtf` file (INTERLIS transfer file). Select *Export data from an existing database* in the intro page of the wizard. -## Database Selection +You can export your data from an physical database into an `xtf` file (INTERLIS transfer file). + +The wizard is started over the toolbar icon or *Database > Model Baker > Import/Export Wizard*. + +![wizard intro](../assets/workflow_wizard_intro.png) + +Select *Export data from an existing database*. + +## 1. Database Selection First you have to select the database schema or file to export your data from. @@ -9,9 +16,10 @@ For more detailed description of the connection parameters, see the description When the database or the schema / file does not exist, a warning will appear. -## Export data +## 2. Export data ![wizard export data](../assets/workflow_wizard_export_data.png) + ### XTF File Set the `xtf` file where you want to export your data to. @@ -20,13 +28,22 @@ Set the `xtf` file where you want to export your data to. You can filter the data *either* by models *or* - if the database considers [Dataset and Basket Handling](../../background_info/basket_handling/) - by datasets *or* baskets. You can choose multiple models/datasets/baskets. But only one kind of filter (`--model`, `--dataset`, `--basket`) is given to the ili2db command (it would make no conjunction (AND) but a disjunction (OR) if multiple parameters are given (what is not really used). A conjunction can still be done by selecting the smallest instance (baskets)). -## Run ili2db Sessions +### Export Models + +The export models do not define the data that should be exported, but in what *format* they should be exported. This is relevant if you use *extended* models: You have your data stored in your extended model, but you export it in the *format* of the base model. + +![export base](../assets/workflow_wizard_export_data_base.png) + +!!! Note + When no model is selected, the data are exported in the format of the model it is saved in. Multiple model selection makes sense here, when you have multiple models extended. + +## 3. Run ili2db Sessions In the next step you can run the export in one single ili2db command. With the ![run arrow_button](../assets/arrow_button.png) button next to *Run* the options are provided to run the command without any validation of your data or to edit the command manually before running it. -## Data Validation +### Data Validation If you did not choose *Run without constraints* on your export session, then the data are validated against their INTERLIS models. If this validation did not succeed, then the export will fail. diff --git a/docs/docs/user_guide/get_started.md b/docs/docs/user_guide/get_started.md index 9ac2fa11a..b3bc76901 100644 --- a/docs/docs/user_guide/get_started.md +++ b/docs/docs/user_guide/get_started.md @@ -2,7 +2,10 @@ 1. [Install QGIS 3](https://qgis.org/en/site/forusers/download.html) -2. Use the plugin manager to install the "QGIS Model Baker" plugin. +2. Use the plugin manager to install the "Model Baker" plugin. + + ![Plugin Manager](../assets/plugin_manager.png) + ## The Model Baker Functionalities @@ -11,16 +14,56 @@ After the installation you can find all the Features in the *Database > Model Ba ![menu](../assets/menu.png) ### Import / Export Wizard -The wizard contains all the functionalities to create database schemas from INTERLIS models, import / export transferdata and generate QGIS projects from the database. It leads you through the process with all the possiblities you have with the single dialogs. Find a guide through the [import and generate process with the wizard](../import_workflow/) and through the [export process with the wizard](../export_workflow/) in this documentation. + +The wizard contains all the functionalities to create database schemas from INTERLIS models, import / export transferdata and generate QGIS projects from the database. It leads you through the process with all the possiblities you have with the single dialogs. + +![workflow_wizard_intro](../assets/workflow_wizard_intro.png) + +Find a guide through the [import and generate process with the wizard](../import_workflow/) and through the [export process with the wizard](../export_workflow/) in this documentation. ### Data Validator -The Data Validator provides you the possiblity to check the data currently open in your QGIS against an INTERLIS model. You can open the validator panel as well over *View > Panels > Model Baker Data Validator*. See for more information about it [Validate Data](../user_guide/validation.md) + +The Data Validator provides you the possiblity to check the data currently open in your QGIS against an INTERLIS model. You can open the validator panel as well over *View > Panels > Model Baker Data Validator*. + +![validation](../assets/validation.png) + +See for more information about it [Validate Data](../user_guide/validation.md) ### Dataset Manager -The dataset manager provides you the possiblity to create and rename datasets and generate the baskets for the datasets. More information you can find in the [Dataset and Basket Handling](../background_info/basket_handling.md) + +The dataset manager provides you the possiblity to create and rename datasets and generate the baskets for the datasets. + +![dataset-manager](../assets/dataset_basket_manager.png) + +More information you can find in the [Dataset and Basket Handling](../background_info/basket_handling.md) + +### OID Manager + +With the OID Manager you can view and set the handling of the OIDs in the current project like the default value expressions and their visibility. + +![oid-mangaer](../assets/oid_tid_manager.png) + +Find further information about [OIDs in general and the OID Manager](../background_info/oid_tid_generator.md) + +### UsabILIty Hub Topping Exporter + +In case you plan to create your own [UsabILIty Hub](../background_info/usabilityhub/modelbaker_integration.md) topping set, then you can use the [Topping Exporter](../user_guide/topping_exporter.md). + +![usabilityhub-exporter](../assets/usabilityhub_exporter_target.png) + +### Settings + +In keeping with aristotle, unnecessary settings are avoided. Still there are some. Find it in [Plugin Configuration](plugin_configuration.md). + +![settings](../assets/settings_general.png) + +### Show Log Folder + +To view all Model Baker or ili2db logs, view the files in the corresponding folder. ## The Model Baker Toolbar -Most of the functionalities are available in the toolbar as well. + +Some functionalities are available in the toolbar as well, like the Import / Export Wizard and the Dataset Manager. ![toolbar](../assets/toolbar.png) diff --git a/docs/docs/user_guide/import_workflow.md b/docs/docs/user_guide/import_workflow.md index caa03c767..5fa2cda14 100644 --- a/docs/docs/user_guide/import_workflow.md +++ b/docs/docs/user_guide/import_workflow.md @@ -8,13 +8,14 @@ To [choose data files and models to import or generate a new database](#source-s !!! Note As well the Wizard opens when you drop a file to QGIS with the extension `xtf`, `ili` or `xml` (`xml` only when it's dropped with a file having one of the other extensions). +## 1. Source Selection -## Source Selection First page offers you to select the sources to import. ![wizard source selection](../assets/workflow_wizard_source_selection.png) ### INTERLIS Models + Sources can be INTERLIS models stored in `ili` files you select from your local system (with the file browser ![file_browser](../assets/file_browser_button.png) or with drag'n'drop). As well you can search for INTERLIS models in the [repositories](../../background_info/repositories) or [custom model directories](../plugin_configuration/#custom-model-directories). Since model names should be given strictly as they were spelled in INTERLIS files, once you start typing, autocompletion will help you discover available models with their correct spelling. Add them wiht the ![plus button](../assets/plus_button.png). @@ -25,11 +26,12 @@ As well you can search for INTERLIS models in the [repositories](../../backgroun This leads you to a process to create the physical database in *PostgreSQL*, *MSSQL* or *GeoPackage*. ### Transfer and Catalogue Files (Data Files) + The `xtf` is an INTERLIS transfer file, containing spatial and/or alphanumeric data stored in XML format. Catalogues or Codelists are technically the same but have usually `xml` as extension. The selection of data files leads you to the process to import the data into a physical database. -## Database Selection +## 2. Database Selection In any case you are requested to set the connection to your database. @@ -43,8 +45,10 @@ In any case you are requested to set the connection to your database. - **User Password** Set the password for the database user. - **Execute data management tasks with superuser login from settings** If checked, it uses the superuser login (set in the [plugin configurations](../plugin_configuration/) for data management tasks like the creation of the schema etc. -## Import of INTERLIS Model +## 3. Import of INTERLIS Model + ### Model selection + There are several ways the Model Baker wizard detects INTERLIS models to import. - Read from the selected local `ini` file. @@ -59,6 +63,10 @@ When you only got a model name (like in all cases except the one of the local `i You can check or uncheck the models you want to import to a physical schema. +!!! Note + If our model requires (according to the ilidata.xml) a codelist and this codelist bases on a model that is not structurally linked (imported) to our model, it will appear here as well. + ![linked model](../assets/workflow_wizard_schema_import_linked_models.png) + ### Metaconfiguration / Topping Choose a metaconfiguration file found on the [UsabILIty Hub](../../background_info/usabilityhub/modelbaker_integration/) to load ili2db settings and styling properties to your QGIS project. @@ -99,7 +107,7 @@ You can define `sql` scripts that runs before and after the (schema) import. A `toml` or `ini` file can contain values for [meta attributes](../../background_info/meta_attributes/) (like `qgis.modelbaker.dispExpression`) instead of having them directly in the `ili` file. -## Run ili2db Sessions +## 4. Run ili2db Sessions In the next step you can run all the sessions to create your physical model. If having multiple models selected that are received from the repositories, then they are passed in one command. You can run the commands one by one or all together. @@ -107,7 +115,7 @@ In the next step you can run all the sessions to create your physical model. If With the ![run arrow_button](../assets/arrow_button.png) button next to *Run* the options are provided to run the command without checking constraints or to edit the command manually before running it. -## Create Baskets +## 5. Create Baskets In case you don't have data to import into your default dataset and want to collect ***fresh*** data in QGIS, the baskets have to be created as well. It's up to you for what topics you want to create baskets. Model Baker suggests you what baskets should be created and reasonalbe values for the BID (value in the `t_ili_tid`) but you might need. to edit them. @@ -115,7 +123,7 @@ In case you don't have data to import into your default dataset and want to coll If you don't know what it is about, check more details [here](../../background_info/basket_handling/#creation-of-baskets) or just press *Create baskets* and then *Next*. -## Import of INTERLIS Data +## 6. Import of INTERLIS Data After the physial model is generated or you selected an existing database to import your transfer or catalogue files to containing the models already, you will see the page to set up your data imports. @@ -147,7 +155,7 @@ Check more information about the catalogues on the *UsabILIty Hub* [here](../../ If you want to delete the data in the database first, you can check the corresponding box. On using baskets, the ili2db parameter `--replace` is executed instead of `--update`. On not using baskets, the parameter `--deleteData` is added to the command. Note that on using baskets, only the data from the corresponding dataset is deleted, whereas on not using baskets all data from the schema is deleted. -## Generate the QGIS Project +## 7. Generate the QGIS Project In case you want to generate your project from an existing database, you will need to [set the connection parameters](#database-selection) first. @@ -181,7 +189,7 @@ Choose your optimization strategy in the checkbox: For more information about the optimization of extended models, see the [corresponding chapter](../../background_info/extended_models_optimization). -### OID Values +## 8. OID Values Often the models definition requires cross-system unique identificators. So called OIDs, what are represented in the physical database as the `t_ili_tid` column. Find a clear definition and more details about them in the [corresponding chapter](../../background_info/oid_tid_generator). diff --git a/docs/docs/user_guide/topping_exporter.md b/docs/docs/user_guide/topping_exporter.md new file mode 100644 index 000000000..3263c3f5b --- /dev/null +++ b/docs/docs/user_guide/topping_exporter.md @@ -0,0 +1,93 @@ +After importing the INTERLIS model and creating the QGIS project with Model Baker, you have made many additional configurations and settings. + +- Categorized layer symbology +- Form configurations +- Changes to the layer tree +- Additional WMS layers +- Project variables +- Print layouts +- ...and much more + +![project](../assets/usabilityhub-exporter-project.png) + +Since you don't want to make these settings again and share your work with others, you decide to create your own metaconfiguration and toppings and make them available in your repository. + +So, find the **Topping Exporter** in the menu *Database > Model Baker > UsabILItyHub Topping Exporter* + +## 1. General information about the topic + +First you need to enter some general information about your topic. This will be in the index file (ilidata.xml) and defines the folder structure. + +![target](../assets/usabilityhub-exporter-target.png) + +## 2. Model and Source + +Your currently opened project is parsed for INTERLIS models on which it is based. + +Your metaconfiguration and your project topping will be filtered by this model name(s). + +Normally your project is based on one model, but if there are others, you can deactivate them as filter parameters. + +![model and source](../assets/usabilityhub-exporter-model.png) + +Also the available metaconfigurations and toppings will be filtered by the data source (as most toppings created for PostGIS do not work for GeoPackage and vice versa). + +If you do not wish to filter by data source, select "No source defined (allow all)". + +## 3. Project Layers + +On this page you can see the layer tree of your current project and you can specify how you want to save the layer information to the topping files. + +![layers](../assets/usabilityhub-exporter-layer.png) + +- With **Style (QML)** all layer settings (symbology, shapes, layer variables, etc.) are written to a layer style (`qml`) fle. This means that it can be applied to a layer with a different data source. This is the ideal case for the toppings you want to apply to the layers of your INTERLIS model. + + This ![icon](../assets/usabilityhub-exporter-layer-styleicon.png) button opens a dialog in which you can select which styling properties are to be taken into account. + +- With **Definition (QLR)** the complete layer definition including source path and styling is saved into a `qlr` file. This is useful for layers that are not based on the INTERLIS model for which you are creating your topping. In this example it would perhaps make sense to save the "Hintergrundkarten" group in a definition file. + +- With **Source** only the original data source path is written directly to the project topping file. This is useful for WMS layers or layers from accessible databases that are not based on INTERLIS models (or at least not on the ones for which we use this topping) + +!!! Note + If you want to remove layers, then you can do that in your project and press "Reset" in the Topping Exorter. + +## 4. Variables and Print Layouts + +There are other settings that are automatically exported and that you cannot activate or deactivate. For example: +- Layer Order +- Transaction Mode + +For some specific configurations, however, it is useful to decide what should be exported. On this page, you can select or unselect your map themes, variables and print layouts. + +![additives](../assets/usabilityhub-exporter-additive-settings.png) + +## 5. Referenced Data (Catalogues) + +Your metaconfiguration can reference a data file (such as a catalog) that Model Baker automatically finds and imports. + +![Reference](../assets/usabilityhub-exporter-reference.png) + +Here you can add a local file (which will be added to your setup) or select an existing file from the public repositories. + +## 6. ili2db Settings + +Finally, you can select whether the ili2db settings of your current schema (means the ili2db settings that has been used to create your current schema) should be considered. + +![ili2db-settings](../assets/usabilityhub-exporter-ili2db.png) + +!!! Note + Please note that only the settings "known" by Model Baker are parsed. These are the parameters that are automatically set by Model Baker or can be set by the user in the advanced options. If you have edited your ili2db command manually (or have not created it via Model Baker), some settings may be missing. + +You can also select any required SQL scripts and an [extra meta attribute file](../../background_info/meta_attributes.md). + +## 7. Generate your files + +Generate your files. At least one metaconfiguration and one project topping file as well as all required topping files (`qml`, `qlr` etc.) are created + +![generated](../assets/usabilityhub-exporter-generated.png) + +## 8. Taste your toppics + +Test your toppics locally before adding them to your repository. Do this by adding the path of your toppings as [custom model directory](../user_guide/plugin_configuration/#custom-model-directories). `ilidata.xml` and `ilimodels.xml` are searched and parsed in it. + +![localrepo](../assets/usabilityhub-exporter-repo.png) diff --git a/docs/docs/user_guide/validation.md b/docs/docs/user_guide/validation.md index 7ad9baf59..bd1dd0c74 100644 --- a/docs/docs/user_guide/validation.md +++ b/docs/docs/user_guide/validation.md @@ -3,12 +3,21 @@ You can validate your physical data against the INTERLIS models directly in QGIS ![validation](../assets/validation.png) ## Database + The database connection parameter are emitted from the currently selected layer. Mostly this is representative for the whole project, since mostly a project bases on one single database schema/file. In case of multiple used database sources, it's possible to *switch* between the validation results when switching the layers. ## Filters + You can filter the data being validated *either* by models *or* - if the database considers [Dataset and Basket Handling](../../background_info/basket_handling/) - by datasets *or* baskets. You can choose multiple models/datasets/baskets. But only one kind of filter (`--model`, `--dataset`, `--basket`) is given to the ili2db command (it would make no conjunction (AND) but a disjunction (OR) if multiple parameters are given (what is not really used). A conjunction can still be done by selecting the smallest instance (baskets)). +## Validate in the base model + +This is relevant if you use *extended* models: You have your data stored in your extended model, but might want to validate it in the *format* of the base model only. + +![validate base](../assets/validation_exportmodels.png) + ## Skip Geometry Errors + ![validation_skipgeometryerrors](../assets/validation_skipgeometryerrors.png) When the checkbox is activated, geometry errors are ignored and the validation of AREA topology is disabled. Errors like those will not be listed. @@ -21,6 +30,7 @@ When the checkbox is activated, geometry errors are ignored and the validation o In the backend the parameters `--skipGeometryErrors` and `--disableAreaValidation` are set. ## Configuration File + It's possible to enable/disable and name constraints of the current model via meta attributes. For the configuration of those, see the chapter [Set Meta Attributes in the Config File](#set-meta-attributes-in-the-config-file) below. Add it to the validation by selecting it via file browser. @@ -33,6 +43,7 @@ You can save this path to your project (to the project variables) with the ![run You can also use a configuration file from the [ilidata repositories](../../background_info/usabilityhub/technical_concept). Just add the ilidata-key (like `ilidata:`) as the path. ## Results + After running the validation by pressing the ![checkmark](../assets/checkmark_button.png) the results are listed. With *right click* on the error a menu is opened with the following options: @@ -50,6 +61,7 @@ On automatic pan and zoom, the coordinates are taken into account if they are pr Since ili2db sometimes on non-geometry errors provides the coordinates as well, there could be a confusion when it zooms or pans to the coordinates there. Still it's preferable to not zoom or pan to the coordinates on geometry errors when they provide an OID. Currently the validator cannot make a difference between those error-types. ## Using of Meta Attributes in the Validation + As well as configuring [meta attributes](../../background_info/meta_attributes/) used for the physical database implementation and for QGIS project generation, meta attributes can be used for additional configuration of the validation like e.g. disable specific checks generally or on specific objects as well as naming of the constraints. ### Set Meta Attributes in the ILI File @@ -165,6 +177,7 @@ See for all the global configurations the official [documentation of ilivalidato Validation with deactivated validation is useful because it checks if everything is ok with the technical aspects (like `t_typ`, `t_id` etc). ## ili2db with `--validate` in the background + On running the validation `ili2db` is used in the background with the parameter `--validate`. This means no export of the data is needed. The output is parsed by Model Baker and provided in the result list. Entries of the type `Error` and `Warning` are listed. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 080a6d163..84b3365fb 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -41,15 +41,17 @@ nav: - Model and Data Import Workflow: user_guide/import_workflow.md - Export Data Workflow: user_guide/export_workflow.md - Validate Data: user_guide/validation.md + - Topping Exporter: user_guide/topping_exporter.md - Plugin Configuration: user_guide/plugin_configuration.md - Tipps & Tricks: - Repositories: background_info/repositories.md - Basket and Dataset Handling: background_info/basket_handling.md - OID Generator: background_info/oid_tid_generator.md - UsabILIty Hub: + - Overview: background_info/usabilityhub/overview.md - Model Baker Integration: background_info/usabilityhub/modelbaker_integration.md - Technical Concept: background_info/usabilityhub/technical_concept.md - - User Guide: background_info/usabilityhub/user_guide.md + #obsolete but keep it for info - User Guide: background_info/usabilityhub/user_guide.md - Optimized Projects for Extended Models: background_info/extended_models_optimization.md - Catalogues and their special cases: background_info/catalogues.md - Meta Attributes: background_info/meta_attributes.md @@ -110,3 +112,4 @@ plugins: primary: white # Page tree + site_description: