Screen components
Screen components are the building blocks used in certain screen view templates — primarily in Workflow views and Notification views with buttons. They define the individual elements that appear on the screen and how users can interact with them.
Currently, MAI supports the following screen components:
Screen components have a well-defined structure that ensures consistency across templates, yet they offer customization options that allow the integrator to tailor content and behavior—making the overall template more effective in delivering the necessary information and collecting necessary input by enabling a more interactive approach.
Text Field
The Text Field is a versatile screen component used to display textual information or accept user input. It consists of two main parts:
Header – A fixed text label that describes the purpose or category of the field.
Content – An auto-scalable text area that shows the main content of the field. It can be modified using an assigned input method.
Key Features:
Visual appearance – The style is controlled by the state of the Text Field.
Customization – Integrators can tailor the text content and state to fit workflow requirements, enabling clear and interactive data presentation.
Interaction – Interaction depends on the assigned input method.
Placement – Text Fields appear within screen views, mainly in Workflow templates. Their position is defined by the selected template.
Code (SDK)
//...
fun createSampleTextField(): PgScreenComponent.TextField {
val inputMethodSample = createSampleInputMethod(NUMWHEEL_SAMPLE)
val textFieldStateSample = createTextFieldStateSample(TEXTFIELD_FOCUSED_SAMPLE)
return PgScreenComponent.TextField(
referenceId = "textFieldWithInputRefId",
headerText = "Shelf number:",
contentText = "Enter quantity",
state = textFieldStateSample,
inputMethod = inputMethodSample
)
}
//...State
Text Fields can be styled using predefined visual states that help communicate the current status of the field to the worker. States apply a small icon in front of the header to draw attention or provide feedback, making them especially useful for guiding the worker's focus or indicating validation results within a workflow.
Each state can optionally be highlighted, which makes the styling more prominent, by filling the background with color.
Available states:
No State (default) – Neutral appearance with no background, border, or icon.
Focused – Indicates the next step in the workflow with a blue play icon. When marked as highlighted, the background becomes blue.
Success – Shows a green checkmark icon to signal that the step was completed successfully. When marked as highlighted, the background becomes green.
Error – Displays a red cross icon to indicate that the step finished with an error. When marked as highlighted, the background becomes red.
Warning – Uses a yellow exclamation mark icon to indicate a step has completed with warnings. When marked as highlighted, the background becomes yellow.
Code (SDK)
//...
fun createTextFieldStateSample(sampleType: Int) =
when(sampleType) {
NO_STATE_SAMPLE ->
PgScreenComponent.TextField.State.NoState
FOCUSED_SAMPLE ->
PgScreenComponent.TextField.State.Focused(isHighlighted = true)
SUCCESS_SAMPLE ->
PgScreenComponent.TextField.State.Success(isHighlighted = false)
ERROR_SAMPLE ->
PgScreenComponent.TextField.State.Error(isHighlighted = true)
WARNING_SAMPLE ->
PgScreenComponent.TextField.State.Warning(isHighlighted = false)
else ->
PgScreenComponent.TextField.State.NoState
}
//...Input method
Input methods specify how workers can enter or edit data in a Text Field on MAI. When an input method is assigned, selecting the field opens a corresponding input interface designed for efficient data entry.
When an input method is assigned, a small icon appears in the text field to show it can be edited (e.g., pen icon).
Once the worker finishes inputting data, the updated content is sent back to the system, triggering a screen data updated event. This event notifies the integrator about the change and includes a reference ID that identifies which Text Field was modified. Because multiple Text Fields may exist on the screen, assigning a unique reference ID to each editable Text Field is essential. This allows the integrator to track exactly which fieldʼs content has changed and respond accordingly.
Type of input methods:
No Input (default) – No input method is assigned. The field is read-only and cannot be edited by the worker.
NumWheel – A rotary wheel input that allows the worker to select a number using three rotating wheels, ideal for numbers up to 999.
Supports an optional title displayed above the wheel.
Can pre-fill the input with an initial value
NumPad – A numeric keypad for entering longer numbers, supporting up to 22 digits (positive numbers only).
Allows setting an optional initial value to pre-fill the input.
Supports an optional hint message shown when the input is empty to guide the worker.
Integrators choose the input method based on the expected input type and workflow needs, ensuring efficient and accurate data entry.
Code (SDK)
//...
fun createSampleInputMethod(sampleType: Int) =
when(sampleType) {
NUMPAD_SAMPLE ->
PgScreenInputMethod.NumPad(
initialValue = "1389",
hint = "Input value"
)
NUMWHEEL_SAMPLE ->
PgScreenInputMethod.NumWheel(
title = "Title",
initialValue = 7
)
else ->
PgScreenInputMethod.NoInput
}
//...On-screen button
The button component is an interactive element displayed on the screen that workers can tap to trigger specific actions. These on-screen buttons are part of the screen view content.
Key features:
Visual appearance - The style and color of the button are defined by the selected template.
Customization - Integrators must set the button text.
Interaction - By default, tapping the button triggers a Notify action, which sends a screen component clicked event to the integrator with the buttonʼs custom reference ID (set by the integrator to uniquely identify which component was pressed). Other screen actions can be assigned instead of Notify.
Placement - Buttons appear only within screen views, mainly in Workflow and Notification templates. Their placement is defined by the selected template.
Limitations - The number of buttons visible at once is constrained by the selected template.
Code (SDK)
//...
fun createSampleButton(): PgScreenComponent.Button =
PgScreenComponent.Button(
referenceId = "mySampleButton",
text = "Click",
onSingleClick = createSamplePgScreenAction(NAVIGATE_BACK_SAMPLE)
)
//...