# 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 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.

# 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 Per Row Help

Determining the Selected Row

Other topics in this document

Flexibility on Data Types

About Window Sizing

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" : [
    	...
      ]
    }

Back to Table of Contents

# Context Menu Item Names and Visibility

These items control the names of the 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" : [
    	...
      ]
    }

Back to Table of Contents

# 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"
        }
      ]
    }

Back to Table of Contents

# 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 the state column is hidden by stateHidden 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
        }
      ]
    }

Back to Table of Contents

# 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
        }
      ]
    }

Back to Table of Contents

# 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
        }
      ]
    }

Back to Table of Contents

# 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 also be treated as a separator.
bold
  The text displayed in the Name column will be bold.

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

Back to Table of Contents

# 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.

enabled
  An array of tests to determine if the row should be enabled or disabled. Each item in the array must be an object and can contain the following items:
  link
    This item must be present and its value must be a string for which an anchor exists in a row. This is a reference to the row being tested.
  function
    A string object describing the test function. All function names are case insensitive.

    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.

  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.
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"
        }
      ]
    }

Back to Table of Contents

# 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 values 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.

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

Back to Table of Contents

# 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 object are reversed with the exception of the Name column values. ie. the names do not move only the State and Value column values.

    {
      "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"
        }
      ]
    }

Back to Table of Contents

# 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 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.

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:
    name
      This key is mandatory and describes the the menu item's description. If missing, the entire menu will not be displayed.
    hidden
      A boolean value. When true, the menu item is hidden. Note that hiding a menu item does not affect indexes when isPopupValue has a value of 1.
    disabled
      A boolean value. When true, the menu item is disabled (dim and not selectable).
    others
      Ignored
  - any other item type will cause the entire menu not to be displayed.
popupAppends
  This item is only used if both 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.
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
        }
      ]
    }

Back to Table of Contents

# 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.
getPathPrompt
  An optional String item which is used as a prompt in the displayed get file/folder panel.

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"
        }
      ]
    }

Back to Table of Contents

# Providing Per Row Help

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.

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.

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"
        }
      ]
    }

Back to Table of Contents

# Determining the Selected Row

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.

Back to Table of Contents

# 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.

Back to Table of Contents

# 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 width x height,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.

Back to Table of Contents