From 74e755b1115add10844dee1da835f9e8d7cbc359 Mon Sep 17 00:00:00 2001 From: Darin Kelkhoff Date: Mon, 10 Feb 2025 08:54:02 -0600 Subject: [PATCH] Add details about producing tableMetaData via @QMetaDataProducingEntity and customizers --- docs/metaData/MetaDataProduction.adoc | 68 +++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 9 deletions(-) diff --git a/docs/metaData/MetaDataProduction.adoc b/docs/metaData/MetaDataProduction.adoc index da872485..353d77ff 100644 --- a/docs/metaData/MetaDataProduction.adoc +++ b/docs/metaData/MetaDataProduction.adoc @@ -288,33 +288,49 @@ all of the fields in you table in two places (the entity and the table meta-data If you are using `QRecordEntity` classes that correspond to your tables, then you can take advantage of some additional annotations on those classes, to produce more related meta-data objects associated with those tables. The point of this is to eliminate boilerplate, and simplify / speed up the process of getting a new table -built and deployed in your application, with some bells and whistles added. +built and deployed in your application. + +Furthermore, the case can be made that it is beneficial to keep the meta-data definition for a table as close +as possible to the entity that corresponds to the table. This enables modifications to the table (e.g., adding +a new field/column) to only require edits in one java source file, rather than necessarily requiring edits +in two files. === @QMetaDataProducingEntity -This is an annotation to go on a QRecordEntity class, which you would like to be -processed by `MetaDataProducerHelper`, to automatically produce some meta-data -objects. Specifically supports: +This is an annotation meant to be placed on a `QRecordEntity` subclass, which you would like to be +processed by an invocation of `MetaDataProducerHelper`, to automatically produce some meta-data +objects. -* Making a possible-value-source out of the table. +This annotation supports: + +* Creating table meta-data for the corresponding record entity table. Enabled by setting `produceTableMetaData=true`. +** One may customize the table meta data that is produced automatically by supplying a class that extends +`MetaDataCustomizerInterface` in the annotation attribute `tableMetaDataCustomizer`. +** In addition to (or as an alternative to) the per-table `MetaDataCustomizerInterface` that can be specified +in `@QMetaDataProducingEntity.tableMetaDataCustomzier`, when an application calls +`MetaDataProducerHelper.processAllMetaDataProducersInPackage`, an additional `MetaDataCustomizerInterface` can be +given, to apply a common set of adjustments to all tales being generated by the call. +* Making a possible-value-source out of the table. Enabled by setting `producePossibleValueSource=true`. * Processing child tables to create joins and childRecordList widgets === @ChildTable This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to define child-tables, e.g., for producing joins and childRecordList widgets related to the table defined in the entity class. -=== @ChildJoin +==== @ChildJoin This is an annotation used as a value inside a `@ChildTable` inside a `@QMetadataProducingEntity` annotation, to control the generation of a `QJoinMetaData`, as a `ONE_TO_MANY` type join from the table represented by the annotated entity, to the table referenced in the `@ChildTable` annotation. -=== @ChildRecordListWidget +==== @ChildRecordListWidget This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to control the generation of a QWidgetMetaData - for a ChildRecordList widget. [source,java] -.QRecordEntity with meta-data producing annotations +.QRecordEntity with meta-data producing annotations and a table MetaDataCustomizer ---- @QMetaDataProducingEntity( + produceTableMetaData = true, + tableMetaDataCustomizer = MyTable.TableMetaDataCustomizer.class, producePossibleValueSource = true, childTables = { @ChildTable( @@ -326,13 +342,47 @@ the generation of a QWidgetMetaData - for a ChildRecordList widget. public class MyTable extends QRecordEntity { public static final String TABLE_NAME = "myTable"; - // class body left as exercise for reader + + public static class TableMetaDataCustomizer implements MetaDataCustomizerInterface + { + @Override + public QTableMetaData customizeMetaData(QInstance qInstance, QTableMetaData table) throws QException + { + String childJoinName = QJoinMetaData.makeInferredJoinName(TABLE_NAME, MyChildTable.TABLE_NAME); + + table + .withUniqueKey(new UniqueKey("name")) + .withIcon(new QIcon().withName("table_bar")) + .withRecordLabelFormat("%s") + .withRecordLabelFields("name") + + .withSection(new QFieldSection("identity", new QIcon().withName("badge"), Tier.T1, + List.of("id", "name"))) + // todo additional sections for other fields + .withSection(new QFieldSection("children", new QIcon().withName("account_tree"), Tier.T2) + .withWidgetName(childJoinName)) + + .withExposedJoin(new ExposedJoin() + .withLabel("Children") + .withJoinPath(List.of(childJoinName)) + .withJoinTable(MyChildTable.TABLE_NAME)); + + return (table); + } + } + + @QField(isEditable = false, isPrimaryKey = true) + private Integer id; + + // remaining fields, constructors, getters & setters left as an exercise for the reader and/or the IDE } ---- The class given in the example above, if processed by the `MetaDataProducerHelper`, would add the following meta-data objects to your `QInstance`: +* A `QTableMetaData` named `myTable`, with all fields annotated as `@QField` from the `QRecordEntity` class, +and with additional attributes as set in the `TableMetaDataCustomizer` inner class. * A `QPossibleValueSource` named `myTable`, of type `TABLE`, with `myTable` as its backing table. * A `QJoinMetaData` named `myTableJoinMyChildTable`, as a `ONE_TO_MANY` type, between those two tables. * A `QWidgetMetaData` named `myTableJoinMyChildTable`, as a `CHILD_RECORD_LIST` type, that will show a list of