Initial checkin

2025-07-18 05:01:07 +00:00 · 2023-02-24 15:25:03 -06:00
parent 60056caa2b
commit 9eaa04abbf
14 changed files with 20129 additions and 0 deletions
--- a/docs/Introduction.adoc
+++ b/docs/Introduction.adoc
@ -0,0 +1,8 @@
 = Introduction
 QQQ is ...
 - Framework
 - Declarative
 - Easy thing easy; Hard thing possible
 - Customizable
--- a/docs/Reports.pdf
+++ b/docs/Reports.pdf
--- a/docs/actions/QueryAction.adoc
+++ b/docs/actions/QueryAction.adoc
@ -0,0 +1,179 @@
 == QueryAction
 include::../variables.adoc[]
 The `*QueryAction*` is the basic action that is used to get records from a {link-table}.
 In SQL/RDBMS terms, it is analogous to a `SELECT` statement, where 0 or more records may be found and returned.
 === Examples
 ==== Basic Form
 [source,java]
 ----
 QueryInput input = new QueryInput(qInstance);
 input.setSession(session);
 input.setTableName("orders");
 input.setFilter(new QQueryFilter()
   .withCriteria(new QFilterCriteria("total", GREATER_THAN, new BigDecimal("3.50")))
   .withOrderBy(new QFilterOrderBy("orderDate", false))
 );
 QueryOutput output = new QueryAction.execute(input);
 List<QRecord> records = output.getRecords();
 ----
 === QueryInput
 * `table` - *String, Required* - Name of the table being queried against.
 * `filter` - *QQueryFilter object* - Specification for what records should be returned, based on *QFilterCriteria* objects, and how they should be sorted, based on *QFilterOrderBy* objects.
 * `skip` - *Integer* - Optional number of records to be skipped at the beginning of the result set.
 e.g., for implementing pagination.
 * `limit` - *Integer* - Optional maximum number of records to be returned by the query.
 * `transaction` - *QBackendTransaction object* - Optional transaction object.
 ** Behavior for this object is backend-dependant.
 In an RDBMS backend, this object is generally needed if you want your query to see data that may have been modified within the same transaction.
 * `recordPipe` - *RecordPipe object* - Optional object that records are placed into, for asynchronous processing.
 ** If a *recordPipe* is used, then records cannot be retrieved from the *QueryOutput*.
 Rather, such records must be read from the pipe's `consumeAvailableRecords()` method.
 ** A *recordPipe* should only be used when a *QueryAction* is running in a separate Thread from the record's consumer.
 * `shouldTranslatePossibleValues` - *boolean, default: false* - Controls whether any fields in the table with a *possibleValueSource* assigned to them should have those possible values looked up
 (e.g., to provide text translations in the generated records' `displayValues` map).
 ** For example, if running a query to present results to a user, this would generally need to be *true*.
 But if running a query to provide data as part of a process, then this can generally be left as *false*.
 * `shouldGenerateDisplayValues` - *boolean, default: false* - Controls whether if field level *displayFormats* should be used to populate the generated records' `displayValues` map.
 ** For example, if running a query to present results to a user, this would generally need to be *true*.
 But if running a query to provide data as part of a process, then this can generally be left as *false*.
 * `queryJoins` - *List of QueryJoin objects* - Optional list of tables to be joined with the main *table* specified in the *QueryInput*.
 See QueryJoin below for further details.
 ==== QQueryFilter
 A key component of *QueryInput*, a *QQueryFilter* defines both what records should be included in a query's results (e.g., an SQL `WHERE`), as well as how those results should be sorted (SQL `ORDER BY`).
 * `criteria` - *List of QFilterCriteria* - Individual conditions or clauses to filter records.
 They are combined using the *booleanOperator* specified in the *QQueryFilter*.  See below for further details.
 * `orderBys` - *List of QFilterOrderBy* - List of fields (and directions) to control the sorting of query results.
 In general, multiple *orderBys* can be given (depending on backend implementations).
 * `booleanOperator` - *Enum of AND, OR, default: AND* - Specifies the logical joining operator used among individual criteria.
 * `subFilters` - *List of QQueryFilter* - To build arbitrarily complex queries, with nested boolean logic, 0 or more *subFilters* may be provided.
 ** Each *subFilter* can include its own additional *subFilters*.
 ** Each *subFilter* can specify a different *booleanOperator*.
 ** For example, consider the following *QQueryFilter*, that uses two *subFilters*, and a mix of *booleanOperators*
 [source,java]
 ----
 queryInput.setFilter(new QQueryFilter()
    .withBooleanOperator(OR)
    .withSubFilters(List.of(
       new QQueryFilter().withBooleanOperator(AND)
          .withCriteria(new QFilterCriteria("firstName", EQUALS, "James"))
          .withCriteria(new QFilterCriteria("lastName", EQUALS, "Maes")),
       new QQueryFilter().withBooleanOperator(AND)
          .withCriteria(new QFilterCriteria("firstName", EQUALS, "Darin"))
          .withCriteria(new QFilterCriteria("lastName", EQUALS, "Kelkhoff"))
    )));
 // which would generate the following WHERE clause in an RDBMS backend:
   WHERE (first_name='James' AND last_name='Maes') OR (first_name='Darin' AND last_name='Kelkhoff')
 ----
 ===== QFilterCriteria
 * `fieldName` - *String, required* - Reference to a field on the table being queried.
 ** Or, in the case of a query with *queryJoins*, a qualified name of a field from a join-table (where the qualifier would be the joined table's name or alias, followed by a dot)
 *** For example:  `orderLine.sku` or `orderBillToCustomer.firstName`
 * `operator` - *Enum of QCriteriaOperator, required* - Comparison operation to be applied to the field specified as *fieldName* and the *values* or *otherFieldName*.
 ** e.g., `EQUALS`, `NOT_IN`, `GREATER_THAN`, `BETWEEN`, `IS_BLANK`, etc.
 * `values` - *List of values, conditional* - Provides the value(s) that the field is compared against.
 The number of values (0, 1, 2, or more) be driven based on the *operator* being used.
 If an *otherFieldName* is given, and the *operator* expects 1 value, then *values* is ignored, and *otherFieldName* is used.
 * `otherFieldName` - *String, conditional* - Specifies that the *fieldName* should be compared against another field in the records, rather than the values in the *values* property.
 Only used for *operators* that expect 1 value (e.g., `EQUALS` or `LESS_THAN_OR_EQUALS` - not `IS_NOT_BLANK` or `IN`).
 QFilterCriteria definition examples:
 [source,java]
 ----
 // one-liners, via constructors that take (List<Serializable> values) or (Serializable... values) in 3rd position
 new QFilterCriteria("id", IN, List.of(1, 2, 3))
 new QFilterCriteria("name", IS_BLANK)
 new QFilterCriteria("orderNo", IN, orderNoList)
 new QFilterCriteria("state", EQUALS, "MO");
 // long-form, with fluent setters
 new QFilterCriteria()
   .withFieldName("quantity")
   .withOpeartor(QCriteriaOperator.GREATER_THAN)
   .withValues(List.of(47));
 // to use otherFieldName, long-form must be used
 new QFilterCriteria()
   .withFieldName("firstName")
   .withOpeartor(QCriteriaOperator.EQUALS)
   .withOtherFieldName("lastName");
 // using otherFieldName to build a criterion that looks at two fields from join tables
 new QFilterCriteria()
   .withFieldName("billToCustomer.lastName")
   .withOpeartor(QCriteriaOperator.NOT_EQUALS)
   .withOtherFieldName("shipToCustomer.lastName");
 ----
 ===== QFilterOrderBy
 * `fieldName` - *String, required* - Reference to a field on the table being queried.
 ** Or, in the case of a query with *queryJoins*, a qualified name of a field from a join-table (where the qualifier would be the joined table's name or alias, followed by a dot)
 * `isAscending` - *boolean, default: true* - Specify if the sort is ascending or descending.
 QFilterCriteria definition examples:
 [source,java]
 ----
 // short-form, via constructors
 new QFilterOrderBy("id") // isAscending defaults to true.
 new QFilterOrderBy("name", false)
 // long-form, with fluent setters
 new QFilterOrderBy()
   .withFieldName("birthDate")
   .withIsAscending(true);
 ----
 ==== QueryJoin
 * `joinTable` - *String, required* - Name of the table that is being joined in to the existing query.
 ** Will be inferred from *joinMetaData*, if *joinTable* is not set when *joinMetaData* gets set.
 * `baseTableOrAlias` - *String, required* - Name of a table (or an alias) already defined in the query, to which the *joinTable* will be joined.
 ** Will be inferred from *joinMetaData*, if *baseTableOrAlias* is not set when *joinMetaData* gets set (which will only use the leftTableName from the joinMetaData - never an alias).
 * `joinMetaData` - *QJoinMetaData object* - Optional specification of a {link-join} in the current QInstance.
 If not set, will be looked up at runtime based on *baseTableOrAlias* and *joinTable*.
 ** If set before *baseTableOrAlias* and *joinTable*, then they will be set based on the *leftTable* and *rightTable* in this object.
 * `alias` - *String* - Optional (unless multiple instances of the same table are being joined together, when it becomes required).
 Behavior based on SQL `FROM` clause aliases.
 If given, must be used as the part before the dot in field name specifications throughout the rest of the query input.
 * `select` - *boolean, default: false* - Specify whether fields from the *rightTable* should be selected by the query.
 If *true*, then the `QRecord` objects returned by this query will have values with corresponding to the (table-or-alias `.` field-name) form.
 * `type` - *Enum of INNER, LEFT, RIGHT, FULL, default: INNER* - specifies the SQL-style type of join being performed.
 QueryJoin definition examples:
 [source,java]
 ----
 // selecting from an "orderLine" table - then join to its corresponding "order" table
 queryInput.withTableName("orderLine");
 queryInput.withQueryJoin(new QueryJoin("order").withSelect(true));
 ...
 queryOutput.getRecords().get(0).getValueBigDecimal("order.grandTotal");
 // given an "order" table with 2 foreign keys to a customer table (billToCustomerId and shipToCustomerId)
 // Note, we must supply the JoinMetaData to the QueryJoin, to drive what fields to join on in each case.
 queryInput.withTableName("order");
 queryInput.withQueryJoins(List.of(
   new QueryJoin(instance.getJoin("orderJoinShipToCustomer")
       .withAlias("shipToCustomer")
       .withSelect(true)),
   new QueryJoin(instance.getJoin("orderJoinBillToCustomer")
       .withAlias("billToCustomer")
       .withSelect(true))));
 ...
 record.getValueString("billToCustomer.firstName")
   + " placed an order for "
   + record.getValueString("shipToCustomer.firstName")
 ----
 === QueryOutput
 * `records` - *List of QRecord* - List of 0 or more records that match the query filter.
 ** _Note:  If a *recordPipe* was supplied to the QueryInput, then calling `queryOutput.getRecords()` will result in an `IllegalStateException` being thrown - as the records were placed into the pipe as they were fetched, and cannot all be accessed as a single list._
--- a/docs/actions/RenderTemplateAction.adoc
+++ b/docs/actions/RenderTemplateAction.adoc
@ -0,0 +1,33 @@
 == RenderTemplateAction
 include::../variables.adoc[]
 The `*RenderTemplateAction*` performs the job of taking a template - that is, a string of code, in a templating language, such as https://velocity.apache.org/engine/1.7/user-guide.html[Velocity], and merging it with a set of data (known as a context), to produce some using-facing output, such as a String of HTML.
 === Examples
 ==== Canonical Form
 [source,java]
 ----
 RenderTemplateInput input = new RenderTemplateInput(qInstance);
 input.setSession(session);
 input.setCode("Hello, ${name}");
 input.setTemplateType(TemplateType.VELOCITY);
 input.setContext(Map.of("name", "Darin"));
 RenderTemplateOutput output = new RenderTemplateAction.execute(input);
 String result = output.getResult();
 assertEquals("Hello, Darin", result);
 ----
 ==== Convenient Form
 [source,java]
 ----
 String result = RenderTemplateAction.renderVelocity(input, Map.of("name", "Darin"), "Hello, ${name}");
 assertEquals("Hello, Darin", result);
 ----
 === RenderTemplateInput
 * `code` - *String, Required* - String of template code to be rendered, in the templating language specified by the `type` parameter.
 * `type` - *Enum of VELOCITY, Required* - Specifies the language of the template code.
 * `context` - *Map of String → Object* - Data to be made available to the template during rendering.
 === RenderTemplateOutput
 * `result` - *String* - Result of rendering the input template and context.
--- a/docs/actions/RenderTemplateAction.pdf
+++ b/docs/actions/RenderTemplateAction.pdf
--- a/docs/docinfo.html
+++ b/docs/docinfo.html
@ -0,0 +1,27 @@
 <!--
  ~ QQQ - Low-code Application Framework for Engineers.
  ~ Copyright (C) 2021-2022.  Kingsrook, LLC
  ~ 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
  ~ contact@kingsrook.com
  ~ https://github.com/Kingsrook/
  ~
  ~ This program is free software: you can redistribute it and/or modify
  ~ it under the terms of the GNU Affero General Public License as
  ~ published by the Free Software Foundation, either version 3 of the
  ~ License, or (at your option) any later version.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
  ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  ~ GNU Affero General Public License for more details.
  ~
  ~ You should have received a copy of the GNU Affero General Public License
  ~ along with this program.  If not, see <https://www.gnu.org/licenses/>.
  -->
 <style>
   pre
   {
      white-space: pre;
   }
 </style>
--- a/docs/index.adoc
+++ b/docs/index.adoc
@ -0,0 +1,17 @@
 = QQQ
 :doctype: book
 :toc: left
 :source-highlighter: coderay
 include::Introduction.adoc[leveloffset=+1]
 == Meta Data
 include::metaData/Tables.adoc[leveloffset=+1]
 ''''
 include::metaData/Reports.adoc[leveloffset=+1]
 == Actions
 include::actions/QueryAction.adoc[leveloffset=+1]
 ''''
 include::actions/RenderTemplateAction.adoc[leveloffset=+1]
 ''''
--- a/docs/index.html
+++ b/docs/index.html
--- a/docs/index.pdf
+++ b/docs/index.pdf
--- a/docs/metaData/Fields.adoc
+++ b/docs/metaData/Fields.adoc
@ -0,0 +1,24 @@
 == QQQ Fields
 include::../variables.adoc[]
 QQQ Fields define
 === QFieldMetaData
 *QFieldMetaData Properties:*
 * `name` - *String, Required* - Unique name for the field within its container (table, process, etc).
 * `label` - *String* - User-facing label for the field, presented in User Interfaces.
 * `type` - *enum of QFieldType, Required* - Data type for values in the field.
 * `backendName` - *String* - Name of the field within its backend.
 ** For example, in an RDBMS-backed table, a field's `name` may be written in camel case, but its `backendName` written with underscores.
 * `isRequired` - *boolean, default false* - Indicator that a value is required in this field.
 * `isEditable` - *boolean, default true* - Indicator that users may edit values in this field.
 * `displayFormat` - *String, default `%s`* - Java Format Specifier string, used to format values in the field for display in user interfaces.
 Used to set values in the `displayValues` map within a `QRecord`.
 ** Recommended values for `displayFormat` come from the `DisplayFormat` interface, such as `DisplayFormat.CURRENCY`, `DisplayFormat.COMMAS`, or `DisplayFormat.DECIMAL2_COMMAS`.
 * `defaultValue` - Value to use for the field if no other value is given.  Type is based on the field's `type`.
 * `possibleValueSourceName` - *String* - Reference to a {link-pvs} to be used for this field.
 Values in this field should correspond to ids from the referenced Possible Value Source.
 * `maxLength` - *Integer* - Maximum length (number of characters) allowed for values in this field.
 Only applicable for fields with `type=STRING`.
 * `
--- a/docs/metaData/Reports.adoc
+++ b/docs/metaData/Reports.adoc
@ -0,0 +1,173 @@
 == QQQ Reports
 include::../variables.adoc[]
 QQQ can generate reports based on {link-tables} defined within a QQQ Instance.
 Users can run reports, providing input values.
 Alternatively, application code can run reports as needed, supplying input values.
 === QReportMetaData
 Reports are defined in a QQQ Instance with a `*QReportMetaData*` object.
 Reports are defined in terms of their sources of data (`QReportDataSource`), and their view(s) of that data (`QReportView`).
 *QReportMetaData Properties:*
 * `name` - *String, Required* - Unique name for the report within the QQQ Instance.
 * `label` - *String* - User-facing label for the report, presented in User Interfaces.
 Inferred from `name` if not set.
 * `processName` - *String* - Name of a {link-process} used to run the report in a User Interface.
 * `inputFields` - *List of {link-field}* - Optional list of fields used as input to the report.
 ** The values in these fields can be used via the syntax `${input.NAME}`, where `NAME` is the `name` attribute of the `inputField`.
 ** For example:
 [source,java]
 ----
 // given this inputField:
 new QFieldMetaData("storeId", QFieldType.INTEGER)
 // its run-time value can be accessed, e.g., in a query filter under a data source:
 new QFilterCriteria("storeId", QCriteriaOperator.EQUALS, List.of("${input.storeId}"))
 // or in a report view's title or field formulas:
 .withTitleFields(List.of("${input.storeId}"))
 new QReportField().withName("storeId").withFormula("${input.storeId}")
 ----
 * `dataSources` - *List of QReportDataSource, Required* - Definitions of the sources of data for the report.
 At least one is required.
 ==== QReportDataSource
 Data sources for QQQ Reports can either reference {link-tables} within the QQQ Instance, or they can provide custom code in the form of a `CodeReference` to a  `Supplier`, for use cases such as a static data tab in an Excel report.
 *QReportDataSource Properties:*
 * `name` - *String, Required* - Unique name for the data source within its containing Report.
 * `sourceTable` - *String, Conditional* - Reference to a {link-table} in the QQQ Instance, which the data source queries data from.
 * `queryFilter` - *QQueryFilter* - If a `sourceTable` is defined, then the filter specified here is used to filter and sort the records queried from that table when generating the report.
 * `staticDataSupplier` - *QCodeReference, Conditional* - Reference to custom code which can be used to supply the data for the data source, as an alternative to querying a `sourceTable`.
 ** Must be a `JAVA` code type
 ** Must be a `REPORT_STATIC_DATA_SUPPLIER` code usage.
 ** The referenced class must implement the interface: `Supplier<List<List<Serializable>>>`.
 ==== QReportView
 Report Views control how the source data for a report is organized and presented to the user in the output report file.
 If a DataSource describes the rows for a report (e.g., what table provides what records), then a View may be thought of as describing the columns in the report.
 A single report can have multiple views, specifically, for the use-case where an Excel file is being generated, in which case each View creates a tab or sheet within the `xlsx` file.
 *QReportView Properties:*
 * `name` - *String, Required* - Unique name for the view within its containing Report.
 * `label` - *String* - Used as a sheet (tab) label in Excel formatted reports.
 * `type` - *enum of TABLE, SUMMARY, PIVOT. Required* - Defines the type of view being defined.
 ** *TABLE* views are a simple listing of the records from the data source.
 ** *SUMMARY* views are essentially pre-computed Pivot Tables.
 That is to say, the aggregation done by a Pivot Table in a spreadsheet file is done by QQQ while generating the report.
 In this way, a non-spreadsheet report (e.g., PDF or CSV) can have summarized data, as though it were a Pivot Table in a live spreadsheet.
 ** *PIVOT* views produce actual Pivot Tables, and are only supported in Excel files _(and are not supported at the time of this writing)_.
 * `dataSourceName` - *String, Required* - Reference to a DataSource within the report, that is used to provide the rows for the view.
 * `varianceDataSourceName` - *String* - Optional reference to a second DataSource within the report, that is used in `*SUMMARY*` type views for computing variances.
 ** For example, given a Data Source with a filter that selects all sales records for a given year, a Variance Data Source may have a filter that selects the previous year, for doing comparissons.
 * `pivotFields` - *List of String, Conditional* - For *SUMMARY* or *PIVOT* type views, specify the field(s) used as pivot rows.
 ** For example, in a summary view of orders, you may "pivot" on the *customerId* field, to produce one row per-customer, with aggregate data for that customer.
 * `titleFormat` - *String* - Java Format String, used with `titleFields` (if given), to produce a title row, e.g., first row in the view (before any rows from the data source).
 * `titleFields` - *List of String, Conditional* - Used with `titleFormat`, to provide values for any format specifiers in the format string.
 Syntax to reference a field (e.g., from a report input field) is: `${input.NAME}`, where `NAME` is the `name` attribute of the inputField.
 ** Example of using `titleFormat` and `titleFields`:
 [source,java]
 ----
 // given these inputFields:
 new QFieldMetaData("startDate", QFieldType.DATE)
 new QFieldMetaData("endDate", QFieldType.DATE)
 // a view can have a title row like this:
 .withTitleFormat("Weekly Sales Report - %s - %s")
 .withTitleFields(List.of("${input.startDate}", "${input.endDate}"))
 ----
 * `includeHeaderRow` - *boolean, default true* - Indication that first row of the view should be the column labels.
 ** If true, then header row is put in the view.
 ** If false, then no header row is put in the view.
 * `includeTotalRow` - *boolean, default false* - Indication that a totals row should be added to the view.
 All numeric columns are summed to produce values in the totals row.
 ** If true, then totals row is put in the view.
 ** If false, then no totals row is put in the view.
 * `includePivotSubTotals` - *boolean, default false* - For a *SUMMARY* or *PIVOT* type view, if there are more than 1 *pivotFields* being used, this field is an indication that each higher-level pivot should include sub-totals.
 ** #TODO - provide example#
 * `columns` - *List of QReportField, required* - Definition of the columns to appear in the view.  See section on QReportField for details.
 * `orderByFields` - *List of QFilterOrderBy, optional* - For a *SUMMARY* or *PIVOT* type view, how to sort the rows.
 * `recordTransformStep` - *QCodeReference, subclass of `AbstractTransformStep`* - Custom code reference that can be used to transform records after they are queried from the data source, and before they are placed into the view.
 Can be used to transform or customize values, or to look up additional values to add to the report.
 ** #TODO - provide example#
 * `viewCustomizer` - *QCodeReference, implementation of interface `Function<QReportView, QReportView>`* - Custom code reference that can be used to customize the report view, at runtime.
 Can be used, for example, to dynamically define the report's *columns*.
 ** #TODO - provide example#
 ===== QReportField
 Report Fields define the fields (AKA columns) of data that appear in a report view.
 These fields can either be direct references to fields from the report's data sources, or values computed using formula defined in the QReportField.
 *QReportField Properties:*
 * `name` - *String, required* - Unique identifier for the field within its ReportView.
 In general, will be a reference to a field from the ReportView's DataSource *unless a *formula* is given (for *SUMMARY* type views), the field is marked as *isVirtual*, or the field is marked as *showPossibleValueLabel*).
 * `label` - *String* - Optional text label to identify the field, for example, in a header row.
 If not given, may be derived from field, where possible.
 * `type` - *QFieldType*
 * `formula` - *String, conditional* - Required for *SUMMARY* type views.
 Defines the formula to be used for computing the value in this field.
 ** For example:
 [source,java]
 ----
 .withName("reportEndDate").withFormula("${input.endDate}")
 .withName("count").withFormula("${pivot.count.id}")
 .withName("percentOfTotal").withFormula("=DIVIDE(${pivot.count.id},${total.count.id})")
 .withName("sumCost").withFormula("${pivot.sum.cost}")
 .withName("sumCharge").withFormula("${pivot.sum.charge}")
 .withName("profit").withFormula("=MINUS(${pivot.sum.charge},${pivot.sum.cost})")
 .withName("totalCost").withFormula("=DIVIDE_SCALE(${pivot.sum.cost},${pivot.count.id},2)")
 .withName("revenuePer").withFormula("=DIVIDE_SCALE(${pivot.sum.charge},${pivot.count.id},2)")
 .withName("marginPer").withFormula("=MINUS(DIVIDE_SCALE(${pivot.sum.charge},${pivot.count.id},2),DIVIDE_SCALE(${pivot.sum.cost},${pivot.count.id},2))")
 .withName("thisWeekMargin").withFormula("=SCALE(DIVIDE(${thisRow.profit},${pivot.sum.charge}),2)")
 .withName("previousWeekProfit").withFormula("=MINUS(${variancePivot.sum.charge},${variancePivot.sum.cost})")
 .withName("previousWeekMargin").withFormula("=SCALE(DIVIDE(${thisRow.previousWeekProfit},${variancePivot.sum.charge}),2)")
 .withName("marginThisVsPrevious").withFormula("=SCALE(MINUS(${thisRow.margin},${thisRow.marginPrevious}),3)")
 .withName("exception").withFormula("""
   =IF(LT(${thisRow.margin},0),Negative Margin,IF(LT(${thisRow.marginThisVsPrevious},0),Margin Decreased,""))""")
 ----
 * `displayFormat` *String*
 * `isVirtual` *Boolean, default false* - (needs reviewed - may only be required for report views using a data source with a *staticDataSupplier*)
 * `showPossibleValueLabel` *Boolean, default false* - To show a translated value for a Possible Value field (e.g., a name or other value meaningful to a user, instead of a foreign key).
 * `sourceFieldName` *String* - Used for the scenario where a possibleValue field is included in a report both as the foreign key (raw, id value), and the translated "label" value.
 In that case, the field marked with *showPossibleValueLabel* = true should be given a different name, and should use *sourceFieldName* to indicate the field that has the id value.
 ** For example:
 [source,java]
 ----
 // this field would have the "raw" warehouseId values
 // e.g., integers - foreign keys to a warehouse table.  Generally useful for machines to know.
 new QReportField("warehouseId")
   .withLabel("Warehouse Id"),
 // this field would have the translated values from the warehouse PossibleValueSource
 // for example, maybe the name field from the warehouse table.  A string, useful for humans to read.
 new QReportField("warehouseName")
   .withSourceFieldName("warehouseId")
   .withShowPossibleValueLabel(true)
   .withLabel("Warehouse Name"),
 ----
--- a/docs/metaData/Tables.adoc
+++ b/docs/metaData/Tables.adoc
@ -0,0 +1,49 @@
 == QQQ Tables
 include::../variables.adoc[]
 The core type of object in a QQQ Instance is the Table.
 In the most common use-case, a QQQ Table may be the in-app representation of a Database table.
 That is, it is a collection of records (or rows) of data, each of which has a set of fields (or columns).
 QQQ also allows other types of data sources ({link-backends}) to be used as tables, such as File systems, API's, Java enums or objects, etc.
 All of these backend types present the same interfaces (both user-interfaces, and application programming interfaces), regardless of their backend type.
 === QTableMetaData
 Tables are defined in a QQQ Instance in a `*QTableMetaData*` object.
 All tables must reference a {link-backend}, a list of fields that define the shape of records in the table, and additional data to describe how to work with the table within its backend.
 *QTableMetaData Properties:*
 * `name` - *String, Required* - Unique name for the table within the QQQ Instance.
 * `label` - *String* - User-facing label for the table, presented in User Interfaces.
 Inferred from `name` if not set.
 * `backendName` - *String, Required* - Name of a {link-backend} in which this table's data is managed.
 * `fields` - *Map of String → {link-field}, Required* - The columns of data that make up all records in this table.
 * `primaryKeyField` - *String, Conditional* - Name of a {link-field} that serves as the primary key (e.g., unique identifier) for records in this table.
 * `uniqueKeys` - *List of UniqueKey* - Definition of additional unique constraints (from an RDBMS point of view) from the table.
 e.g., sets of columns which must have unique values for each record in the table.
 * `backendDetails` - *QTableBackendDetails or subclass* - Additional data to configure the table within its {link-backend}.
 * `automationDetails` - *QTableAutomationDetails* - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.
 * `customizers` - *Map of String → QCodeReference* - References to custom code that are injected into standard table actions, that allow applications to customize certain parts of how the table works.
 * `parentAppName` - *String* - Name of a {link-app} that this table exists within.
 * `icon` - *QIcon* - Icon associated with this table in certain user interfaces.
 * `recordLabelFormat` - *String* - Java Format String, used with `recordLabelFields` to produce a label shown for records from the table.
 * `recordLabelFields` - *List of String, Conditional* - Used with `recordLabelFormat` to provide values for any format specifiers in the format string.
 These strings must be field names within the table.
 ** Example of using `recordLabelFormat` and `recordLabelFields`:
 [source,java]
 ----
 // given these fields in the table:
 new QFieldMetaData("name", QFieldType.STRING)
 new QFieldMetaData("birthDate", QFieldType.DATE)
 // We can produce a record label such as "Darin Kelkhoff (1980-05-31)" via:
 .withRecordLabelFormat("%s (%s)")
 .withRecordLabelFields(List.of("name", "birthDate"))
 ----
 * `sections` - *List of QFieldSection* - Mechanism to organize fields within user interfaces, into logical sections.
 If any sections are present in the table meta data, then all fields in the table must be listed in exactly 1 section.
 If no sections are defined, then instance enrichment will define default sections.
 * `associatedScripts` - *List of AssociatedScript* - Definition of user-defined scripts that can be associated with records within the table.
 * `enabledCapabilities` and `disabledCapabilities` - *Set of Capability enum values* - Overrides from the backend level, for capabilities that this table does or does not possess.
--- a/docs/metaData/Tables.html
+++ b/docs/metaData/Tables.html
@ -0,0 +1,553 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 2.0.18">
 <title>QQQ Tables</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
 <style>
 /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
 /* Uncomment the following line when using as a custom stylesheet */
 /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
 html{font-family:sans-serif;-webkit-text-size-adjust:100%}
 a{background:none}
 a:focus{outline:thin dotted}
 a:active,a:hover{outline:0}
 h1{font-size:2em;margin:.67em 0}
 b,strong{font-weight:bold}
 abbr{font-size:.9em}
 abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
 dfn{font-style:italic}
 hr{height:0}
 mark{background:#ff0;color:#000}
 code,kbd,pre,samp{font-family:monospace;font-size:1em}
 pre{white-space:pre-wrap}
 q{quotes:"\201C" "\201D" "\2018" "\2019"}
 small{font-size:80%}
 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
 sup{top:-.5em}
 sub{bottom:-.25em}
 img{border:0}
 svg:not(:root){overflow:hidden}
 figure{margin:0}
 audio,video{display:inline-block}
 audio:not([controls]){display:none;height:0}
 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
 legend{border:0;padding:0}
 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
 button,input{line-height:normal}
 button,select{text-transform:none}
 button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
 button[disabled],html input[disabled]{cursor:default}
 input[type=checkbox],input[type=radio]{padding:0}
 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
 textarea{overflow:auto;vertical-align:top}
 table{border-collapse:collapse;border-spacing:0}
 *,::before,::after{box-sizing:border-box}
 html,body{font-size:100%}
 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
 a:hover{cursor:pointer}
 img,object,embed{max-width:100%;height:auto}
 object,embed{height:100%}
 img{-ms-interpolation-mode:bicubic}
 .left{float:left!important}
 .right{float:right!important}
 .text-left{text-align:left!important}
 .text-right{text-align:right!important}
 .text-center{text-align:center!important}
 .text-justify{text-align:justify!important}
 .hide{display:none}
 img,object,svg{display:inline-block;vertical-align:middle}
 textarea{height:auto;min-height:50px}
 select{width:100%}
 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
 a{color:#2156a5;text-decoration:underline;line-height:inherit}
 a:hover,a:focus{color:#1d4b8f}
 a img{border:0}
 p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
 p aside{font-size:.875em;line-height:1.35;font-style:italic}
 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
 h1{font-size:2.125em}
 h2{font-size:1.6875em}
 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
 h4,h5{font-size:1.125em}
 h6{font-size:1em}
 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
 em,i{font-style:italic;line-height:inherit}
 strong,b{font-weight:bold;line-height:inherit}
 small{font-size:60%;line-height:inherit}
 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
 ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
 ul,ol{margin-left:1.5em}
 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
 ul.circle{list-style-type:circle}
 ul.disc{list-style-type:disc}
 ul.square{list-style-type:square}
 ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
 dl dt{margin-bottom:.3125em;font-weight:bold}
 dl dd{margin-bottom:1.25em}
 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
 h1{font-size:2.75em}
 h2{font-size:2.3125em}
 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 h4{font-size:1.4375em}}
 table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
 table thead,table tfoot{background:#f7f8f7}
 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 table tr.even,table tr.alt{background:#f8f8f7}
 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 .center{margin-left:auto;margin-right:auto}
 .stretch{width:100%}
 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 .clearfix::after,.float-group::after{clear:both}
 :not(pre).nobreak{word-wrap:normal}
 :not(pre).nowrap{white-space:nowrap}
 :not(pre).pre-wrap{white-space:pre-wrap}
 :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
 pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
 pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
 pre>code{display:block}
 pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 em em{font-style:normal}
 strong strong{font-weight:400}
 .keyseq{color:rgba(51,51,51,.8)}
 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 .keyseq kbd:first-child{margin-left:0}
 .keyseq kbd:last-child{margin-right:0}
 .menuseq,.menuref{color:#000}
 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 .menuseq{word-spacing:-.02em}
 .menuseq b.caret{font-size:1.25em;line-height:.8}
 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 b.button::before{content:"[";padding:0 3px 0 2px}
 b.button::after{content:"]";padding:0 2px 0 3px}
 p a>code:hover{color:rgba(0,0,0,.9)}
 #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 #content{margin-top:1.25em}
 #content::before{content:none}
 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
 #header .details span:first-child{margin-left:-.125em}
 #header .details span.email a{color:rgba(0,0,0,.85)}
 #header .details br{display:none}
 #header .details br+span::before{content:"\00a0\2013\00a0"}
 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 #header #revnumber{text-transform:capitalize}
 #header #revnumber::after{content:"\00a0"}
 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 #toc>ul{margin-left:.125em}
 #toc ul.sectlevel0>li>a{font-style:italic}
 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 #toc li{line-height:1.3334;margin-top:.3334em}
 #toc a{text-decoration:none}
 #toc a:active{text-decoration:underline}
 #toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
 body.toc2{padding-left:15em;padding-right:0}
 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 body.toc2.toc-right{padding-left:0;padding-right:15em}
 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 #toc.toc2{width:20em}
 #toc.toc2 #toctitle{font-size:1.375em}
 #toc.toc2>ul{font-size:.95em}
 #toc.toc2 ul ul{padding-left:1.25em}
 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
 #content #toc>:first-child{margin-top:0}
 #content #toc>:last-child{margin-bottom:0}
 #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
 #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
 #content{margin-bottom:.625em}
 .sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
 .sect1{padding-bottom:1.25em}}
 .sect1:last-child{padding-bottom:0}
 .sect1+.sect1{border-top:1px solid #e7e7e9}
 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 details{margin-left:1.25rem}
 details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
 details>summary::-webkit-details-marker{display:none}
 details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
 details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
 details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 .admonitionblock>table td.icon{text-align:center;width:80px}
 .admonitionblock>table td.icon img{max-width:none}
 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
 .exampleblock>.content>:first-child{margin-top:0}
 .exampleblock>.content>:last-child{margin-bottom:0}
 .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
 .sidebarblock>:first-child{margin-top:0}
 .sidebarblock>:last-child{margin-bottom:0}
 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
 .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
 .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
 .listingblock>.content{position:relative}
 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
 .listingblock:hover code[data-lang]::before{display:block}
 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 .listingblock pre.highlightjs{padding:0}
 .listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
 .listingblock pre.prettyprint{border-width:0}
 .prettyprint{background:#f7f7f8}
 pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
 pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
 pre.prettyprint li code[data-lang]::before{opacity:1}
 pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
 table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
 table.linenotable td.code{padding-left:.75em}
 table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
 pre.pygments span.linenos{display:inline-block;margin-right:.75em}
 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 .quoteblock blockquote{margin:0;padding:0;border:0}
 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 .verseblock{margin:0 1em 1.25em}
 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 .verseblock pre strong{font-weight:400}
 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
 p.tableblock:last-child{margin-bottom:0}
 td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
 td.tableblock>.content>:last-child{margin-bottom:-1.25em}
 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 table.grid-all>*>tr>*{border-width:1px}
 table.grid-cols>*>tr>*{border-width:0 1px}
 table.grid-rows>*>tr>*{border-width:1px 0}
 table.frame-all{border-width:1px}
 table.frame-ends{border-width:1px 0}
 table.frame-sides{border-width:0 1px}
 table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
 table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
 table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
 table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
 table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
 th.halign-left,td.halign-left{text-align:left}
 th.halign-right,td.halign-right{text-align:right}
 th.halign-center,td.halign-center{text-align:center}
 th.valign-top,td.valign-top{vertical-align:top}
 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 th.valign-middle,td.valign-middle{vertical-align:middle}
 table thead th,table tfoot th{font-weight:bold}
 tbody tr th{background:#f7f8f7}
 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 p.tableblock>code:only-child{background:none;padding:0}
 p.tableblock{font-size:1em}
 ol{margin-left:1.75em}
 ul li ol{margin-left:1.5em}
 dl dd{margin-left:1.125em}
 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 ul.unstyled,ol.unstyled{margin-left:0}
 li>p:empty:only-child::before{content:"";display:inline-block}
 ul.checklist>li>p:first-child{margin-left:-1em}
 ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
 ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 ul.inline>li{margin-left:1.25em}
 .unstyled dl dt{font-weight:400;font-style:normal}
 ol.arabic{list-style-type:decimal}
 ol.decimal{list-style-type:decimal-leading-zero}
 ol.loweralpha{list-style-type:lower-alpha}
 ol.upperalpha{list-style-type:upper-alpha}
 ol.lowerroman{list-style-type:lower-roman}
 ol.upperroman{list-style-type:upper-roman}
 ol.lowergreek{list-style-type:lower-greek}
 .hdlist>table,.colist>table{border:0;background:none}
 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 td.hdlist2{word-wrap:anywhere}
 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 .colist td:not([class]):first-child img{max-width:none}
 .colist td:not([class]):last-child{padding:.25em 0}
 .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
 .imageblock.left{margin:.25em .625em 1.25em 0}
 .imageblock.right{margin:.25em 0 1.25em .625em}
 .imageblock>.title{margin-bottom:0}
 .imageblock.thumb,.imageblock.th{border-width:6px}
 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 .image.left{margin-right:.625em}
 .image.right{margin-left:.625em}
 a.image{text-decoration:none;display:inline-block}
 a.image object{pointer-events:none}
 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 sup.footnote a,sup.footnoteref a{text-decoration:none}
 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 #footnotes .footnote:last-of-type{margin-bottom:0}
 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 div.unbreakable{page-break-inside:avoid}
 .big{font-size:larger}
 .small{font-size:smaller}
 .underline{text-decoration:underline}
 .overline{text-decoration:overline}
 .line-through{text-decoration:line-through}
 .aqua{color:#00bfbf}
 .aqua-background{background:#00fafa}
 .black{color:#000}
 .black-background{background:#000}
 .blue{color:#0000bf}
 .blue-background{background:#0000fa}
 .fuchsia{color:#bf00bf}
 .fuchsia-background{background:#fa00fa}
 .gray{color:#606060}
 .gray-background{background:#7d7d7d}
 .green{color:#006000}
 .green-background{background:#007d00}
 .lime{color:#00bf00}
 .lime-background{background:#00fa00}
 .maroon{color:#600000}
 .maroon-background{background:#7d0000}
 .navy{color:#000060}
 .navy-background{background:#00007d}
 .olive{color:#606000}
 .olive-background{background:#7d7d00}
 .purple{color:#600060}
 .purple-background{background:#7d007d}
 .red{color:#bf0000}
 .red-background{background:#fa0000}
 .silver{color:#909090}
 .silver-background{background:#bcbcbc}
 .teal{color:#006060}
 .teal-background{background:#007d7d}
 .white{color:#bfbfbf}
 .white-background{background:#fafafa}
 .yellow{color:#bfbf00}
 .yellow-background{background:#fafa00}
 span.icon>.fa{cursor:default}
 a span.icon>.fa{cursor:inherit}
 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 .conum[data-value] *{color:#fff!important}
 .conum[data-value]+b{display:none}
 .conum[data-value]::after{content:attr(data-value)}
 pre .conum[data-value]{position:relative;top:-.125em}
 b.conum *{color:inherit!important}
 .conum:not([data-value]):empty{display:none}
 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem}
 p{margin-bottom:1.25rem}
 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 .print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
 html{font-size:80%}
 a{color:inherit!important;text-decoration:underline!important}
 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 abbr[title]{border-bottom:1px dotted}
 abbr[title]::after{content:" (" attr(title) ")"}
 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 thead{display:table-header-group}
 svg{max-width:100%}
 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 #header,#content,#footnotes,#footer{max-width:none}
 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 body.book #header{text-align:center}
 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 body.book #header .details{border:0!important;display:block;padding:0!important}
 body.book #header .details span:first-child{margin-left:0!important}
 body.book #header .details br{display:block}
 body.book #header .details br+span::before{content:none!important}
 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 .listingblock code[data-lang]::before{display:block}
 #footer{padding:0 .9375em}
 .hide-on-print{display:none!important}
 .print-only{display:block!important}
 .hide-for-print{display:none!important}
 .show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
 .sect1{padding:0!important}
 .sect1+.sect1{border:0}
 #footer{background:none}
 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 </style>
 </head>
 <body class="article">
 <div id="header">
 </div>
 <div id="content">
 <div class="sect1">
 <h2 id="_qqq_tables">QQQ Tables</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>The core type of object in a QQQ Instance is the Table.
 In the most common use-case, a QQQ Table may be the in-app representation of a Database table.
 That is, it is a collection of records (or rows) of data, each of which has a set of fields (or columns).</p>
 </div>
 <div class="paragraph">
 <p>QQQ also allows other types of data sources (<a href="Backends{relfilesuffix}">QQQ Backends</a>) to be used as tables, such as File systems, API&#8217;s, Java enums or objects, etc.
 All of these backend types present the same interfaces (both user-interfaces, and application programming interfaces), regardless of their backend type.</p>
 </div>
 <div class="sect2">
 <h3 id="_qtablemetadata">QTableMetaData</h3>
 <div class="paragraph">
 <p>Tables are defined in a QQQ Instance in a <code><strong>QTableMetaData</strong></code> object.
 All tables must reference a <a href="Backends{relfilesuffix}">QQQ Backend</a>, a list of fields that define the shape of records in the table, and additional data to describe how to work with the table within its backend.</p>
 </div>
 <div class="paragraph">
 <p><strong>QTableMetaData Properties:</strong></p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p><code>name</code> - <strong>String, Required</strong> - Unique name for the table within the QQQ Instance.</p>
 </li>
 <li>
 <p><code>label</code> - <strong>String</strong> - User-facing label for the table, presented in User Interfaces.
 Inferred from <code>name</code> if not set.</p>
 </li>
 <li>
 <p><code>backendName</code> - <strong>String, Required</strong> - Name of a <a href="Backends{relfilesuffix}">QQQ Backend</a> in which this table&#8217;s data is managed.</p>
 </li>
 <li>
 <p><code>fields</code> - <strong>Map of String → <a href="Fields{relfilesuffix}">QQQ Field</a>, Required</strong> - The columns of data that make up all records in this table.</p>
 </li>
 <li>
 <p><code>primaryKeyField</code> - <strong>String, Conditional</strong> - Name of a <a href="Fields{relfilesuffix}">QQQ Field</a> that serves as the primary key (e.g., unique identifier) for records in this table.</p>
 </li>
 <li>
 <p><code>uniqueKeys</code> - <strong>List of UniqueKey</strong> - Definition of additional unique constraints (from an RDBMS point of view) from the table.
 e.g., sets of columns which must have unique values for each record in the table.</p>
 </li>
 <li>
 <p><code>backendDetails</code> - <strong>QTableBackendDetails or subclass</strong> - Additional data to configure the table within its <a href="Backends{relfilesuffix}">QQQ Backend</a>.</p>
 </li>
 <li>
 <p><code>automationDetails</code> - <strong>QTableAutomationDetails</strong> - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.</p>
 </li>
 <li>
 <p><code>customizers</code> - <strong>Map of String → QCodeReference</strong> - References to custom code that are injected into standard table actions, that allow applications to customize certain parts of how the table works.</p>
 </li>
 <li>
 <p><code>parentAppName</code> - <strong>String</strong> - Name of a <a href="Apps{relfilesuffix}">QQQ App</a> that this table exists within.</p>
 </li>
 <li>
 <p><code>icon</code> - <strong>QIcon</strong> - Icon associated with this table in certain user interfaces.</p>
 </li>
 <li>
 <p><code>recordLabelFormat</code> - <strong>String</strong> - Java Format String, used with <code>recordLabelFields</code> to produce a label shown for records from the table.</p>
 </li>
 <li>
 <p><code>recordLabelFields</code> - <strong>List of String, Conditional</strong> - Used with <code>recordLabelFormat</code> to provide values for any format specifiers in the format string.
 These strings must be field names within the table.</p>
 <div class="ulist">
 <ul>
 <li>
 <p>Example of using <code>recordLabelFormat</code> and <code>recordLabelFields</code>:</p>
 </li>
 </ul>
 </div>
 </li>
 </ul>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="CodeRay highlight"><code data-lang="java"><span style="color:#777">// given these fields in the table:</span>
 <span style="color:#080;font-weight:bold">new</span> QFieldMetaData(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">name</span><span style="color:#710">&quot;</span></span>, QFieldType.STRING)
 <span style="color:#080;font-weight:bold">new</span> QFieldMetaData(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">birthDate</span><span style="color:#710">&quot;</span></span>, QFieldType.DATE)
 <span style="color:#777">// We can produce a record label such as &quot;Darin Kelkhoff (1980-05-31)&quot; via:</span>
 .withRecordLabelFormat(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">%s (%s)</span><span style="color:#710">&quot;</span></span>)
 .withRecordLabelFields(<span style="color:#0a8;font-weight:bold">List</span>.of(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">name</span><span style="color:#710">&quot;</span></span>, <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">birthDate</span><span style="color:#710">&quot;</span></span>))</code></pre>
 </div>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p><code>sections</code> - <strong>List of QFieldSection</strong> - Mechanism to organize fields within user interfaces, into logical sections.
 If any sections are present in the table meta data, then all fields in the table must be listed in exactly 1 section.
 If no sections are defined, then instance enrichment will define default sections.</p>
 </li>
 <li>
 <p><code>associatedScripts</code> - <strong>List of AssociatedScript</strong> - Definition of user-defined scripts that can be associated with records within the table.</p>
 </li>
 <li>
 <p><code>enabledCapabilities</code> and <code>disabledCapabilities</code> - <strong>Set of Capability enum values</strong> - Overrides from the backend level, for capabilities that this table does or does not possess.</p>
 </li>
 </ul>
 </div>
 </div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Last updated 2022-11-21 09:02:56 -0600
 </div>
 </div>
 </body>
 </html>
--- a/docs/variables.adoc
+++ b/docs/variables.adoc
@ -0,0 +1,13 @@
 ifdef::env-name[:relfilesuffix: .adoc]
 :link-backend: link:Backends{relfilesuffix}[QQQ Backend]
 :link-backends: link:Backends{relfilesuffix}[QQQ Backends]
 :link-table: link:Tables{relfilesuffix}[QQQ Table]
 :link-tables: link:Tables{relfilesuffix}[QQQ Tables]
 :link-join: link:Joins{relfilesuffix}[QQQ Join]
 :link-joins: link:Joins{relfilesuffix}[QQQ Joins]
 :link-field: link:Fields{relfilesuffix}[QQQ Field]
 :link-fields: link:Fields{relfilesuffix}[QQQ Fields]
 :link-process: link:Processes{relfilesuffix}[QQQ Process]
 :link-processes: link:Processes{relfilesuffix}[QQQ Processes]
 :link-app: link:Apps{relfilesuffix}[QQQ App]
 :link-apps: link:Apps{relfilesuffix}[QQQ Apps]