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:
The table has a context menu which by default displays the following items:
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 preset and define at least one row. When testing for rows items and an item does not exists, columns will be searched for the same item. This means that the columns object can set defaults for rows.
The following sections describe the object items (keys), used in columns and rows objects to configure the panel.
Context Menu Item Names and Visibility
Disabling the State Column's Checkbox
Setting the State Column's Behaviour
Controlling the Display of Rows
Disabling Rows and the Value Column
Easing the Acquisition of File and Folder Paths
Other topics in this document
Additional information
These items control the names of the column headers and are only read from the columns object.
{
"columns" : {
"nameTitle" : "Title",
"stateTitle" : "State",
"valueTitle" : "Value"
},
"rows" : [
...
]
}These items control the names of the the menu items and are only read from the columns object.
{
"columns" : {
"menuMixed" : "Set All to Mixed",
"menuOff" : "Set All to Off",
"menuOn" : "Set All to On"
},
"rows" : [
...
]
}The following items are used to preset values for each cell in the table and will contain modifications.
{
"rows" : [
{
"name" : "Sample row 1",
"state" : true,
"value" : "Sample value 1"
},
{
"name" : "Sample row 2",
"state" : false,
"value" : "Sample value 2"
}
]
}The following items are used to hide columns.
| 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 |
{
"columns" : {
"valueHidden" : true
},
"rows" : [
{
"name" : "No checkbox displayed",
"state" : true,
"stateHidden" : 1
},
{
"name" : "Checkbox Displayed",
"state" : false
}
]
}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.
| 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
}
]
}These items control how the State column's checkbox can display and how a row's checkbox is affected by context menu items.
{
"columns" : {
"stateMixed" : true
},
"rows" : [
{
"name" : "State is mixed and ignore the context menu",
"state" : -1,
"stateIgnoreMenu" : true
}
]
}These items are only processed in the rows object.
{
"rows" : [
{
"bold" : true,
"name" : "This is a header row",
"stateHidden" : 1,
"valueRO" : 1
},
{
"separator" : true
},
{
"name" : "row 1"
},
{
"name" : "row 2"
}
]
}Entire rows can be disabled and the Value column can be treated as read only.
| 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. |
| Function | Description |
|---|---|
| On | Tests if the State column of the referenced row is checked. |
| Not On | Tests if the State column of the referenced row is not checked. |
| Off | Tests if the State column of the referenced row is not checked or mixed. |
| Not Off | Tests if the State column of the referenced row is checked or mixed. |
| Mixed | Tests if the State column of the referenced row is mixed. |
| Not Off | Tests if the State column of the referenced row 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. |
{
"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"
}
]
}You can perform validation of items in the Value column. Validating is performed when closing the panel via a Continue button. If validation values an error message is displayed and the panel is not closed.
{
"rows" : [
{
"name" : "Cannot exit when the value column is empty",
"validate" : "E"
}
]
}You can enable the dragging of rows.
{
"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"
}
]
}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 a menu is editable, the icon at the right of the Value column will be a down triangle. When a menu is not editable, the icon at the right of the Value column will be an up-down triangle. When a menu is not editable, clicking anywhere in the cell be display the menu. When editable the icon must be clicked to display the menu.
| 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. |
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
}
]
}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.
Note that getFilePath 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"
}
]
}The Prompt from Container's panel can display a help button in the right hand corner. How the help is displayed depends on the Prompt Help Button URL named variable which is described in Configuring Buttons on Prompt Statements. The help can be a resource action's online help or a popup help panel. In order for the per row help to be activated a valid value must be placed in the the Prompt Help Button URL named variable. This defines the help to be displayed if no row is selected or no per row help is specified. At runtime if the help button is clicked while holding down the Option key, the supplied default help will be displayed.
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.
Action:
1: Set named variable 'row 2 help' to "<m>help for row 2"
2: Set named variable 'Prompt Help Button URL' to "<m>Generic help"
3: Create container 'obj' from JSON text '{ .... }'
4: Prompt from Container 'obj'
JSON defined on line 3
{
"rows" : [
{
"help" : "<m>Sample inline per row help",
"name" : "Row with per row help"
},
{
"help" : "\<row 2 help>",
"name" : "Row with per row help in named variable"
},
{
"name" : "Row without per row help"
}
]
}If you want to present a list of items and wish 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.
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 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.
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.
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.