qqq/docs/metaData/Fields.adoc

[#Fields]
== 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`.  Needs to be used with a `FieldBehavior` of type `ValueTooLongBehavior`.

==== Field Behaviors
Additional behaviors can be attached to fields through the use of the `behaviors` attribute,
which is a `Set` of 0 or more instances of implementations of the `FieldBehavior` interface.
Note that in some cases, these instances may be `enum` constants,
but other times may be regular Objects.

QQQ provides a set of common field behaviors.
Applications can also define their own field behaviors by implementing the `FieldBehavior` interface,
and attaching instances of their custom behavior classes to fields.

===== ValueTooLongBehavior
Used on String fields.  Requires the field to have a `maxLength` set.
Depending on the chosen instance of this enum, before a record is Inserted or Updated,
if the value in the field is longer than the `maxLength`, then one of the following actions can occur:

* `TRUNCATE` - The value will be simply truncated to the `maxLength`.
* `TRUNCATE_ELLIPSIS` - The value will be truncated to 3 characters less than the `maxLength`, and three periods (an ellipsis) will be placed at the end.
* `ERROR` - An error will be reported, and the record will not be inserted or updated.
* `PASS_THROUGH` - Nothing will happen.  This is the same as not having a `ValueTooLongBehavior` on the field.

[source,java]
.Examples of using ValueTooLongBehavior
----
   new QFieldMetaData("sku", QFieldType.STRING)
      .withMaxLength(40),
      .withBehavior(ValueTooLongBehavior.ERROR),

   new QFieldMetaData("reason", QFieldType.STRING)
      .withMaxLength(250),
      .withBehavior(ValueTooLongBehavior.TRUNCATE_ELLIPSIS),

----

===== ValueRangeBehavior
Used on Numeric fields.  Specifies min and/or max allowed values for the field.
For each of min and max, the following attributes can be set:

* `minValue` / `maxValue` - the number that is the limit.
* `minAllowEqualTo` / `maxAllowEqualTo` - boolean (default true).  Controls if < (>) or ≤ (≥).
* `minBehavior` / `maxBehavior` - enum of `ERROR` (default) or `CLIP`.
** If `ERROR`, then a value not within the range causes an error, and the value does not get stored.
** else if `CLIP`, then a value not within the range gets "clipped" to either be the min/max (if allowEqualTo),
or to the min/max plus/minus the clipAmount
* `minClipAmount` / `maxClipAmount` - Default 1.  Used when behavior is `CLIP` (only applies when
not allowEqualTo).

[source,java]
.Examples of using ValueRangeBehavior
----
    new QFieldMetaData("noOfShoes", QFieldType.INTEGER)
      .withBehavior(new ValueRangeBehavior().withMinValue(0));

    new QFieldMetaData("price", QFieldType.BIG_DECIMAL)
      .withBehavior(new ValueRangeBehavior()
         // set the min value to be >= 0, and an error if an input is < 0.
         .withMinValue(BigDecimal.ZERO)
         .withMinAllowEqualTo(true)
         .withMinBehavior(ERROR)
         // set the max value to be < 100 - but effectively, clip larger values to 99.99
         // here we use the .withMax() method that takes 4 params vs. calling 4 .withMax*() methods.
         .withMax(new BigDecimal("100.00"), false, CLIP, new BigDecimal("0.01"))
    );
----

===== DynamicDefaultValueBehavior
Used to set a dynamic default value to a field when it is being inserted or updated.
For example, instead of having a hard-coded `defaultValue` specified in the field meta-data,
and instead of having to add, for example, a pre-insert custom action.

* `CREATE_DATE` - On inserts, sets the field's value to the current time.
* `MODIFY_DATE` - On inserts and updates, sets the field's value to the current time.
* `USER_ID` - On inserts and updates, sets the field's value to the current user's id (but only if the value is currently null).

_Note that the `QInstanceEnricher` will, by default, add the `CREATE_DATE` and `MODIFY_DATE` `DynamicDefaultValueBehavior`
options to any fields named `"createDate"` or `"modifyDate"`.
This behavior can be disabled by setting the `configAddDynamicDefaultValuesToFieldsNamedCreateDateAndModifyDate` property
on the `QInstanceEnricher` instance used by the application to `false`._

[source,java]
.Examples of using DynamicDefaultValueBehavior
----
   new QFieldMetaData("createDate", QFieldType.DATE_TIME)
      .withBehavior(DynamicDefaultValueBehavior.CREATE_DATE),

   new QFieldMetaData("modifyDate", QFieldType.DATE_TIME)
      .withBehavior(DynamicDefaultValueBehavior.MODIFY_DATE),

   new QFieldMetaData("createdByUserId", QFieldType.STRING)
      .withBehavior(DynamicDefaultValueBehavior.USER_ID),
----

===== DateTimeDisplayValueBehavior
By default, in QQQ, fields of type `DATE_TIME` are stored in UTC,
and their values in a QRecord is a java `Instant` instance, which is always UTC.
However, frontends will prefer to display date-time values in the user's local Time Zone whenever possible.

Using `DateTimeDisplayValueBehavior` allows a `DATE_TIME` field to be displayed in a different Time Zone.
An example use-case for this would be displaying airplane flight times,
where you would want a flight from California to New York to display Pacific Time for its departure time,
and Eastern Time for its arrival.

An instance of `DateTimeDisplayValueBehavior` can be configured to either use a hard-coded time `ZoneId`
(for example, to always show users UTC, or a business's home-office time zone).
Or, it can be set up to get the time zone to use from another field in the table.

[source,java]
.Examples of using DateTimeDisplayValueBehavior
----
new QTableMetaData().withName("flights").withFields(List.of(
   ...
   new QFieldMetaData("departureTimeZoneId", QFieldType.STRING),
   new QFieldMetaData("arrivaTimeZoneId", QFieldType.STRING),

   new QFieldMetaData("departureTime", QFieldType.DATE_TIME)
      .withBehavior(new DateTimeDisplayValueBehavior()
         .withZoneIdFromFieldName("departureTimeZoneId")),

   new QFieldMetaData("arrivalTime", QFieldType.DATE_TIME)
      .withBehavior(new DateTimeDisplayValueBehavior()
         .withZoneIdFromFieldName("arrivalTimeZoneId"))

   new QFieldMetaData("ticketSaleStartDateTime", QFieldType.DATE_TIME)
      .withBehavior(new DateTimeDisplayValueBehavior()
         .withDefaultZoneId("UTC"))
----

===== CaseChangeBehavior
A field can be made to always go through a toUpperCase or toLowerCase transformation, both before it is stored in a backend,
and after it is read from a backend, by adding a CaseChangeBehavior to it:

[source,java]
.Examples of using CaseChangeBehavior
----
new QTableMetaData().withName("item").withFields(List.of(

   new QFieldMetaData("sku", QFieldType.STRING)
      .withBehavior(CaseChangeBehavior.TO_UPPER_CASE)),

   new QFieldMetaData("username", QFieldType.STRING)
      .withBehavior(CaseChangeBehavior.TO_LOWER_CASE)),
----