Skip to contents

Core concepts

The framework is based on two main concepts – data model and items.

Data Model

The data model contains the specifications of the Items to manage.

For each attribute of the item, the data model carries information like its name and type, but also a method to determine its default value as well as logical values to indicate if it should be skipped in forms, displayed in the table view or used to sort the data.

Supported types are numeric, integer, logical, character, Date and POSIXct.

Note: class POSIXlt is not supported as it stores datetime values into a list
POSIXct should be used to store datetime attributes.

Structure

Data models have the following structure:

  • Name – the name of the attribute

  • Type – the type of the attribute

  • Default value – a default value for the attribute (optional)

  • Default function – a function name (optional, without ())

  • Default arg – a list of arguments to pass to the default function (optional)

  • Display – whether or not the attribute should be displayed in the item table

  • Skip – whether or not the attribute should be skipped in the item form

  • Sort rank – a number to indicate that the attribute is used to sort the data

  • Sort desc – a logical if the attribute should be used in descending order

Mandatory attribute

Data models have a mandatory id attribute.
This id is the primary key of the item table, here to ensure the uniqueness of the items.

By default, the attribute gets a value that is generated by the ktools::getTimestamp() function.
You can pass another function as long as it generates unique ids (otherwise item creation will fail).

Defaults

In many cases, an item may have attributes that do not require an input from the user:

  • to generate a primary key

  • to set a default state or date

  • because the attribute is internal / hidden

Two mechanisms are available to tune the default behavior:

  • default value – a value that fits with the attribute type

  • default function – a function to generate the default value (optional arguments can be passed to the function)

Those defaults will be used to initialize the item input form and set the attribute value in case the user lets the input empty or if the attribute is skipped.

Important

Whenever an item is created or updated, the input values from the item form will be coerced to the type defined in the data model.

Make sure the default can be converted to the expected type or an error will be generated.

Integrity

When the module server is launched, it will perform an integrity check to ensure that the items and the data model are synchronized.

If not, the data model will be updated to match with any missing attribute for example (it is used during the import process to extract the data model from the loaded data).

Items

An item is defined as – something that is part of a list or group of things.

That is basically the purpose of the package / framework. An item is by definition anything that belongs to a group of things defined by their data model. This means all the item related functions inside this package dynamically work on the items in the context of their data model.

As an example, the item_form() function dynamically generates an input form based on the attribute list contained in the data model (the type of input, the default value of the input or if no input should be created for the attribute).

Items are stored (as a data.frame) in a reactive object that fits with the data model rules.
This means any authoring operation on the items should be performed within the module server.

When the module server is started, items will be checked to make sure attribute types fit with the data model.