Skip to content

Listing Entitities

Standard User Story

As a user, I want to be able to list all entities of a particular type (e.g. Items, Orders, Cards, …) so that I easily find the information I am looking for and act on it.

References

Required Behaviors

General

  1. Navigate to the list of entities from a given context in the system. The
    context can be the top level navigation of the application (e.g. looking at the Items List) or it can be a local context that determines a subset of all possible instances of the entity to be displayed. E.g. A particular Order for the list of its lines, A State for Cards in the Order Queue, etc. The initial information presented to the user should follow a configuration set at the Tenant or User preferences.
  2. The list has a set of columns available to show to the user. Tenant or User preferences determine which columns are shown and in which order.

Filtering

  1. The list should allow filtering on a pre-defined subset of the columns available.
  2. A global filter will allow for text input to be matched by one of a pre-defined subset of columns.
  3. Column Filters will allow for filtering on the data type of the column for equality or regex match (Strings). Multiple column filters
    combine using AND logic.
  4. An Advanced Filter that allows:
    1. Conditions based on the data type of the column (e.g. Text, Numeric, Dates, …)
      1. Equality
      2. Gt, Ge, Lt, Le
      3. Ranges
      4. Case Insensitive Regex (Text)
    2. Composing Conditions using AND and OR Logic
  5. The final filter applied to the list is the AND of the global filter, column filters and advanced filter.
Column Filter Behavior
  • text filters match the regular expression ($i).*{{ input }}.* (case insensitive exact match of the input value anywhere in the field)
  • Numeric:
    • Equals with a precision of 1e-18
  • Boolean: Strict Equality
  • Dates: Equality within +/- 12 hours of the record date in the record TimeZone
  • Enumerations: Strict String Equality with the values handled by the back end (to be published for each enumeration type)
  • Other “string-like” types (e.g. URL’s, UUID’s, emails, phones, …) strict equality

Sorting

  1. The list should allow sorting on a pre-defined subset of the columns available.
  2. The User selects one column with sorting direction.
  3. Nice-to-have an advanced sort by multiple columns (with Sorting precedence).

Sorting should follow:

  • Lexicographic Order for all Text or String like properties
  • Numerical Order for any Numerical type
  • True before False for boolean properties
  • Epoch Order for Date Properties (Time ordering converted to UTC)
  • Nulls are ordered last

Pagination

The Front End will present the user with an “infinite scroll” experience, calling the back end to retrieve
additional data as needed by the scrolling motion.

Grouping

TBD

Selection and Actions

A Table may support actions that are applicable to:

  1. No Selection
  2. Single Entity/Row
  3. Multiple Entities/Rows, acting on them independently
  4. Multiple Entities/Rows, acting on them as a group

Interaction elements should show enabled or disabled states based on the selection status (e.g. A delete button should be disabled when no row is selected)

Tool tips on the action elements should:

  • Explain the action when enabled
  • Explain why the action is disabled when disabled

Actions may be accesible via different UI mechanisms, including but not limited to:

  1. In-Row Actions (buttons, drop-downs, , Right-Click Context Menus, etc.)
  2. Global Actions (buttons, drop-downs, menus, etc.)

In-Row actions should be restricted to actions applicable to the specific row.

Edit in Place

If Enabled, Cell in a row may be edited in place.

The Edit Interaction involves:

  1. The user signaling intent to edit the row by double-click on a cell of the row, or by explicit action (e.g. a button)
  2. The row becomes editable, the user can navigate the editable cells of the row via (Tab, Shift+Tab, Arrow Keys) to edit multiple cells in the row.
  3. The user can exit the edit mode by pressing escape (cancelling the changes) or by pressing enter (accepting the changes)
  4. Navigating away from the row while in edit mode will prompt the user to accept, cancel the changes or go back to the editing place if there are any changes made to the row.

Reference Edit-Through

For columns of type Lookup/Reference, the system should allow the user to punch-through the reference to either add a new referenced entity or edit an existing referenced entity in an overlay interaction, returnting to the lookup list after the referenced entity is created or updated.

Validation

When a row is being edited, the system should provide feedback to the user on the validity of the data being entered as soon as feasible. In particular, each editable column should validate

Configuration/Definition of a List Component

A List Component should support all the behaviors described above with no modifications to its code. To do so, it should be configured by providing information on the entities it manages, the columns to display, etc.

Entity Definition

The Entity Type that a List Component Manages is defined by:

  1. An Entity Name
  2. An Entity Short Name
  3. A Description
  4. A Rest Endpoint Route of the form https://<server>/<version>/<module>/<entity>
  5. A Schemas for:
    1. Entity Payload
    2. Entity Metadata
    3. Entity Input Payload
    4. Entity Input Metadata (if necessary)

The Rest Endpoint should support all the subroutes and operations of a Standards System Data Authority Endpoint and the Data Authority Module Designs, in particular the Query DSL that supports filtering, sorting and pagination.

Column Definitions

The configuration of a list includes:

  1. A list of the columns available for the entities it manages.
  2. An Ordered list of the columns to display in the component.

Each column is defined by:

  1. A Column Name, unique for the List
  2. A Column Display Name to be used in Column Selectors and Configuration Actions.
  3. A Column Header to be used to display the column in the list.
  4. A Column Description to be used in Tooltips and other help elements
  5. A Column Type out of the supported types
  6. Boolean indicators for:
    1. Filterable
    2. Sortable
    3. Editable
    4. Groupable
  7. Binding to a property of the entity payload described by a json path to it.
  8. If Filterable and/or Sortable, a binding to the filtering or sorting key in the API Endpoint (See Current Limitations of Data Authority Endpoints)
  9. A Boolean Expression that defines what values are valid for the column. A special case of validation is whether the cell is required or not.

In addition to the defined columns, the list will show columns for:

  1. Selection of the row. This will always be the first column of the table
  2. Actions available for the row. This column will have:
    1. Column Display Name: Row Actions
    2. Column Header: Actions
    3. Column Type: A Special Type showing the action Icons for Single Row Actions of the table
    4. It will not be Filterable, Sortable, Editable or Groupable
Supported Basic Column Types

Information to be displayed in a row-column cell is described by a Column Type.

Column Types are inspired by Coda’s supported Column Types:

A Column Type is defined by:

  1. A Type Name unique in the system and predefined by the system. (User Extensions to column types may be added in the future))
  2. A Type Description to be used in Tooltips and other help elements.
  3. A Data Type that it displays, which should be one of:
    1. Open Text: A text field that allows single line input of text without special formatting.
    2. Extended Text (Canvas): A text field that allows multi-line input of text, potentially including special formatting (TBD).
    3. Number: An open text that accepts numeric input only.
    4. Date: A column that accepts a date in the format given by the User Locale.
      1. It may require a Timezone to be specified.
    5. DateTime: A column that accepts a date, time and timezone in the format given by the User Locale.
    6. Time: A column that accepts a time in the format given by the User Locale.
      1. It may require or accept a Timezone to be specified.
    7. Boolean: A column that accepts a boolean value.
    8. Enum: A column that accepts a value from a short (less than ~10 elements) list of pre-defined values.
    9. Dynamic Enum: A column that accepts a value from a long (more than ~10 elements) list of pre-defined values.
    10. Lookup/Reference: A Column that accepts a value that represents a reference to another entity instance in the system.
    11. Money: A column that represents a monetary value in a currency supported by the system.
    12. Url/Link: A Column representing a URL that should be opened in a new browser tab, window, overlay or external application.
    13. Image: A Column representing an image either hosted in the system or in an external service through a URL.
    14. Attachment: A Column representing a opaque blob of data that is stored by the system or in an external service through a URL. The types of Attachments to be supported (i.e. with specialized handling other than downloading) is TBD.
    15. Email: An email address.
    16. Phone: A phone number.
  4. A Display widget to be used for the read-only presentation of the column value in the cell.
  5. An Edit widget to be used for the editable presentation of the column value in the cell.
  6. An Error Widget to be used for presentation of validation errors in the cell.
Advanced Column Types

The system will support additional Column Types as its functionality evolves. These Column types could be composite types that combine multiple basic column types into a group that is edited using a specialized editor and may have additional validation logic, and at the same time may add sortable and filterable properties to the table.

An initial list of candidate Advanced Column Types is:

  1. Quantity: A Column representing an amount of inventory of a particular item expressed as a number and a unit of measurement.
  2. Date Range: A Column representing a range of dates with start and end dates that are ordered in time and a timezone.
  3. Address: A Collection of values (Street, City, State, Country, Zip Code, etc.) that are edited together as a group and contribute filtering and sorting capabilities to the table.
  4. Physical Quantities: Columns representing Lengths, Weights, Volumes, Areas, etc with a numerical value and a well-known physical unit of measurement.
  5. GeoLocations: Longitude, Latitude and Elevation (Altitude) with numerical values and a well-known length units of measurement.

Action Definitions

A list of Actions that can be triggered on the table rows:

Each Action is defined by:

  1. An Action Name, unique for the List
  2. The Action Type, one of:
    1. No-Row: For Actions that do not refer to any row, or refer to all rows (including those not seen in the current page) (e.g. New Row)
    2. Single Row Action: For actions that act on a single row (e.g. View Details, Edit)
    3. Multi-Row Action: For actions that can act on a set of rows, taking each row individually (E.g. Delete)
    4. Row-Set Action: For actions that act on a set of rows as a whole (e.g. computing a total, creating a document like an Order, etc)
  3. An Action Display Name to be used in Menus and Configuration Options
  4. An Action Icon to be used in the Action column (for Single Row Actions) or in action bars (for No-Row, Multi-Row and Row-Set Actions)
  5. An Action Description to be used in Tooltips and other help elements
  6. For implementation purposes, an Action will bind a Typescript function handler to be called when the action is triggered that takes None, one or an array of row values as their parameters.

Current Limitations of Data Authority Endpoints

The current implementation of Data Authority Endpoints does not support the column headers or json path expressions directly to express conditions for Filtering or Sorting. Although this constraint will be removed in the future, for
now columns that support Filtering or Sorting must define a Filtering Key in addition to the json path expression to be used in the API Query DSL.

Copyright: © Arda Systems 2026, All rights reserved

Comments