Creating Hierarchy View Definition Files

Hierarchy View definition files define the layout, format, and behavior of data in a Hierarchy. The Hierarchy View definition file is also referenced by the Show DataTable command used in a procedure file.

Hierarchy View definitions are stored as ASCII files and can be created and edited in any text editor. The recommended file extension for Hierarchy View definitions is .lvhvw.

Note: The data displayed in a Hierarchy is determined by the DataTable object specified in the Show DataTable command. For more information, see Defining DataTable objects and Show DataTable.

The following graphic shows a typical Hierarchy.

A Hierarchy, such as the one above, could be defined in a Hierarchy View definition similar to the following:

You can use the following functions in a Hierarchy View definition:

To view a sample Hierarchy View definition, see Sample documents for Tables.

Action (for Hierarchy Views)

Use this Hierarchy View function to add a toolbar button or a context menu with an associated action in a Hierarchy. For example, you can use actions to run a procedure, or open a new Table or Data Grid.

Syntax:

where:

• Text is the text to display in the toolbar. To display an image-only icon, omit this parameter and use two double quotation marks ( "" ). You must specify either Text or Image.
• Image is the path to the image to display as the toolbar or context menu icon. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. To display a text-only icon, omit this parameter and use two double quotation marks ( "" ). You must specify either Text or Image.

  Note: Longview recommends using 16 x 16 pixel images to optimize the appearance of your Table toolbar.

• Command is the Application Framework command to execute when a user clicks the toolbar icon or context menu item. To display a disabled icon, omit this parameter and use two double quotation marks ( "" ). For example, you can add a button that executes the Launch App command.
• Helptext is the tooltip text that appears when a user hovers over the toolbar icon. To omit tooltip text, use two double quotation marks ( "" ).
• Location is optional and defines the location of the action in the user interface. To add multiple locations, separate the parameters with a pipe ( | ). If you do not specify a location, the action item is added to the toolbar. Location can be one of the following:

  Parameter	Description
  ROWCONTEXT	Add the action as part of the context menu for a row. Note: Changes applied as the result of an action using the ROWCONTEXT location are row-specific only. Using this option updates the specified row and does not refresh or reorder the entire hierarchy.
  TOOLBAR	Adds the action to the Hierarchy toolbar.

• CondtionalExpression can be specified only if Location is also specified as ROWCONTEXT and must be enclosed in double quotation marks (""). This parameter is optional and is the expressions under which the context menu is available on the row header. You must enclose column tokens in escaped quotes (\"). ConditionalExpression uses the following syntax:

  {{Column, ColumnName}} Operation Condition

  where:

  • ColumnName is the name of the column to evaluate for the expression.
  • Operation is one of the following operators:

    Symbol	Meaning
    NE or !=	is not equal to
    EQ or ==	is exactly equal to
    GT or >	is greater than
    GE or >=	is greater than or equal to
    LT or <	is less than
    LE or <=	is less than or equal to

  • Condition is the condition to evaluate.

Note: If you require double quotation marks (“) in the parameters for the Action, precede them with a backslash.

Example:

ApplyUserPreferences

Use this Hierarchy View function to specify whether to display the user’s last view when it is first opened (the view is automatically saved when the user closes the Hierarchy) or to always display the default view as defined in the Hierarchy View definition.

If you set this function to FALSE, Reset will be disabled in the Layout menu. If you do not use this function, the Hierarchy displays the user’s last view when the user opens the Hierarchy.

Syntax:

where:

• TRUE — Opens the Hierarchy with the user's last view. The default is TRUE if this function is not used.
• FALSE — Opens the Hierarchy with the default view as defined in the Hierarchy View definition.

Example:

Columns (for Hierarchy Views)

Use this Hierarchy View function to specify the columns in the DataTable object that you want to display in the Hierarchy, in the order they are to be displayed. If you do not use this function, all columns in the DataTable object display in the Hierarchy.

Columns that are defined as NameColumn and ParentColumn must be included in this Columns function.

Note: For information on including columns in the DataTable object, see Columns (for DataTable definitions).

Caution: If you restrict the columns and do not specify the column that is designated as the primary key or any non-nullable columns, the Add, Edit, Delete, and Duplicate buttons will be disabled in the Hierarchy and users will not be able to add new rows.

Syntax:

where:

• ColumnName is the name of the DataTable column to display in the Hiearchy. Separate multiple column names with a comma. Columns display in the Hierarchy in the order specified in this function.

Example:

ColumnDecimals

Use this Hierarchy View function to specify the number of decimals for numeric values in specific column(s). This function overrides the DefaultDecimals function for the specified columns in the Hierarchy. The default number of decimal places for numeric values in a column is 2.

Syntax:

where:

• DecimalPlaces is the number of decimal places to use for numeric values in the specified columns.
• ColumnName1[|ColumnName2... |ColumnN] are the columns for which to specify the number of decimal places.

Example:

ColumnWidth

Use this Hierarchy View function to specify the column width for all or for particular columns in the Hierarchy.

Syntax:

where:

• Width is the width for the specified columns, in pixels. The minimum column width that will be displayed in the Hierarchy’s user interface is 20 pixels. The default column width ranges from 100 pixels to 200 pixels depending on the data type of a column.
• ColumnName1, ColumnName2... are the names of the DataTable column for which to set the width. If you do not specify at least one column, the width applies to all columns in the Hierarchy. To specify different widths for different columns, use multiple ColumnWidth statements.

Example:

DefaultDecimals

Use this Hierarchy View function to specify the default number of decimal places for numeric values in a Hierarchy. If you do not specify this function, the default number of decimal places for numeric values is 2.

If you want to override this value for a specific column, you can use the ColumnDecimals function.

Syntax:

where:

• DecimalPlaces is the default number of decimal places for numeric values in the Hierarchy.

Example:

DescriptionColumn

Use this Hierarchy View function to specify the column that stores description of items in the Hierarchy.

Syntax:

where:

• ColumnName is the name of the DataTable column where the description of items can be found in a Hierarchy.

Example:

DuplicateExclusions

Use this Hierarchy View function to specify the columns to exclude from duplication when a user duplicates a row. Columns specified as excluded from duplication appear blank and require user input. This function does not apply to columns with file, autointeger, autouser, or boolean data types.

Syntax:

where:

• ColumnName is a pipe-delimited list of the columns for which to exclude from duplication.

Example:

DynamicProcedure

Use this Hierarchy View function to specify a procedure to run when a user enters data manually or edits data using a control within a Hierarchy. You may also specify a procedure to run when a user invokes a standard row operation such as Add, Edit, Duplicate, Delete, Reset, and ResetAll.

Before the procedure runs, the following variables are populated and are available for use in the procedure:

• C_CELLVALUE
• C_CELLVALUEPRIOR
• C_COLUMNINDEX
• C_ROWINDEX
• C_DATATABLE
• C_CONTEXT

For more information on these variables, see "Working with context variables".

You can use the global variable LVG_TableRedraw to set the table redraw indicator after the procedure is run. For more information, see "Working with global variables".

Syntax:

where:

• Type can be one of the following:

  Field	Description
  CELL	Used to define the procedure to run when a user manually inputs data or edits data using a control
  ROW	Used to define the procedure to run when a user invokes one of the following standard row operations: Add, Edit, Duplicate, Delete, Reset.
  TABLE	Used to define the procedure to run when a user invokes the standard row operation ResetAll.

• Procedure is the procedure to run, enclosed in double quotation marks. The procedure must exist. You can specify multiple DynamicProcedure statements. Procedures will run in the order in which they appear in the Hierarchy View definition (.lvhvw) file.
• ColName1, ColName2... are the names of the DataTable column for which the dynamic procedure applies. This parameter allows you to optionally restrict which columns trigger the specified dynamic procedure. If you do not specify at least one column, the dynamic procedure applies to all columns in the Hierarchy.
• RunOnMultiPaste specifies whether the dynamic procedure will run when multiple values are pasted into the Data Table. By default, this option is FALSE.
  • TRUE The dynamic procedure will run when multiple values are pasted into the Data Table.
  • FALSE The dynamic procedure will not run when multiple values are pasted into the Data Table.

Example:

EditProcedure

Use this Hierarchy View function to add a custom procedure that the user can invoke to edit a cell. For example, you can invoke a form to prompt the user for input and calculate a value for the cell. To set the value back to the cell, you can use the SetDataTableCell function.

Note: EditProcedure can only be specified for columns of type STRING and NUMBER.

Syntax:

where:

• ColumnName is the name of the DataTable column for which the procedure will be run when the user clicks on the edit control.
• Procedure is the procedure to run, enclosed in double quotation marks. The procedure must exist.
• AllowManualInput specifies whether the user can type in the textbox. By default, this option is FALSE.
  • TRUE User can type in the textbox or click a button to invoke the procedure
  • FALSE User cannot type in the textbox and must click the button to invoke the procedure

Example:

Expand (for Hierarchy Views)

Use this Hierarchy View function to specify the initial expansion state of the items in the Hierarchy.

Syntax:

where:

• numLevels is the number of levels the root of a Hierarchy is to be expanded when it is opened. Default is 99 which means the root is fully expanded.

Example:

NameColumn

Use this Hierarchy View function to specify the column that stores name of items in the Hierarchy.

Syntax:

where:

• ColumnName is the name of the DataTable column where name of items can be found in a Hierarchy.

Example:

ParentColumn

Use this Hierarchy View function to specify the column that stores parent of items in the Hierarchy.

Syntax:

where:

• ColumnName is the name of the DataTable column where parent of items can be found in a Hierarchy.

Example:

Parentheses

Use this Hierarchy View function to specify whether or not negative numbers display with parentheses instead of a negative sign. If you do not use this function, the negative numbers in the Hierarchy are preceded by a negative sign.

Syntax:

where:

• ON displays negative numbers enclosed in parentheses.
• OFF displays negative numbers preceded by a negative sign ( - ).

Example:

Protect

Use this Hierarchy View function to protect the specified columns in the Hierarchy from input by users. If a user adds a new row, the Protect function still applies to the specified columns in the newly-created row.

If you want the entire hierarchy to be read-only, use the ReadOnly function.

Note: If you use the Protect function and the EnabledCriteria keyword in the SetColumn function for the same column, Protect takes priority.

Syntax:

where:

• ColumnName is the name of the column to protect from user input.

Example:

ReadOnly

Use this Hierarchy View function to make an entire Hierarchy read-only. This feature can be useful when you want to present data to users in a format in which they can sort and manipulate columns, but not add or submit data.

If you want only certain columns to be read-only, use the Protect function.

Syntax:

where:

• TRUE makes the Hierarchy read-only.
• FALSE makes the Hierarchy editable.

Example:

SetColumn (for Hierarchy Views)

Use this Hierarchy View function to specify display options for a column.

Syntax:

where:

• ColumnName is the name of the DataTable column to display in the Hierarchy. Separate multiple column names with a comma.
• My Description is the column header text to display. If you do not specify a description, the ColumnName displays.
• ConditionalExpression is optional and is the conditional expression under which a column is enabled or disabled.

Note: This option does not apply to virtual DataTables.

If the result of the expression is not zero, the column is enabled. If the result of the expression is zero, the column is disabled. Conditional expressions can include conditional operators, attributes, and column tokens. You must enclose column tokens in escaped quotes ( \" ).

Depending on the data type for the column, there are special considerations for the ConditionalExpression for EnabledCriteria.

Note: If you use the Protect function and the EnabledCriteria keyword in thefunction for the same column, Protect takes priority.

Example:

ShowToolbarButtons (for Hierarchy Views)

Use this Hierarchy View function to specify the buttons to show in the Hierarchy’s toolbar. If you do not specify this function, no buttons display in the Hierarchy’s toolbar.

Syntax:

where:

• ButtonName can be one or more of the following, separated by a pipe ( | ):

  Button name	Description
  Add	Displays a button that allows users to add a new row as a child to the current row to the Hierarchy.
  Edit	Display a button that allows users to edit certain fields of the current row in the Hierarchy.
  Delete	Displays a button that allows users to delete the current row from the Hierarchy.
  Duplicate	Displays a button that allows users to duplicate the current row in the Hierarchy.
  Reset	Displays a button that allows users to reset the current row in the Hierarchy that contain an error.
  ResetAll	Displays a button that allows users to reset all rows in the Hierarchy that contain an error.

All displays all of the above buttons in the Hierarchy.

Example:

SortOrderColumn

Use this Hierarchy View function to specify the column that stores sort order of items in the Hierarchy.

Syntax

where:

• ColumnName is the name of the DataTable column where sort order of items can be found in a Hierarchy.

Example:

SystemAction (for Hierarchy Views)

Use this Hierarchy View function to add a button with a predefined system action to the toolbar. For example, you can use system actions to include a toolbar button that allows users to export to Microsoft Excel or to add a button that allows users to specify whether they view symbol names, descriptions, or an attribute value in a Hierarchy.

Syntax:

where:

• Action is the system action to add to the toolbar and can be one of the following values:
  • Close, which adds a button that users can click to close the current Hierarchy.
  • ExportToExcel, which adds a button that allows users to export the current view to Microsoft Excel.
  • PrintPreview — Adds a button that allows users to open a Print Preview dialog.
  • Users’ printing preferences are saved when the Hierarchy is closed.
  • ViewLayout, which adds a button with drop-down options that allow the user to reload the most recently saved view layout (the layout is saved when the Hierarchy is closed) or reset the view to its original layout (as specified by the developer that created the Hierarchy).
• Text is the text to display on the button. If you want to omit this parameter and display the image only, use two double quotation marks ( "" ). The following table lists the default text.

  Keyword	Default text
  Close	Close
  ExportToExcel	Export to Excel
  PrintPreview	Print Preview
  ViewLayout	Layout

• Image is the image to display on the button. This option does not apply to the Close action. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. If you want to omit this parameter, the system uses a default icon. To omit this parameter, use two double quotation marks ( "" ). The following table indicates the default images.

  Keyword	Default image
  ExportToExcel
  PrintPreview
  ViewLayout

• Helptext is the tooltip text that appears when a user hovers over the button. There is no default for this parameter.

Example:

ThousandsSeparator

Use this Hierarchy View function to specify whether numeric values display with a locale-specific thousands separator. For example, if your location setting is “United States”, numeric values display with commas ( , ) as the thousands separator.

Syntax:

where:

• ON displays a locale-specific thousands separator based on the operating system setting.
• OFF does not display a thousands separator. If this function is not specified, OFF is used.

Example:

ValuesPane

Use this Hierarchy View function to present the columns of the active row in a pane where the columns are transposed (presented in rows). The values pane is ideal for Hierarchies containing numerous columns which would require users to scroll horizontally in order to enter row details.

If you do not use this function, the Hierarchy displays with the values pane feature disabled. If the values pane feature is ON for the Hierarchy, but the pane is not present, double-click the row selector to open the values pane.

Syntax:

where:

• ON will enable the values pane feature.
• OFF will disable the values pane feature.
• MyTitle is the text to display in the pane's title bar. The default title is "Values Pane".
• HideOnLoad define whether the values pane is visible when the Hierarchy is initially displayed. This option can have one of the following values:

  Value	Description
  TRUE	Opens the Hierarchy with the values pane in view.
  FALSE	The Hierarchy is opened without the values pane in view. This is the default value. The user must double-click on the row selector to open the values pane if required.

Example: