Diagrams that use buttons to submit values to external systems will usually need input fields where operators can specify the values to send. The shapes documented here are the different input options available for operators to use.

Text Input Text Input Icon

To use a 'free form' text box which will allow the operator to enter a wide range of values, drag one of these shapes onto the canvas. If the operator is allowed to enter absolutely any value, then just adding the shape to the canvas is enough to make it work. If there are restrictions on valid values or the input needs to be certain data types, there are more configuration options:

  • Type: This controls the general type of data the text box is expected to handle. The allowed types are 'Text', 'Number', and 'Password'. Each has a different mix of the settings below.
  • Required: If checked, operators will be required to provide a value here before clicking any connected submit buttons. If the field is left empty, the operator will see a message that all required fields must be completed.
  • Placeholder: A value here will appear as faint text in the text box before an operator clicks into it. This text is different than the 'Default' setting below because the placeholder text is not a real value in that text box, it's just a hint for what the operator should enter. If the operator does not enter anything, that input counts as empty. This is only allowed for 'Text' type inputs.
  • Default: A value here will be pre-populated in the text box when the diagram first loads. This text is different than the 'Placeholder' setting above because the placeholder text is not a real value in that text box, it's just a hint for what the operator should enter. The default value is a real value which will be used if the operator doesn't change it.
  • Max Length: This is the maximum number of characters allowed in this field. This is only allowed for 'Text' type inputs.
  • Pattern: This setting allows a designer to provide a regular expression to enforce rules on the format of data entered. Regular expressions are complex. Third-party tools like regex101 can be used to help create them, or you can contact the Prophecy Consulting Group for assistance. This is only allowed for 'Text' type inputs.
  • Warning Message: This optional setting can be used to specify the error message shown to an operator when any of the configured restrictions are violated. If left empty, each restriction type has its own default error message, e.g. "Value cannot be more than X characters.".
  • Min: For 'Number' type inputs, this specifies the minimum value the operator is allowed to enter.
  • Max: For 'Number' type inputs, this specifies the maximum value the operator is allowed to enter.

Note: Different browsers enforce restrictions like valid characters, max counts, etc. differently. It is sometimes possible for operators to bypass those restrictions by copy/pasting a value into that field, for example. The diagram will enforce the rules as best as possible, but input values may need further validation in other systems.

Textbox Config

If you prefer to restrict the HMI user to specific values rather than using a text box, drag one of these shapes onto the canvas. Once the shape is on the canvas, make sure it is selected and click the 'Configure Dropdown Options' button in the left panel. That will open a window where you can create the list of options for the operator to choose from:

  • Text: This is what the operator will see.
  • Value: This is what will be set on the tag you choose on the button when it is submitted. This does not have to match what is in 'Text', but make sure the Value you enter makes sense for the data type of the tag you're working with. Entering 'Bob' for a tag with an integer data type will cause the tag value to not update.
  • Default: If this is checked, that option will be pre-selected when the operator first loads the diagram. The dropdown will reset to this value if an associated submit button is clicked.

Dropdown Config

Combo Box Combo Box Icon

Combo boxes allow users to type or scan input into a field, with a list of matching options presented in a dropdown as they type. This helps ensure that accurate values are provided, while still allowing the operator to enter a value other than what appears in the predefined list when necessary. Combo boxes are configured the same way Dropdowns are, with the exception that they do not have a separate 'Value' column. When using a combo box, the text shown to the user and the value sent to a tag or CSI will always be the same. If you need to be able to display text to a user but submit a different value, use a dropdown shape.

Combo Box Config

Combo Box Example

Combo boxes can be marked as required by selecting the shape and then clicking this box in the left properties panel:

Required Field Config

Toggle Switch Toggle Switch Icon

The toggle allows you to restrict operator input to true/false. There is no required configuration for toggles once they're dragged onto the canvas, though you can change the on/off colors if you don't like the defaults:

Toggle Switch Config

Mongoose Dropdown Mongoose Dropdown Icon

This shape allows the diagram designer to provide the operator with a list of options to choose from. Unlike the predefined dropdown option, this shape fetches its values from an IDO call. To configure one of these dropdowns, drag it onto the canvas and then click the 'Configure Mongoose Data Display' button in the left panel:

  • Connection: Choose the Mongoose connection this button should make its IDO calls through. Most sites will only have one, in which case the option will be selected automatically.
  • IDO Definition: Choose the name of the IDO Definition you want to display returned values from.
  • IDO Property: Choose the name of the IDO Property in the definition selected above that whose values you want to display.

If filters were set up on the IDO, a row for each will be listed in this section of the form. The 'Filter Index' is the number that will be replaced with the value specified for each filter row (see the linked page above for more info). Each row can specify either a predefined value set by the diagram designer, or a 'live' value provided by the operator. Make sure that your filters are usually going to result in multiple values being returned, to populate the dropdown. If it's likely that only a single value will be returned, the Mongoose Value Display shape (see above) is probably a better fit for this part of the diagram.

  • Filter Value: If you want to use a predefined value, put it here. This field also supports tokens.
  • Filter Input Field: If you want the filter value to come from a user input field on the diagram, choose its name from this dropdown.
  • Column Name: If the shape chosen for a Filter Input Field is a grid (see below), choose the column the filter value should come from. The user will select that value by clicking on a row in the grid.

Mongoose Dropdown Config

Mongoose Combo Box Mongoose Combo Box Icon

Mongoose combo boxes allow users to type or scan input into a field, with a list of matching options presented in a dropdown as they type. This helps ensure that accurate values are provided, while still allowing the operator to enter a value other than the predefined list when necessary. Unlike the predefined combo box option, this shape fetches its values from an IDO call. Combo boxes are configured the same way Dropdowns are (see above).

Time Input Toggle Switch Icon

Time input shapes allow operators to input time values that are more likely to be in a valid format than using the free-form text input shape. To configure one of these inputs, drag it onto the canvas and then click the 'Configure Time Input Options' button in the left panel:

  • Min: This specifies the minimum value the operator is allowed to enter. It should be in HH:MM:SS AM/PM format.
  • Max: This specifies the maximum value the operator is allowed to enter. It should be in HH:MM:SS AM/PM format.
  • Default: This is the default value the shape will have when the diagram is first loaded. If the operator does not change the value, this will be used when any associated buttons are clicked. It should be in HH:MM:SS AM/PM format.
  • Warning Message: This optional setting can be used to specify the error message shown to an operator when any of the configured restrictions are violated. If left empty, each restriction type has its own default error message, e.g. "One or more required fields is empty.".
  • Output Format: Tags and CSI format their dates differently. Choose the target this input value will be sent to and the provided time will be converted to the correct format when the button is clicked.
  • Required: If checked, operators will be required to provide a value here before clicking any connected submit buttons. If the field is left empty, the operator will see a message that all required fields must be completed.

Time Input Config

Note: Different browsers enforce input restrictions differently. It is sometimes possible for operators to bypass those restrictions by copy/pasting a value into that field, for example. The diagram will enforce the rules as best as possible, but input values may need further validation in other systems.

Required Fields

Most input shapes can be marked as required when needed. If an input marked as required doesn't have a value in it when a button connected to that input field is clicked, the operator will see a message prompting them to fill in all fields:

Required Field Warning