Open Dig Reports

Appearance

The Groups ​

The Trio system utilizes a number of group types according to the group's required/optional, singular/multiple definitions and other limitations. These are the supported group types:

The Lookup Value (LV) Group Type ​

This group type store the group's options in a related "lookup" table. Below is an example of the definition of a a group instance from the back end of the Jezreel Expedition website:

php
class StoneGroups
{
    public static function getGroups(): array
    {
        return [
                //...
                'Primary Classification' => [
                'code' => 'LV',
                'field_name' => 'primary_classification_id',
                'lookup_table_name' => 'stone_primary_classifications',
                'lookup_text_field' => 'name',
                'lookup_order_by_field' => 'id',
                'useInTagger' => true,
                'showAsTag' => true,
                'dependency' => ['Scope:Artifact'],
            ],
        ]
    }
    //...
}

This group type is used when a required/single selection is called for. By convention, the first two values in all lookup tables in this group are (1) Unassigned and (2) Unknown.

Enum Fields (EM) Group Type ​

Much like the LV group type, the Enum group type permits only a required/single selection. This group type utilizes MySql's Enum column type which restricts possible values at the DB level.

Specific List of strings (SV) Group Type ​

Much like the EM and LV group types, the SV group type permits only a required/single selection. The list of allowed values is supplied in the group's definition:

php
      'Registration Scope' => [
        'code' => 'SV',
        'option_labels'  => ['Basket', 'Artifact'],
        'useInTagger' => false,
        'showAsTag' => true,
        'dependency' => [],
      ],

Module Tag (TM) Group Type ​

Instances of this group store their options in the external [module]_tags and [module]_groups tables (see ERD).

php
class CeramicGroups
{
    public static function getGroups(): array
    {
        return [
        // ...
             'Ware Color' => [
                'code' => 'TM',
                'multiple' => true,
                'dependency' => [['Registration Scope:Artifact']],
            ],
      ];
    }
}

As these groups mainly represent optional properties, they are commonly dependent upon other options. The 'multiple' configuration value controls whether multiple selections are allowed.

Global Tag (TG) Group Type ​

Similar to the Module Tag group type, this group type is used when some optional proerties are common to multiple modules. The tables used to define and use them are:

  • tags
  • tag_groups
  • taggable (polymorphic pivot)

This group type allows for the attachment of a numerical value to an optional property. It is mainly used to represent optional measurements (e.g., bone measurements dependent on bone type). The implementation of this group type is similar to that of the Module Tag group type with an additional value column in the pivot table (see ERD). All numbers are stored as integers with a "shift" property to denote the number's precision.

Categorized Groups (CG) Group Type ​

This group type is used to design bespoke, closed-ended lists of properties derived from the record's field values. For example, we can define a “Phase” group with the 'New Dig' and 'Old Dig' options dependent on the 'Season' property. This group type contains pairs of "categorizer functions" that define this logic for the back and frontends:

php
// Back end (filtering)
class StoneReadDetails implements ReadDetailsInterface
{
    private static Builder $builder;

    public static function applyCategorizedFilters(Builder $builder, array $groups): Builder
    {
        self::$builder = $builder;

        foreach ($groups as $key => $group) {
            switch ($group['group_name']) {
                case 'Registration Scope':
                    static::filterScope($group['selected']);
                    break;

                default:
                    // Do nothing
            }
        }
        return self::$builder;
    }

    private static function filterScope(array $vals)
    {
        if (count($vals) !== 1) {
            return;
        }

        static::$builder->Where(function ($query) use ($vals) {
            switch ($vals[0]['name']) {
                case 'Basket':
                    $query->where('artifact_no', 0);
                    return;

                case 'Artifact':
                    $query->Where('artifact_no', '!=', 0);
                    return;

                default:
                    return;
            }
        });
    }
}
ts
// Front end
export const StoneConfigs: TModuleConfigs = {
  nameRegExp:
    /^1(?<season>[2-8])\/(?<area>[K-S])\/(?<locus_no>\d{1,3}).(?<code>[A-Z]{2}).(?<basket_no>\d{1,2}).(?<artifact_no>\d{1,2})$/,

  //...
  categorizerFuncs: (fields?: TFields) => {
    const d = fields as TFields<"Stone">;
    return {
      "Registration Scope": d.artifact_no === 0,
    };
  },
};

Group types used only as filters:

Field Search (FS) Group Type ​

These groups perform simple textual search on a specific field. Only OR operations between the different values are currently supported.

Order By (OB) Group Type ​

As the name suggests, these groups are used to order by specific columns or, in the case of "composite" fields, by a substring of the field.

Media (MD) Group Type ​

Filter by the existence of a related media type. Options correspond to the distinct values in the application-wide media.collection_name column.

The implementation of the different filters can be found here.

TIP

Choosing group types should be done cautiously and with user input. Any Open Dig Reports website can be used as an example.