# Patterns

Patterns define the interactions and data that are exposed and collected by an app. A pattern definition is a YAML document that defines the UI elements of an app. Every UI element is an object with a set of properties that define its looks and behavior. Routegy supports numerous built-in element types that range from simple text inputs (type: text) to more advanced and specialized components like Net Promoter Score element (type: nps).

# Example

The following is an example YAML pattern for an app that collects information about a problem with an office printer. This UI pattern includes a list of checkboxes that map to a list of predefined problem categories, and an additional_problem_info textarea field for additional details or miscellaneous problems not included in the list.

problem:
  type: checkboxes
  items:
    - Doesn't turn on
    - Paper jam
    - No paper
    - No toner
    - Connectivity issue
    - Something else
  title: What's going on?
additional_problem_info:
  type: textarea
  title: Something else or more details?
  placeholder: E.g. Printer screen shows E104 error, cannot be reset and doesn't print

The following is the same pattern rendered by Routegy.

A 'Printer issue' form generated from the Routegy pattern defined above

Once submitted, data collected by this app will be a JSON object with two properties: problem array property and additional_problem_info string property. Example:

{
  "problem": [
      "No paper",
      "No toner"
  ],
  "additional_problem_info": "No supplies can be found anywhere in the print room."
}

# Element properties

Every element is defined as a YAML object with a set of properties that determine the type, appearance, and behavior of a UI component to be rendered in the app. Below is a list of properties that are support in most of the built-in components.

Property	Description
`type`	Determines the type of the UI element. If `type` property is not defined, the object is treated as a fieldset. If `type` is defined, it must be one of the supported element types.
`label` (also `caption` and `title`)	Defines a label for the UI element (optional).
`visible`	Conditional visibility expression (optional).
`default`	The default value for the element (optional). Supported by all built-in elements except for `markdown`.
`required`	Set to true to make entering a valid value into this element mandatory.
`placeholder`	Placeholder string (optional). Supported by elements based on the text input including `text`, `textarea`, `email`, `phone`, etc.
`items`	List of items for multiple or single choice elements like radio buttons and checkboxes.
`tooltip`	Adds a tooltip to a label that appears on hover or touch. You can also specify `tooltipSize` as `small`, `medium` (default), or `large`, as well as `tooltipPosition` as `top`, `right` (default), `bottom`, or `left`.

# Supported element types

Type	Description
string, text	Basic text input
textarea	Multiline textarea input
date	Date input based on HTML date input type
datetime	Datetime input based on HTML datetime-local input time
email	Email input based on HTML email input type
time	Time input based on HTML time input type
uri, url	Url input based on HTML url input type
phone	Text input with a RegEx pattern matching US phone numbers]
password	Masked text input for senstive information
number, integer	Integer input with up-and-down controls
radio, radios, radiobuttons	Multiple radio buttons
dropdown	Dropdown select input
checkboxes	Multiple checkboxes
checkbox, boolean	Single checkbox
tags	Tag input
markdown	Markdown element to display static information

# Text inputs

To render a text input, use a text or string type and customize its appearance with title and placeholder properties.

text_input:
  type: text
  label: Text input
  placeholder: Input some text here

A form with a text input field generated from a Routegy pattern

# Regular expressions

To render a text input with automatic validation against a regular expression pattern, set the pattern property inside the element of a text or string type to a desired RegEx pattern.

api_key:
  type: string
  pattern: '^[0-9a-zA-Z]{32}$'
  label: API key

A form with a regex-validated API key field generated from a Routegy pattern

# HTML input types

Routegy offers built-in support for various HTML input types. Here is a list element types mapped to supported HTML input types.

Routegy element type	HTML input type
date	date
datetime	datetime-local
email	email
time	time
uri	url

Below is an example of a pattern that contains inputs of email and date types.

email:
  type: email
  label: Email address
  placeholder: E.g. john.doe@email.org
dob:
  type: date
  label: Date of birth

A form with formatted email and date fields generated from a Routegy pattern

# Passwords and other masked inputs

WARNING

Be extremely careful when requesting sensitive data in your apps. If you're unsure about how best to process sensitive data, please contact us at support@routegy.com.

Masked text inputs can be helpful when collecting sensitive information like passwords. To render one, set the element's type to password.

password:
  type: password
  label: Password
  placeholder: Enter your password here

A form with a masked field generated from a Routegy pattern

# Text area

To render a textarea, set the element's type to textarea.

comments:
  type: textarea
  label: Any comments?

A form with a text area 'comment' field generated from a Routegy pattern

# Number input

To render a number input with up and down buttons, set element's type to integer or number. Optionally, set minimum and maximum properties attributes to define the allowed range, and set a default value using the default property.

count:
  type: integer
  label: Count
  default: 5
  maximum: 10
  minimum: 1

A form with a number input 'count' field generated from a Routegy pattern

# Radio buttons

To render a group of radio buttons, set the element's type to radio, radios or radiobuttons and define a list of their values/labels using the items array property.

options:
  type: radios
  label: Choose one of the following
  items:
    - Option 1
    - Option 2
    - Option 3

A form with a list of radio options generated from a Routegy pattern

# Item data types

By default, values listed under items property have to be defined as strings. This can be overridden by using dataType property that can be set to one of the following primitive types: string, integer, boolean.

Below is an example pattern with radio buttons mapped to some integer values.

options:
  type: radios
  dataType: integer
  label: Select a number
  items:
    - 1
    - 2
    - 3

# Custom labels

Labels for individual radio buttons can be customized by turning items of the items property into objects with value and label properties. This can be combined with a custom dataType to map non-string values to text labels. Below is an example of a pattern with two radio boxes mapped to true and false boolean values that are labeled as Yes and No respectively.

options:
  type: radios
  label: What is your answer?
  dataType: boolean
  items:
    - value: true
      label: Yes
    - value: false
      label: No

A form containing a list of radio options with displayed values of 'Yes/No' and data-values of 'true/false' generated from a Routegy pattern

# Select input

To render a dropdown select input, set the element's type to dropdown and define a list of dropdown items items using the items property.

options:
  type: dropdown
  label: Choose one of the following
  items:
    - Option 1
    - Option 2
    - Option 3

A form containing a list of options in a select dropdown field generated from a Routegy pattern

# Item data types

Below is an example pattern with a dropdown list of integer values.

options:
  type: dropdown
  dataType: integer
  label: Choose one of the following
  items:
    - 1
    - 2
    - 3

# Single checkbox

To render a single checkbox, define an element of type checkbox or boolean.

checkbox:
  type: checkbox
  label: Checkbox example

A form containing a checkbox field generated from a Routegy pattern

# Multiple checkboxes

To render a group of checkboxes, set the type to checkboxes and define a list of checbox values and labels using the items property.

checkboxes:
  type: checkboxes
  label: Select all that apply
  items:
    - Option one
    - Another option
    - One more option
    - Last option

A form containing a list of checkbox fields generated from a Routegy pattern

# Item data types

# Custom labels

Labels for individual checkboxes can be customized by turning items of the items property into objects with value and label properties. This can be combined with a custom dataType to map non-string values to text labels.

Below is an example pattern with checkboxes that represent integer values labeled with number names. The resulting pattern data will be an array of integers, E.g. [10, 10000].

numbers:
  type: checkboxes
  dataType: integer
  label: Choose one or more
  items:
    - value: 100
      label: One hundred
    - value: 1000
      label: One thousand
    - value: 10000
      label: Then thousands

# Tag input

Tag input is an input element for entering a list of string tags. To render one, use the tags element type. Optionally, the maxItems property can be used to define a maximum number of tags allowed.

tags_example:
  type: tags
  maxItems: 10
  label: Items to refill

A form containing a tag-input field generated from a Routegy pattern with soda flavor tags added entered into it

# Static information

# Markdown

To render text formatted with markdown (opens new window), set the element type to markdown and enter your markdown into the text property.

You can dynamically display values entered from elsewhere in your pattern by referencing the value name and placing it in your markdown with the format ${your_value_name}.

In addition to text, you can specify the size (small, normal (default), medium, large) and whether or not to render the markdown in a visible container with isBoxed set to true.

TIP

Use a pipe (|) after the text property keyword to allow multi-line strings in your YAML.

name:
  type: string
  label: Name
  placeholder: Enter your name
markdownTitle:
  type: markdown
  size: large
  text: |
    # Hello ${name}!
markdown:
  type: markdown
  isBoxed: true
  size: normal
  text: |
    # A first-level header

    **This is bold.**

    _And this is italic._

    Use emoji! :) :smile: :shrug: :magic_wand:

    Links are automatically parsed: URLs like www.routegy.com or email addresses like support@routegy.com

    Of course [regular links](https://routegy.com) are also ok.

    * a list
    * is easy
    * to do

    ::: warning
    :warning: *this is a warning*
    :::

    ::: info
    :bulb: *this is informative*
    :::

    ::: danger
    :exclamation: *this is an error*
    :::

    ::: success
    :white_check_mark: *this is a success*
    :::

    ::: primary
    :point_right: *this is important*
    :::

    ::: normal
    :sleeping: *this is just boring ol' normal*
    :::

    # THE END

A form with a name field and markdown rendered from a Routegy pattern

# Specialized components

# Star rating

To render a star rating widget, add an element of type rating. Optionally, set the size property to small, medium (default), or large to customize the size of rendered stars.

experience:
  type: rating
  default: 4
  label: How was your experience?

A form containing a star rating field generated from a Routegy pattern with four stars selected

# Net Promotor Score

Net Promotore Score (NPS) (opens new window) can be used to quantify a customer's perception of an experience or a product by asking them how likely they are to recommend it to someone else. Routegy provides a component for collecting an NPS numerical value that can be rendered setting type to nps.

score:
  type: nps
  minScoreLabel: Absolutely not!
  maxScoreLabel: Yes!
  label: Would you recommend this product to a friend?

Minimum and maximum score labels and score ranges are customizable using additional element properties as shown below.

Attribute name	Default value	Description
minScoreLabel	Not Very Likely	Label displayed next to the lowest score
maxScoreLabel	Very Likely	Label displayed next to the highest score
minScore	0	Lowest score on on the scale
maxScore	10	Highest score on the scale
passiveScore	7	Starting score for the 'passive' range (orange)
promoterScore	9	Starting score for the 'promoter' range (green)

A form containing an NPS field generated from a Routegy pattern

# Conditional fields

Routegy offers support for conditionally displaying elements using simple comparison logic defined inside the visible property of an element. This allows control of an element's visiblity based on a comparison of an elements value to another element's value or to a defined value.

For instance, the following visible property would evaluate to true only if a value associated with the provide_more_info element is set to true.

visible:
  provide_more_info:
    equalTo: true

Since equals_to is the default comparison operator (more on different operator below), it can be ommited and the entire expression can be reduced to:

visible:
  provide_more_info: true

Below is a more complete example that demonstrates how two text inputs, defined as email and phone, are conditionally displayed depending on the value of the how_to_contact radio buttons element.

how_to_contact:
  type: radio
  label: How would you like to be contacted?
  items:
    - value: by_email
      label: Send me an email
    - value: by_text
      label: Send me a text message
email:
  type: email
  placeholder: E.g. you@example.com
  label: Your email address
  visible:
    how_to_contact: by_email
phone:
  placeholder: 'E.g, 555-555-5555'
  label: You phone number
  type: phone
  visible:
    how_to_contact: by_text

By default, neither email nor phone widgets are visible.

A form containing a 'Contact me' form with no selected option

If how_to_contact's value is set to by_email (Send me an email radio button), the email input is made visible to collect an email address.

A form containing a 'Contact me' form with an email selected as a preferred contact

If how_to_contact's value is set to by_text (Send me a text message radio button), the phone input is made visible to collect a phone number.

A form containing a 'Contact me' form with a text message selected as a preferred contact

# Comparison operators

Here is a list of comparison operators supported inside the visible property.

Property name	Description
equalTo	True if the specified value is equal to the value of the specified element.
notEqualTo	True if the specified value is not equal to the value of the specified element.
lessThan	True if the specified value is less than the value of the specified element. Useful when working with elements that have numerical values like `integer`, `rating` or `nps`.
lessThanOrEqualTo	True if the specified value is less than or equal to the value of the specified element.
greaterThan	True if the specified value is less than the value of the specified element. Useful when working with elements that have numerical values like `integer`, `rating` or `nps`.
greaterThanOrEqualTo	True if the specified value is less than or equal to the value of the specified element.
empty	True if the specified element's value is empty or undefined. The specified value must be boolean `true` or `false`.
notEmpty	True if the specified element's value is not empty and not undefined. The specified value must be boolean `true` or `false`.
contains	True if the specified value is contained in the value of the specified element. Useful when working with elements associated with array values like `checkboxes` and `tags` or any text element.
doesntContain	True if the specified value is not contained in the value of the specified element. Useful when working with elements associated with array values like `checkboxes` and `tags` or any text element.

# Additional examples for conditional elements

Make the something_else textarea visible only if the Something else checkbox is checked in the problem element. Since the value associated with the problem element is an array of strings (values of checked checkboxes), the contains operator is used.

problem:
  type: checkboxes
  title: Printer problem?
  items:
    - Doesn't turn on
    - Paper jam
    - No paper
    - No toner
    - Something else
something_else:
  type: textarea
  title: Something else or more details?
  visible:
    problem:
      contains: Something else

Make the how_can_we_improve textarea visible only if fewer than three stars are selected in the experience rating element.

experience:
  type: rating
  size: large
  label: How would you rate your experience today?
how_can_we_improve:
  type: textarea
  label: Please let us know how can we make the experience better
  visible:
    experience:
      lessThan: 3

# Grouping elements into fieldsets

Combining multiple elements into a fieldset can be done by nesting them inside a parent object that doesn't have a type property set. Fieldsets can be also nested in each other to create a multi-level hierarchy.

The sample pattern below demonstrates a simple field grouping for collecting contact information structured in the following way:

Contact info
  Name
    First name
    Last name
  Email address

To accomplish this, the following YAML definition uses three levels of nested objects. Fieldsets (Contact info and Name) are labeled using the label property (optional), but they don't have a type property like other elements.

contact_info:
  label: Contact info
  name:
    last_name:
      type: text
      label: Last name
    first_name:
      type: text
      label: First name
  email:
    type: email
    label: Email address

# Multipage patterns

Multipage pattern can be used to organize larger forms into multiple, smaller pages with a wizard-like experience. To define a multipage pattern in Routegy, do the following:

Set top-level type property to wizard or multipage
Define pages of your pattern as top level properties - every page is an object that can contain element and field set.

TIP

Conditional fields within a wizard must be fully qualified with the page they belong to (E.g. step_one.prop) .

The following sample is scaffolding for a three-page pattern (all pages are empty).

type: wizard
page_1:
  # Page 1 definition
page_2:
  # Page 2 definition
page_3:
  # Page 3 definition

By default, navigation buttons are captioned as Next, Back, and Submit. Captions can be customized using the buttonCaptions property inside appSettings:

appSettings:
  buttonCaptions:
    next: Forward
    back: Previous
    submit: Send

Below is a complete example for a printer problem pattern that consists of three pages:

Problem page with a list of radio buttons representing common problems
Details page with a text input for collecting more details about the problem
Follow-up page with an option to opt into email or text updates on the problem

type: wizard
problem_page:
  problem:
    type: radios
    label: What is going on?
    items:
      - No paper
      - No toner
      - Printer not responding
      - Printer stuck
      - Something else
details_page:
  details:
    type: textarea
    placeholder: E.g. printer shows error E122
    label: Any more details?
follow_up_page:
  how_to_contact:
    type: radios
    items:
      - value: by_email
        label: 'Yes, send me an email'
      - value: by_phone
        label: 'Yes, send me a text message'
      - value: no_contact
        label: 'No, thanks'
    label: Would you like to recieve updates on this?
  email:
    type: email
    placeholder: E.g. me@example.com
    label: You email address
    visible:
      how_to_contact: by_email
  phone:
    type: phone
    placeholder: 'E.g, 555-555-5555'
    label: You phone number
    visible:
      follow_up_page.how_to_contact: by_phone

First page of a multipage pattern showing a list radio buttons representing common printer problems

Second page of a multipage pattern showing a text area for problem details

Third page of a multipage pattern showing an option to opt into email follow ups

# Instant events

A pattern of type: instant will create an event immediately upon interaction with an associated app. The pattern can define the custom branding and result message; it simply does not define any data to collect and thus does not render a form or UI.

This can be helpful for basic help requests (E.g. Assistance needed!) or notifications (E.g. Someone is using this asset now).

type: instant
appSettings:
  logo:
    >-
      https://routegy-assets.s3.us-west-2.amazonaws.com/routegy/schemas/mock-approval-logo.svg
  colors:
    header: "#2e1046"
    headerText: "#eff0eb"
    footer: "#eff0eb"
    white: "#2e1046"
    black: "#eff0eb"
  successMessage: Thanks for the report!

# Application settings

In addition to the information about components and their layout, pattern can contain application-level settings like custom colors, header logo, button captions, and a post-submit success message.

TIP

These visual features are not visible when the pattern is edited and previewed in the Routegy admin app (opens new window). They will take effect when a pattern is associated with an app, and can be seen when the app is launched. We suggest opening the app in a separate tab and refreshing as you make changes to the pattern.

App customizations can be defined using a top level appSettings object that supports the following properties:

Property name	Description	Default
logo	Path to a custom logo to be displayed at the top of the app header	No logo
successMessage	Message to be displayed after interaction with an app has been successfully completed. Markdown (opens new window) is supported.	`# Thank you! { .m-0 align=center }`
buttonCaptions	Custom captions for built-in navigation buttons. This includes the Submit button as well as Next and Back buttons used in the wizard/multipage patterns	Submit, Next, and Back
colors	Custom colors for various elements of an app that will override default Routegy brand colors.	Please see the custom colors section

# Example

Here is an example pattern that demonstrates some of these customizations including a custom app logo, submit button caption, and selected colors.

appSettings:
  logo: https://routegy-assets.s3.us-west-2.amazonaws.com/routegy/schemas/mock-room-help-logo.svg
  colors:
    header: black
    headerText: '#00fab3'
    black: black
    footer: black
    grey: grey
    primary: '#007252'
    lightGrey: lightgrey
    white: white
    success: '#00b682'
    buttonText: white
  buttonCaptions:
    submit: Report
problem:
  type: radios
  label: What is the problem?
  items:
    - Call quality is poor
    - WiFi signal is poor
    - Projector/TV not working
    - Missing A/V adapters
    - Something else
additional_comment:
  type: textarea
  label: Something else or more details?
  placeholder: Provide additional information here

A screenshot of the app showing all of these customizations in effect is shown below.

Screenshot of a conference room problem report app with custom appSettings.

# Custom color reference

Below is a list of customizable colors along with their default values. When overriding a color, any valid CSS color notation (opens new window) can be used.

Name	Description	Default
header	App header background color
headerText	App header text color used for app name and description text displayed in the app header
footer	App footer background color
white	Background color for contents of an app rendered between the header and the footer
black	Color used for static text like labels as well as text entered into input elements
grey	Secondary color used for visual elements like outlines of checkboxes and radio buttons
lightGrey	Secondary color used for borders of various input elements when they are not active (not focused)
primary	Color used for borders of active (focused) input elements, hover color for radio and checkbox labels, and fill color for radios, checkboxes, and dropdown arrows
buttonText	Text color for buttons
success	Background color for elements associated with success actions and notifications (E.g. application submit button)
warning	Background color for elements associated with warning notifications
danger	Background color for elements associated with danger notifications (E.g. error messages)
info	Background color for elements associated with info notifications (E.g. next button in wizards)

← Organizations Templating →