Prompt from Container

This statement is used to present an interactive table in the Action Pending Window based on a container's contents. Everything in the table is configurable on a column and row basis.

The two text fields may contain any of the escape sequences described in Escape Sequences. The prompt field is optional.

You can configure up to four buttons. See Configuring Buttons on Prompt Statements for more information.

The statement supports additional configurability which is documented in Advanced Prompt Statement Functionality. These settings can be configured by clicking on the button with the gear icon.

Upon return from this statement, all edited values will be in the container.

In order to assist in producing the container the Create Container from JSON statement can produce a template for this statement which can be edited.

The specified container must adhere to the specification described in this document.

If the specified container does not exist or is not an Object, action processing will be terminated.

A table is presented which can contain up to three columns:

State

A checkbox

Name

Typically the identification for a row. This column is never editable.

Value

A text value field.

The table has a context menu which by default displays the following items:

• Set All to On
• Set All to Off
• Set All to Mixed

The general format of the container object is as follows:

{
   "columns" : {
      ...  
   },
   "rows" : [
      {
         row 0
      },
      ...
   ]
}

The columns object and every item in it is optional.

The rows object must be present and have at least one row. Items in rows should be objects. Any row which is not an object is treated as a separator row and is modified in the container to be an object as follows:

{ "separator" : true }

Unless otherwise mentioned, when testing for rows items and an item does not exist, columns will be searched for the same item. This means that the columns object can set defaults for rows.

Table of Contents

The following sections describe the object items (keys), used in columns and rows objects to configure the panel.

Column Header Names

Context Menu Item Names and Visibility

Per Row Cell Values

Hiding Columns

Disabling the State Column's Checkbox

Setting the State Column's Behaviour

Controlling the Display of Rows

Disabling Rows and the Value Column

Validating Values

Drag & Drop

Popup Menus

Easing the Acquisition of File and Folder Paths

Providing Multi Line Editor Access

Providing Per Row Help

Controlling the Number of Selected rows and Determining the Highlighted Row

Clearing Values when Deselecting Rows

Clearing State when Disabled

Auto Loading and Saving

Other topics in this document

Flexibility on Data Types

About Window Sizing

First Time Usage Panel

Referencing Rows

Additional information

Containers

Directed Paths

Column Header Names

These items control the names of the column headers and are only read from the columns object.

nameTitle

The header for the Name column. If omitted, the header will be Name.

valueTitle

The header for the Value column. If omitted, the header will be Value.

stateTitle

The header for the State column. If omitted, the header will be State.

{
  "columns" : {
    "nameTitle" : "Title",
    "stateTitle" : "State",
    "valueTitle" : "Value"
  },
  "rows" : [
	...
  ]
}

Context Menu Item Names and Visibility

These items control the names of the menu items and are only read from the columns object.

menuOn

You can specify alternate text for the Set All to On menu item. If the text is empty, the menu item will be hidden.

menuOff

You can specify alternate text for the Set All to Off menu item. If the text is empty, the menu item will be hidden.

menuMixed

You can specify alternate text for the Set All to Mixed menu item. If the text is empty, the menu item will be hidden.

{
  "columns" : {
    "menuMixed" : "Set All to Mixed",
    "menuOff" : "Set All to Off",
    "menuOn" : "Set All to On"
  },
  "rows" : [
	...
  ]
}

Per Row Cell Values

The following items are used to preset values for each cell in the table and will contain modifications.

name

The value displayed for the Name column. The item is ignored if it is not a String. If omitted, empty is assumed.

state

The value initially presented or returned for the State column. If the State column is hidden, the item is ignored. The item will typically be a Boolean for non mixed state columns and a Number for mixed state columns. 0 (Off), 1 (On), -1 (Mixed). If omitted, Off (0) is assumed. If omitted, the item will only be created if it is edited.

value

The value initially displayed or returned for the Value column. If the Value column is hidden, the item is ignored. The item is ignored if it is not a String. There is one exception which will be covered later. If omitted, empty is assumed. If omitted, the item will only be created if it is edited.

{
  "rows" : [
    {
      "name" : "Sample row 1",
      "state" : true,
      "value" : "Sample value 1"
    },
    {
      "name" : "Sample row 2",
      "state" : false,
      "value" : "Sample value 2"
    }
  ]
}

Typically each row object should have a name item at the minimum. state and value items will be created if edited.

Note that rows which are not separators and would display as completely empty, display as ••• in the State column.

When the State column is not hidden, you can use the context menu to Set all On, Set All Off or Set All Mixed. Set All Mixed will only modify rows which are capable of retaining mixed values. Note that items which are hidden or disabled are not modified.

Hiding Columns

The following items are used to hide columns.

stateHidden

This is a Number item and controls whether the state checkbox is hidden or available. If omitted, 0 or an unsupported value, the State column is not hidden. The following values are supported:

Value	Description
0	The State column is not hidden
1	The State column is hidden
2	The State column's checkbox is hidden if the name item has an empty value
3	The State column's checkbox is hidden if the value item has an empty value
4	The State column's checkbox is hidden if the name or value items have an empty value
5	The State column's checkbox is hidden if the name and value items have an empty value

If stateHidden has a value of 1 in the columns object, the State column will not show. ie. you cannot override it on a per row basis in the rows object. If you selectively want to hide the checkbox in the State column you must use stateHidden in the rows object.

valueHidden

If true, the Value column will be hidden. If set to false or if omitted, the Value column will be displayed. When the column is hidden, all other value items are ignored.

If valueHidden is true in the columns object, the Value column will not show. ie. you cannot override it on a per row basis in the rows object. When valueHidden is set to true in a rows object, the cell's Row column will display as empty.

{
  "columns" : {
    "valueHidden" : true
  },
  "rows" : [
    {
      "name" : "No checkbox displayed",
      "state" : true,
      "stateHidden" : 1
    },
    {
      "name" : "Checkbox Displayed",
      "state" : false
    }
  ]
}

Disabling the State Column's Checkbox

The checkbox displayed in the State column can be disabled. While this would typically be done in a rows object, it can also be done in columns.

stateDisabled

This is a Number item and controls whether the state checkbox is enabled (default) or disabled. If omitted, 0 or an unsupported value, the State column is not disabled. When disabled, the state column will display its value but it cannot be changed. The following values are supported:

Value	Description
0	The State column's checkbox is not disabled
1	The State column's checkbox is disabled
2	The State column's checkbox is disabled if the name item has an empty value
3	The State column's checkbox is disabled if the value item has an empty value
4	The State column's checkbox is disabled if the name or value items have an empty value
5	The State column's checkbox is disabled if the name and value items have an empty value

{
  "rows" : [
    {
      "name" : "State is disabled and on",
      "state" : true,
      "stateDisabled" : 1
    }
  ]
}

Setting the State Column's Behaviour

These items control how the State column's checkbox can display and how a row's checkbox is affected by context menu items.

stateMixed

If true, the State column will support tri-state checkboxes. On, Off or Mixed (-). If set to false or if omitted, the State column will display simple On/Off checkboxes.

stateIgnoreMenu

The displayed table's context menu may contain items to set all checkboxes to On, Off or Mixed. When this item is true, checkboxes will not respond to the menu commands. Typically this item would only be specified on a row basis.

{
  "columns" : {
    "stateMixed" : true
  },
  "rows" : [
    {
      "name" : "State is mixed and ignore the context menu",
      "state" : -1,
      "stateIgnoreMenu" : true
    }
  ]
}

Controlling the Display of Rows

These items are only processed in the rows object.

separator

If set to true, the row is treated as a separator line. It will display as entirely empty and may not be selected. This is useful for the insertion of spacer rows. If an item in the rows array is not an object, it will be treated as a separator. Note than a non object separator is modified in the container to be an object as follows:

     { "separator" : true }

bold

The text displayed in the Name column will be bold.

placeholder

A placeholder value to be displayed if the value field is empty.

{
  "rows" : [
    {
      "bold" : true,
      "name" : "This is a header row",
      "stateHidden" : 1,
      "valueRO" : 1
    },
    {
      "separator" : true
    },
    {
      "name" : "row 1"
    },
    {
      "name" : "row 2",
      "placeholder" : "default row 2 value"
    }
  ]
}

If you want to display spaces as centered dots in the Value column, you can add a showSpaces item set to true in rows or columns. Note that a rows value has higher priority.

{
  "rows" : [
    {
      "name" : "Display spaces as centered dots for this row",
      "showSpaces" : true
    }
  ]
}

Disabling Rows and the Value Column

Entire rows can be disabled and the Value column can be treated as read only.

valueRO

A Number controlling the edibility and display of the Value column.

Value	Description
0	The Value column is editable.
1	The Value column is not editable. The value is not dimmed so that a read only Value field can visually be used as a title.
2	The Value column is not editable. The value is displayed bold. This is equivalent to a value of 1 if the row has a getPath item or has a popup menu.
-1	The Value column is only editable if the state value in the same row is not 0 (or false). When not editable, the value will be dimmed.
-2	The Value column is never editable. If the state column in the same row is not 0 (or false) the value will not be dimmed. When the state column in the same row is 0 (or false) the value column will be dimmed.

valueRO is processed after rowDisabled and enabled.

rowDisabled

A row only item which when set to true, disables the entire row. rowDisabled is processed before enabled and valueRO.

enabled

An array of criteria items which determine if a row should be enabled or disabled. Note that the same items are used in container menus when disabled and hidden are arrays and in this container when the popupAppends key is an array.

Each item in the array must be an object and can contain the following items:

link

This item must be present, unless checkbox is true. Its value must be a string for which an anchor exists in a row. This is a reference to the row being tested.

checkbox

Only examined if link is missing. If checkbox is true, the panel's checkbox field is being tested as opposed to a row with an anchor.

function

A string object describing the test function. All function names are case insensitive. Note that when checkbox is true, only the functions displayed as blue text are valid.

Function	Description
On	Tests if the State column of the referenced row, or the panel's checkbox, is checked.
Not On	Tests if the State column of the referenced row, or the panel's checkbox, is not checked.
Off	Tests if the State column of the referenced row, or the panel's checkbox, is not checked or mixed.
Not Off	Tests if the State column of the referenced row, or the panel's checkbox, is checked or mixed.
Mixed	Tests if the State column of the referenced row, or the panel's checkbox, is mixed.
Not Mixed	Tests if the State column of the referenced row, or the panel's checkbox, is not mixed.
Equals	Tests if the Value column of the referenced row is case insensitive equal to the specified value. May also be specified as Equal.
Not Equals	Tests if the Value column of the referenced row is not case insensitive equal to the specified value. May also be specified as Not Equal.
Starts With	Tests (case insensitive) if the Value column of the referenced row starts with the specified value. If the specified value is empty, the test always fails.
Not Starts With	Tests (case insensitive) if the Value column of the referenced row does not start with the specified value. If the specified value is empty, the test always fails.
Ends With	Tests (case insensitive) if the Value column of the referenced row ends with the specified value. If the specified value is empty, the test always fails.
Not Ends With	Tests (case insensitive) if the Value column of the referenced row does not end with the specified value. If the specified value is empty, the test always fails.
Contains	Tests (case insensitive) if the Value column of the referenced row contains the specified value. If the specified value is empty, the test always fails.
Not Contains	Tests (case insensitive) if the Value column of the referenced row does not contain the specified value. If the specified value is empty, the test always fails.
==	Tests if the Value column of the referenced row is equal to the specified value when both are treated as integers. May also be specified as =.
!=	Tests if the Value column of the referenced row is not equal to the specified value when both are treated as integers.
<=	Tests if the Value column of the referenced row is less than or equal to the specified value when both are treated as integers.
<	Tests if the Value column of the referenced row is less than the specified value when both are treated as integers.
>=	Tests if the Value column of the referenced row is greater than or equal to the specified value when both are treated as integers.
>	Tests if the Value column of the referenced row is greater than the specified value when both are treated as integers.

value

When a function requires a value, it is specified here.

Successive tests in the enabled array are ANDed. ie. every test must succeed in order for a row to be enabled. If enabled is not defined or it does not contain any objects, the associated row is enabled.

enabled is processed before valueRO and is only evaluated in the rows object. enabled potentially disables entire rows. valueRO only effects the Value column. enabled is processed after rowDisabled.

anchor

An arbitrary string which can be referenced from a rows's enabled object. It essentially serves as a named reference to the containing row.

clearIfDisabled

Rows can be disabled based on the state or values of other rows. If this item is true, the state and value items will be emptied whenever a row is disabled.

{
 "rows" : [
    {
      "name" : "valueRO test",
      "value" : "disabled unless state is checked",
      "valueRO" : -1
    },
    {
      "anchor" : "control",
      "name" : "State controls test row 1 and 2",
      "state" : 1,
      "valueRO" : 1
    },
    {
      "anchor" : "control2",
      "name" : "Value controls test row 2",
      "value" : "When cleared, test row 2 will be disabled"
    },
    {
      "enabled" : [
        {
          "function" : "on",
          "link" : "control"
        }
      ],
      "name" : "test row 1",
      "value" : "Row 1 value"
    },
    {
      "clearIfDisabled" : true,
      "enabled" : [
        {
          "function" : "on",
          "link" : "control"
        },
        {
          "function" : "not equal",
          "link" : "control2",
          "value" : ""
        }
      ],
      "name" : "test row 2",
      "value" : "Row 2 value. Cleared when disabled"
    }
  ]
}

Validating Values

You can perform validation of items in the Value column. Validating is performed when closing the panel via a Continue button. If validation fails an error message is displayed and the panel is not closed.

validate

This item is a String and can contain any of the validation codes described in Prompt Text Format Codes which is accessible on the Help>Quick Reference menu. Note that Value fields which are read only, are on rows which are disabled or separators, are not validated. Note that when a row is validated, its value item is always rewritten as a string.

{
  "rows" : [
    {
      "name" : "Cannot exit when the value column is empty",
      "validate" : "E"
    }
  ]
}

Tip : if you want to validate the proper range of values on a row which has valueIsPopup=1, you can test the value as:

#0, number of menu items-1

Drag & Drop

You can enable the dragging of rows.

drag

If true, the dragging of rows is enabled. Any row which can be dragged can be dropped on any other row which can be dragged. You cannot drag a separator row, or onto a separator row. The positions of the source and destination objects are reversed. All items in the two objects are swapped with the exception of the following items:

• anchor
• autoSaveRowOnContinue
• autoSaveRowOnExit
• autoSaveSuppress0State
• autoSaveSuppress0Value
• autoSetRow
• clearStateIfDisabled
• name
• rowFixedReference
• state
• stateDisabled
• stateHidden
• stateID
• stateInit
• stateIgnoreMenu
• stateMixed

{
  "rows" : [
    {
      "drag" : true,
      "name" : "Row 1 can be dragged",
      "value" : "row 1"
    },
    {
      "name" : "Row 2 cannot be dragged",
      "value" : "row 2"
    },
    {
      "drag" : true,
      "name" : "Row 3 can be dragged",
      "value" : "row 3"
    }
  ]
}

Popup Menus

You can provide popup menus on every row or on a per row basis. The popup menus can use a numeric index into a menu as its value or a text string. Menus can be editable or not. When text based, the icon at the right of the Value column will be a down triangle. When index based, the icon at the right of the Value column will be an up-down triangle. When index based, clicking anywhere in the cell be display the menu. When text based the icon must be clicked to display the menu.

valueIsPopup

Value	Description
0	No menu is associated with the row or rows. No icon will be displayed. This is the default value if valueIsPopup is not defined.
1	The associated menu is referenced by value containing a zero based index into the menu defined in popupValues. In this case value can be a Number or String. A Number will be returned if the value is changed. If the value is out range of the popup Values, the value column will display as empty. A value of -2 is an exception. With this value, the popup menu is only presented for informational purposes. The value is not modified when a menu item is selected.
2	The value is always treated as text to be displayed and may contain items not in the associated menu. The text field is editable.
3	The value is always treated as text to be displayed and may contain items not in the associated menu. The text field is not editable.

popupValues

An array of values, only accessed if valueIsPopup is not 0, which describe the menu items, Each array element can be one of:

• a String representing the menu item's description.
• an Object representing the menu item's description. The object can contain the following keys:
  
  

  Key	Description
  name	This key is mandatory (unless separator is true) and describes the menu item's description. If missing, the entire menu will not be displayed.
  separator	A boolean value. When true, the menu item is a separator line.
  hidden	A boolean or array value. When boolean and true, the menu item is hidden. Note that hiding a menu item does not affect indexes when isPopupValue has a value of 1. When an array, it is formatted the same as the enable item's array. This allows a menu item to be hidden based on runtime criteria.
  disabled	A boolean or array value. When boolean and true, the menu item is disabled (dim and not selectable). When an array, it is formatted the same as the enable item's array. This allows a menu item to be disabled based on runtime criteria.
  icon	An integer value describing an optional icon to be displayed on the menu item. See the Prompt Menu Formatting topic for additional information.
  others	Ignored.

  
  
• any other item type will cause the entire menu not to be displayed.

When the Prompt from Container statement is executing, popupValues must be an array. However, when constructing the container it can also be a string. When the Prompt from Container statement starts executing, the string is interpreted as a named variable whose contents, delimited by the default list delimiter (\~) or a newline character (\n), is used as a list of strings to store in the array. The popupValues item is modified to be an array. This is a convenient method of initializing the popupValues to a list of string items which are not static.

popupAppends

This item is only used if valueIsPopup has a value of 2 or 3. When true, selecting a menu item appends the menu item's description. A delimiter is inserted if required to separate appended values. The delimiter is established from the popupDelimiter key. A true or false value can be supplied or alternately the item can be an array containing criteria items. See the enabled key in Disabling Rows and the Value Column for a description of the criteria iotem formatting.

popupDelimiter

This string value is used as an append delimiter when one is required. If popupDelimiter is empty, a comma is assumed.

Note that prior to Yate version 6.10, isPopupValue was a boolean setting where false was equivalent to the current 0 value and true was equivalent to the current 1 value. An item named popupEditable was read and if true the popup mode was effectively the same as if isPopupValue is 2. In order to maintain compatibility, popupEditable is still read if isPopupValue has a value of 1.

Whenever a row associated with a popup menu is displayed and it is disabled or read only, the icon to display the menu will be hidden.

{
  "rows" : [
    {
      "name" : "An index based menu",
      "popupValues" : [
        "NO",
        "YES"
      ],
      "value" : 1,
      "valueIsPopup" : 1
    },
    {
      "name" : "An editable field and text based menu which appends and has a disabled menu item",
      "popupAppends" : true,
      "popupValues" : [
        "M1",
        {
          "disabled" : true,
          "name" : "M2"
        },
        "M3"
      ],
      "value" : "value not in menu",
      "valueIsPopup" : 2
    },
    {
      "name" : "A non editable field which is initially empty and text based menu",
      "popupValues" : [
        "M1",
        "M2",
        "M3"
      ],
      "valueIsPopup" : 3
    },
    {
      "name" : "An editable field whose popup values are deferred",
      "popupValues" : "popupMenuSourceNamedVariable",
      "valueIsPopup" : 2
    }
  ]
}

Easing the Acquisition of File and Folder Paths

It is possible to display a system get file or folder panel and save the path to the selected item in the Value column. With the exception of the getPathPrompt item, these items are only accessed in the rows object.

getFilePath

An file icon will be displayed to the right of the value field which when clicked will display a standard system open panel where you can select a file. The item is a String and must not be empty. If * is the value all files may be selected, otherwise the value is a comma separated list of filename extensions which are valid for selection. Do not precede the filename extensions with a period.

getFolderPath

A folder icon will be displayed to the right of the value field which when clicked will display a standard system open panel where you can select a folder. The item is a Boolean value which enables the display of the menu item.

getNewFilePath

A file icon will be displayed to the right of the value field which when clicked will display a standard system save panel where you can choose a file. The file does not have to exist. The item is a String and must not be empty. If * is the value all files may be selected, otherwise the value is a comma separated list of filename extensions which are valid for selection. Do not precede the filename extensions with a period.

abbreviatePath

When either of the above three items are present, setting abbreviatePath to true will abbreviate a path relative to the home folder. ie. /Users/John/Documents will become ~/Documents.

getPathPrompt

An optional String item which is used as a prompt in the displayed get file/folder panel.

Note that a non zero valueIsPopup takes precedence over getFilePath which takes precedence over getFolderPath which takes precedence over getNewFilePath.

{
  "rows" : [
    {
      "getFilePath" : "txt",
      "name" : "Path to existing .txt file"
    },
    {
      "getNewFilePath" : "txt",
      "name" : "Path to new or existing .txt file"
    },
    {
      "getFolderPath" : true,
      "name" : "path to folder"
    }
  ]
}

Providing Multi Line Editor Access

At times entering data in a single row cell is inconvenient. This is especially true if the data can contain newline characters. For these cases you can mark the row as being multi line. When a row is designated as being multi line, an icon will be displayed at the right of the field to activate the editor. If the row is disabled or marked as read only, the icon will not appear.

multiLine

When true or a positive integer, the row's Value is designated as being multi line. When less than 0, the row's Value is designated as being multi line and inline editing of the value field is disabled. ie. the multi line editor must be used. Note that this item is only valid in rows.

multiLineExit

This row only item allows you to provide a custom editing experience. The item is only examined if multiLine is non zero. When the item has a non zero value and the multi line icon is pressed, the panel is immediately closed as if an Exit button was pressed. Row validation does not occur and the multi line edit panel is not displayed. The Prompt Chosen Button named variable will be set to the specified value. Note that currently values of 1, 2, 3 and 4 are used to denote which panel button was used to exit. -1 is used to represent an exit caused by the panel checkbox. -1000 is used to represent an Exit warning style on a Cancel button. It is a good idea to avoid these values.

multiLineEmpty

This item controls how visually empty lines are handled:

Value	Description
0	All empty lines are retained.
1	Leading empty lines are removed.
2	Trailing empty lines are removed.
3	All empty lines are removed.

If a negative value is specified, a single trailing empty line will always be present. This is useful if you want to ensure that the last line of text is followed by a newline sequence.

The item is only examined if multiLine is non zero and multiLineExit is zero.

multiLineSeq

This item controls how the multi line editor determines line breaks. This item is valid in rows and the columns object. The item is only examined if multiLine is non zero and multiLineExit is zero.

When the item is omitted or is empty, the Value field will display newline characters as the Default List Delimiter (⏎). Note that this method leaves the newline characters in the saved value. If you are saving the values to a runtime setting, this will not have the desired effect as the setting will be truncated at the first newline character.

When the item is specified and is not empty, it is used as the pattern which is treated as a linebreak by the multi line editor. When the editor is closed, all newline characters will be replaced by the pattern.

Note that a non zero valueIsPopup and non empty getFilePath, getFolderPath and getNewFilePath all take precedence over multiLine.

example:

{
  "rows" : [
    {
      "multiLine" : -1,
      "name" : "Row 1",
      "value" : "row 1\npart 2"
    },
    {
      "multiLine" : true,
      "multiLineSeq" : ",",
      "name" : "Row 2",
      "value" : "row 2,part 2"
    },
    {
      "multiLine" : -1,
      "multiLineExit" : 100,
      "name" : "exit when the icon is clicked",
    }
  ]
}

The value field in fist row with display as: row1⏎part 2. When displayed in the multi line editor it will display as:

row 1
part 2

After editing in the multi line editor, all newlines will appear as ⏎ characters but \n characters will still be in the data. Note that Row 1 cannot be edited inline.

The display of the value field in the second row will not be modified. It will display the same as row 1 in the multi line editor. After editing in the multi line editor, all newlines will be replaced with a , sequence. Note that Row 2 can be edited inline.

The third row cannot be edited inline. When the row's icon is pressed, the panel will close with a value of 100 in Prompt Chosen Button.

Providing Per Row Help

If you want to display per row help which is different that displayed by the optional Help button, you must declare a key named help. The help is displayed by selecting a row and hitting the spacebar key.

help

The value is a String and must be formatted the same as the Prompt Help Button URL named variable as described in Configuring Buttons on Prompt Statements . At runtime an <m> sequence will automatically be inserted at the start of the string if it does not begin with an http, ? or <m> sequence. When adding markup sequences while using the JSON Multi Line Editor Panel, an <m> tag will be inserted at the start of the JSON text if the sequences are inserted via a markup menu or keyboard shortcut. This tag will automatically be removed when saving the JSON text and can be ignored.

The per row help text can be deferred to runtime. This allows you to efficiently share the same per row help for multiple rows. The help value is specified as: = named variable

{
  "rows" : [
    {
      "help" : "Sample inline per row help",
      "name" : "Row with per row help"
    },
    {
      "help" : "\<row 2 help>",
      "name" : "Row with per row help in named variable inserted when the container is created."
    },
    {
      "help" : "=row 3 help",
      "name" : "Row with deferred help in named variable 'row 3 help'."
    },
    {
      "name" : "Row without per row help"
    }
  ]
}

Controlling the Number of Selected rows and Determining the Highlighted Row

If you want to ensure that at least one row has the state column set, place a selectAtLeastOne key with a value of true in the Columns object. Rows which have a stateIgnoreMenu item set to true are not considered. When the panel is closed and validation is performed, a test is made to ensure that at least one appropriate row has a state value other than false.

If you want to enforce that one and only one row has the state column set, place a selectOne key with a value of true in the Columns object. Rows which have a stateIgnoreMenu item set to true will not be modified and take no part in the process.

When the selectOne key is true, the context menu items to set all state values will be hidden. Whenever a state value is set to On, all other state columns will be set to Off. Rows which have stateIgnoreMenu item set to true will not be modified and take no part in the process. When the panel is closed and validation is performed, a test is made to ensure that one appropriate row has a state value other than false. The container object will have a key named selectedRow which contains the index of the selected row. Please read: Prior to Yate v6.11, the selectedRow key was incorrectly written to the Columns object as opposed to the container object. For now Yate will write the key to both locations in order not to break any existing actions ... but at some point it will stop doing so.

If selectOne is effectively false, the selectedRow key will contain the index of the table row which is highlighted. If no table row is highlighted, the key will be set to -1.

Clearing Values when Deselecting Rows

There are two methods of automatically clearing a value :

clearIfDisabled

Rows can be disabled based on the state or values of other rows. See the enabled key in Disabling Rows and the Value Column . If clearIfDisabled is true, the value column will be cleared whenever a row is disabled.

clearOnDeselect

If clearOnDeselect is true, a value field will be cleared whenever its state checkbox is set to unchecked.

Clearing State when Disabled

Whenever the State checkbox on a row is disabled you can automatically clear the state value. ie. if State is checked or mixed and for any reason, the state checkbox is disabled, its value will become 0. Set clearStateIfDisabled to true in rows or columns to force this behaviour.

Auto Loading and Saving

It can be tedious to set and extract the values associated with the state and value columns. Many times the values will be kept in the current action runtime setting set and/or in named variables. The following items can used to control the process on a global or per row basis. Unless otherwise mentioned, the items can appear in rows or columns.

autoSetRow

This item controls if state and value are automatically set prior to displaying the window.

Value	Description
0	No automatic loading of occurs.
1	Automatic loading is performed from the current action runtime setting set.
2	Automatic loading is performed from named variables.

stateID

This rows only item is the name of the action runtime setting or named variable to be accessed when loading or saving the state item.

stateInit

If autoSetRow is 1 and the mapped runtime settings set is empty or does not exist, this optional rows only item can contain the value used to be displayed for state.

valueID

This rows only item is the name of the action runtime setting or named variable to be accessed when loading or saving the value item.

valueInit

If autoSetRow is 1 and the mapped runtime settings set is empty or does not exist, this optional rows only item can contain the value used to be displayed for value.

autoSaveRowOnContinue

This item controls if state and value are automatically saved when the window is closed by a Continue style button.

Value	Description
0	No automatic saving occurs.
1	Automatic saving is performed to the current action runtime setting set.
2	Automatic saving is performed to named variables.
-2	Automatic saving is performed to named variables. If a value is empty and there is a placeholder for the field, it is saved to the named variable.
3	Automatic saving is performed to the current action runtime setting set and to named variables.
-3	Automatic saving is performed to the current action runtime setting set and to named variables. If a value is empty and there is a placeholder for the field, it is saved to the named variable.

autoSaveRowOnExit

This item controls if state and value are automatically saved when the window is closed by an Exit style button. The values are interpreted the same as for autoSaveRowsOnContinue.

autoSaveSuppress0State

This item allows you to omit redundant action runtime settings when saving state. When set to true, if the state to be saved is 0 or false, the runtime setting is removed.

autoSaveSuppress0Value

This item allows you to omit redundant action runtime settings when saving value. When set to true, if the value to be saved is exactly 0, the runtime setting is removed.

There are times when you might be conditionally displaying a panel but you want the same named variables set whether the panel is displayed or not. The Extract IDs from Prompt Container statement allows you to get and set various information based on the stateID and valueID settings in a container.

Flexibility on Data Types

In order to be able to create the container using the Create Container from JSON statement and to initialize any of the above settings using named variables, all integer or boolean fields may be specified as strings. Note that the Create Container from JSON statement only accepts named variables within strings. When a numeric or boolean value is implied, a string is interpreted as follows: "true" (case insensitive) is treated as 1, otherwise the integer value of the text is used.

About Window Sizing

The Action Pending Window can be configured to resize automatically or to retain its last displayed size. When displaying containers this may not be advantageous, especially if multiple containers are being displayed with different metadata.

The Prompt from Container statement uses a different method to determine the window size. Whenever a container is displayed and the window is closed, a Prompt Window Size named variable will be written as widthxheight, state column width. Whenever a Prompt from Container statement is issued, the size in the named variable, if valid, will be used. If the size is not valid, (formatted incorrectly or too small), the default window sizing algorithm will be used.

If you never use the named variable, the last window size will be used.

If you always want the default size of the window to be displayed, clear the Prompt Window Size named variable prior to executing the Prompt from Container statement.

First Time Usage Panel

You can display a first time usage panel when the window is displayed. The columns object can contain a key named firstTimeUsage where the value is a named variable which contains the help text. The text can contain markup sequences. If the text is empty the first time usage panel will not be displayed.

The displayed panel has a Do not show again checkbox. If the checkbox is enabled, the named variable will be set to empty. This allows you to detect and retain state.

Typically you would have a setting in an action runtime settings set which controls whether the first time usage panel is displayed. Based upon the value of the setting, you would place text into the named variable or you would clear it. In order to make this process easier, you can optionally place a # before the name of the named variable. When this tag is detected and the Do not show again checkbox is checked when the panel is dismissed, the following will occur:

• A runtime setting of the same name of the specified named variable will be read.
• If its value is true or has a non zero integer value, it will be set to an empty string (effectively false) otherwise 1 (effectively true).
• The setting is complemented so that you can work with true or false meaning display the panel.
• The # tag is not part of the named variable's or runtime setting's name.

Example: assume the following in a container named obj :

"columns" : {
	"firstTimeUsage" : "#FTU",
	...
}

The following statements will implement a retained state. Note that the first statement is accessing a runtime setting.

Test if text "\#FTU#" is true (Set result)
if true
    Set named variable 'FTU' to "... the text"
else
    Set named variable 'FTU' to empty
endif
Prompt from Container 'obj'

If runtime setting FTU is not true, named variable FTU will be set to empty and the panel will not be displayed.

If runtime setting FTU is true, named variable FTU is initialized to the text. If the user checked the Do not show again checkbox, named variable FTU will be emptied and runtime setting FTU will be complemented (and because it was true, it will be emptied).

Note that the runtime setting will be complemented, if necessary, even if the Prompt from Container panel is subsequently cancelled.

Referencing Rows

When you want to extract results from the container after the prompt closes, you might need a reference point to a row. Using absolute references based on numeric indexes is possible but can lead to issues as you might restructure the container or change row positions by dragging rows when the container is displayed.

A reference to a row can be saved to a named variable by using a rowReference key which supplies the name of the named variable as its value. eg:

	
{
   "columns" : {
      ...  
   },
   "rows" : [
   	  {
   	  },
   	  ...
      {
         "name" : "sample1"
         "rowReference" : "namvar",
         "value" : "test"
      },
      ...
   ]
}

In the previous example, the row with name sample1 can be referenced as \<namvar>. eg: \<namvar>.value

The named variable namvar will be set to:

objectName.rows[ index ]

where objectName is the name of the container and index is an integer value representing the row's position in the rows array.

Row references are placed into the named variables whenever a Prompt from Container or Extract IDs from Prompt Container statement starts executing. The Extract IDs from Prompt Container statement has a mode which only establishes the references, as there are times when you create the container and need the references to finish the structuring of the object before displaying it.

Note that row references written by rowReference keys are recalculated when rows are dragged. ie.the row references move with the drag. If you do not want this behaviour, use a rowFixedReference key. The key's value and produced reference are the same as those for rowReference.