Creating Table View Definition Files

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

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

Note: The data displayed in a Table 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 Table.

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

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

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

Action (for Table Views)

Use this function to add a toolbar button or a context menu with an associated action in a Table

For example, you can use actions to run a procedure, open a new Table or Data Grid, or run a model.

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 table.
  TOOLBAR	Adds the action to the Table 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:

AllowMultiPaste

Use this Table View function to specify whether a user can paste multiple cell values into contiguous cells within the Data Table.

If you set this function to OFF, users will be unable to paste multiple values into the Data Tables. You may wish to set this function to OFF in cases where you want to prevent this behavior because there are dynamic procedures defined that will not work well when modifying several values at once. For example, dynamic procedures that invoke user interfaces (messages, forms) or that run long calculations.

Note: Regardless of the AllowMultiPaste setting, there are some restrictions on when pasting is allowed. For example, users cannot paste into File type or Protected columns even if AllowMultiPaste is set to ON.

Syntax:

where:

• ON — Allows the end-user to paste multiple values into contiguous cells within the Data Table at runtime.
• OFF — Prevents the end-user from pasting multiple values into contiguous cells within the Data Table at runtime. The default is OFF if this function is not used.

Example:

ApplyUserPreferences

Use this Table 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 Table) or to always display the default view as defined in the Table 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 Table displays the user’s last view when the user opens the Table.

Note: Specifying a SortOrder when applying user preferences may cause unpredictable sorting. If you specify a SortOrder, Longview recommends that you set ApplyUserPreferences to FALSE. If you do not specify a SortOrder and ApplyUserPreferences is FALSE, the columns are sorted based on the order in which they are returned from the database.

Syntax:

where:

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

Example:

ColorPicker

Use this Table View function to add a color picker control that the user can invoke to edit a cell. The return value will be the HEX color code for the selected color.

Note: ColorPicker can only be specified for columns of type STRING.

Syntax:

where:

• ColumnName is the name of the DataTable column that will contain the color picker control.
• ShowText specifies whether the HEX color code is displayed with the color indicator. By default, this option is TRUE.
  • TRUE displays the HEX color code beside the color indicator. This is the default if this option is not specified.
  • FALSE does not display the HEX color code beside the color indicator.

Example:

Example:

Columns (for Table Views)

Use this Table View function to specify the columns in the DataTable object that you want to display in the Table, along with the order in which they display. If you do not use this function, all columns in the DataTable object display in the Table.

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, Delete, and Duplicate buttons will be disabled in the Table and users will not be able to add new rows.

Syntax:

where:

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

Example:

ColumnDecimals

Use this 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 Table. 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 function to specify the column width for all or for particular columns in the Table.

Syntax:

where:

• Width is the width for the specified columns, in pixels. The minimum column width that will be displayed in the Table’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 Table. To specify different widths for different columns, use multiple ColumnWidth statements.

Example:

DefaultDecimals

Use this function to specify the default number of decimal places for numeric values in a Table. 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 Table.

Example:

DuplicateExclusions

Use this 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 function to specify a procedure to run when a user enters data manually or edits data using a control within a Table. You may also specify a procedure to run when a user invokes a standard row operation such as Add, 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, 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 Table View definition (.lvtvw) 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 Table.
• 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 DataTable 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:

LeftTitleText

Use this function to include additional information in the top left section of your Table. Left title text appears just below the toolbar(s) of the Table. You can include attribute tokens and string variables in the text.

Syntax:

where:

• Text is the text to include, enclosed in double quotation marks. To include text on multiple lines, use \n as the line break character.

Note: If you use variables in Text, variables are updated with toolbar button actions and the left title text is refreshed.

Example:

PageSize

Use this DataTable function to render the table in a paged format that displays a specified number of rows per page. Users use navigation controls in the table to traverse the pages. The use of the PageSize function is recommended for tables when there are a large number of rows to display. By rendering the table into separate pages, the UI will perform optimally.

Because PageSize displays a subset of the total rowset, the following functions have either modified behavior or do not work in conjunction with the PageSize keyword:

• The SummaryRows totals applies to the rowset in the current view only.
• The secondary toolbar actions Add, Duplicate, and Delete are disabled when using the PageSize keyword.
• The secondary toolbar action Reset All applies to the rowset in the current view only.
• The Filter toolbar action will filter according to the current filter settings. It is possible that as a user pages through the table, they may encounter a page with all records filtered. In order to reset the filter settings, use the Remove Filter system action and then invoke the Filter system action again.
• The toolbar action Save Layout will save the layout but not the current view displayed.
• The Print toolbar action will only print the rowset in the current view only.
• The Export to Excel toolbar action will only export the rowset in the current view only.
• After the Download Application Framework command is invoked, the application will redraw with the first page in view.
• After the Import Application Framework command is invoked, the application will redraw with the first page in view.
• DynamicProcedure and custom procedures in toolbar actions are allowed but the end-user will need to navigate to see results on other pages.
• As a Longview App Designer, you may need to set the LVG_TableRedraw flag appropriately in order for the end-user to view accurate results.

Syntax:

where:

• numRows specifies the number of rows to display in each page view.

Example:

Parentheses

Use this 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 Table 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 Table View function to protect the specified columns in the Table 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 table 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 Table column to protect from user input.

Example:

ReadOnly

Use this function to make an entire Table 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 Table read-only.
• FALSE makes the Table editable.

Example:

SetColumn (for Table Views)

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

Syntax:

where:

• ColumnName is the name of the DataTable column to display in the Table. 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 the SetColumn function for the same column, Protect takes priority.

Example:

ShowToolbarButtons

Use this Table View function to specify the buttons to show in the Table’s toolbar. If you do not specify this function, no buttons display in the Table’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 to the Table.
  Delete	Displays a button that allows users to delete the current row from the Table.
  Duplicate	Displays a button that allows users to duplicate the current row in the Table.
  Reset	Displays a button that allows users to reset the current row in the Table that contain an error.
  ResetAll	Displays a button that allows users to reset all rows in the Table that contain an error.

• All displays all of the above buttons in the Table.

Example:

SortOrder

Use this Table View function to sort items in one or more Table columns in ascending or descending order.

Note: Specifying a SortOrder when applying user preferences may cause unpredictable sorting. If you specify a SortOrder, Longview recommends that you set ApplyUserPreferences to FALSE. If you do not specify a SortOrder and ApplyUserPreferences is FALSE, the columns are sorted based on the order in which they are returned from the database.

Syntax:

where:

• ColumnName is the name of the column to sort.
• ASC sorts items in the column in ascending order. This is the default sort order.
• DESC sorts items in the column in descending order.

Example:

SummaryRow

Use this function to add a summary row to a Table. Summary rows can display information such as subtotals and grand totals.

Note: You can allow users to toggle the display of subtotal and grand total rows by including the Options System Action. For more information, see SystemAction (for Table Views).

Syntax:

where:

• Type is one of the following:
  • SUBTOTAL — Adds a row that calculates and displays the subtotal sum of all records for each of the specified columns grouped by the Group By functionality. If the user does not group records, the summary row appears below all records. This type applies only to columns with the NUMBER or BOOLEAN data types. For BOOLEAN data types, the summary is the count of TRUE values.
  • GRANDTOTAL — Adds a row below all records that calculates and displays the sum of all records for each of the specified columns. This type applies only to columns with the NUMBER or BOOLEAN data types. For BOOLEAN data types, the summary is the count of TRUE values.

Note: To include a label for the each summary row, use the SummaryRowLabel function.

Example:

SummaryRowLabel

Use this function to include a label in the left-most column for a summary row. If you include more than one SummaryRowLabel function per type, the last one displays in the Table as the summary row label. You must include the SummaryRow function for a summary row to display in the Table.

Syntax:

where:

• Type is one of the following:
  • SUBTOTAL — includes a label for the subtotal row as specified by the SummaryRow function.
  • GRANDTOTAL — includes a label for the grandtotal row, as specified by the SummaryRow function.
• Label is the label for the row, enclosed in double quotation marks.

Note: If the left-most column displayed is being summed, the label does not display.

Example:

SystemAction (for Table Views)

Use this Table 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 Table.

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 Table.
  • ExportToExcel, which adds a button that allows users to export the current view to Microsoft Excel.
  • Filter, which adds buttons that allows users to filter the current view based on criteria for each column and to remove all filters.
  • GroupBy, which adds a list that allows users to group the current view by the selected column.
  • Options — Adds a button that allows users to access the following options when the corresponding SummaryRow function is also included in the table view document:

    Option	Description
    Show Group Subtotals toggle	Allows users to show or hide group subtotal rows if defined by the SummaryRow function. For more information, see SummaryRow.
    Show Grand Total toggle	Allows users to show or hide grand total rows if defined by the SummaryRow function. For more information, see SummaryRow.

    Note: If you use the Options SystemAction without including the SummaryRows function in your Table View document, the Options button does not display to the user.

  • PrintPreview — Adds a button that allows users to open a Print Preview dialog.

    Note: Users’ printing preferences are saved when the Table 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 Table is closed) or reset the view to its original layout (as specified by the developer that created the Table).

• Text is the text to display on the button. This option does not apply to the Filter and GroupBy actions. 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
  Options	Options
  PrintPreview	Print Preview
  ViewLayout	Layout

• Image is the image to display on the button. This option does not apply to the GroupBy, Filter, or Close actions. 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
  Options
  PrintPreview
  ViewLayout

• Helptext is the tooltip text that appears when a user hovers over the button. This option does not apply for the GroupBy action. There is no default for this parameter.

Example:

ThousandsSeparator

Use this 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 Table 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 Tables containing numerous columns which would require users to scroll horizontally in order to enter row details.

If you do not use this function, the Table displays with the values pane feature disabled. If the values pane feature is ON for the Table, 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 Table is initially displayed. This option can have one of the following values:

  Value	Description
  TRUE	Opens the Table with the values pane in view.
  FALSE	The Table 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:

VisibleRows

Use this function to specify the maximum number of DataTable rows to display in the Table. For example, you can use this function, with the SortOrder function, to create a Top 10 report.

Syntax:

where:

• NumOfRows is the maximum number of DataTable rows to display in the Table.

Example: