Harness and Section forms - Adding a Table layout

A Table layout, formerly referred to as a Grid layout, presents data in aligned columns and rows, as a spreadsheet. Tables can display expansive data sets using progressive paging.

Using table layouts, users can view (and in certain cases edit) values of a data page, property, or report definition, in a spreadsheet format. The table is created dynamically, and will contain as many rows as needed to display the requested data. The layout can use a custom skin. You can also configure the layout to be editable and localizable.

You can specify that the table be read-only or editable, in one of the following ways:

All the editable fields are displayed as editable, as in a spreadsheet.
The editable fields in a row become editable when a user clicks on that row.
A modal dialog is displayed with the editable fields for a row when the user clicks on that row.

When a table uses a data page or report definition that accepts parameters and the parameter value uses a property reference, the table automatically refreshes whenever the property value changes. Depending on the parameters that you specify, users may be able to add or delete rows, reorder rows, and apply actions to rows by clicking action buttons.

If the source for the table is a report definition and the Header display field on the Report Definition Report Viewer tab is set to Hide column headings, the column headings are not displayed in the table.

The Table layout consists of the following areas:

Layout area – The framework that contains the action and repeating areas. You define the header format, header type, and overall width.
Action areas – The top and bottom areas in which you can place buttons or other controls linked to actions, such as Add Item or Delete.
Repeating area – Between the action areas, the system displays information dynamically created from the data source. The first row in this area holds column headers representing the data source fields. The second row repeats as needed to display the requested data. You do not manually add or delete rows here.
You can add or remove columns, specify which fields of the data source to include in which columns, or configure the data's appearance. Insert radio buttons or check box controls in fields to simplify data entry. You can also place action buttons in the repeat row to provide quick access to actions that do not require further user input, such as Flag for Review.

> Adding and configuring a Table layout

Open a section.
Click the Layout control group and drag the Table control to the section.
Click the View properties icon in the Table layout header.
In the Properties panel, define the table using the following tabs:
You can also set properties for columns, rows, and action areas, as described below.

> Column properties

Select a column in the repeating area and open the Column Properties panel.

Width – Enter the width of this column in pixels. Alternatively, you can adjust the column width directly by dragging the cell border.
Inline style – Optional: You can use this field to define an inline style by entering cascading style sheet (CSS) code.
Filtering – This option is displayed if the Allow filtering (Additional settings on column) check box is selected on the Operations tab of the Layout Properties panel. Select one of the following settings:
- Auto – Displays a check box for each unique value and the search or date range fields, depending on the column data type.
- List Only – Displays a check box for each unique value and the search or date range fields, depending on the column data type.
- Range/Search – Displays only the search or date range fields, depending on the column data type. Use this option to enable search or date ranges on columns in which the value of each row is unique, such as a description column.
- None – No filtering is available on the column.
Filter by – If you set the Filtering option to a setting other than None, use this option to specify the filtering basis:
- Value – Filters the column based on the value of the cell content.
- Format – Select a property reference.
Enable sorting – By default, columns can be sorted. Clear this check box to disable sorting on this column.
Importance – Select the importance level for the column to determine which columns display first when a responsive breakpoint is reached at run time. Only one column can have primary importance; this column appears before all secondary columns. At a second responsive breakpoint, the remaining columns are converted to a list, with the primary column displayed in the heading. Any unmarked columns are treated with secondary importance.
Categorize by this column – This check box is displayed if the Categorize grid rows (Additional settings on column) option is selected on the Operations tab of the Layout Properties panel. Select this check box if you want to categorize table rows based on the column.
Category order – Specify the sorting order as Ascending or Descending.

> Row properties

Select a row in the repeating area and open the Row Properties panel to specify the following settings:

Height – Enter the height of the row, in pixels. Alternatively, you can adjust the row height directly by dragging the cell border.
Inline style – You can use this field to define an inline style by entering cascading style sheet (CSS) code.
Make header – Select this check box to display cell values in the row with the same style used by the column heading.

> Cell properties

Select a cell from the second row in the repeating area and click the View properties icon to open the Cell Properties panel.

Property – Select a Single Value property. Typically, this is from the data source's embedded page property. If the source is a report definition, the list contains Column Name properties defined in the rule. Property names indicate whether joins are part of the report.
Default value – Optional: Specify a default value to speed data entry.
Visibility – Select one of the following settings to determine the cell's visibility:
- Always: Always visible.
- Condition (expression): The region is visible under the specified condition. In the field that displays, select a condition or click the Gear icon to open the Condition Builder . You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
- Condition (when): Tthe region is visible under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.
Disable – Specify a condition for disabling the text input:
- Never – Never disabled
- Always – Always disabled
- Condition (expression) – The text input is disabled under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression by using the && and || operators.
- Condition (when) – The text input is disabled under the specified condition. In the field that is displayed, select a when rule. Click the Open icon to create a when condition or review an existing when condition.
Show when active – Select this check box to have the icon of a control display in the row only when the user selects it.
Required – Select this check box to require the user to enter a non-blank value for the corresponding property at run time.
Control – Select a control to format the value in this cell. If left blank, the property uses the control (if any) in the Control field on the property form's General tab. Many controls in the Basic and Advanced groups are associated with default controls based on the property type. When you drag and drop a control into the cell, the rule appears in this field.
Behavior – Click the Gear icon beside this field to display the Client Event Editor, where you can specify formatting conditions and actions for this field. This field is not displayed if the value in the Control field contains an Action mode control such as pxButton.

The delete icon appears at the right of the repeating row in this area, to indicate how and where it appears at run time. Do not use it to attempt to remove cells or rows while editing the layout.

> Advanced Presentation Options

Cell width – Specify the width of the column in pixels. Provides the same control as the Width setting in the Column properties panel.
Cell height – Specify the height of the cell in pixels. Provides the same control as the Height setting in the Row properties panel.

Instead of creating a new custom format in the skin, you can adjust elements in a cell by applying Cascading Style Sheet (CSS) helper classes. For example, you can use a CSS helper class to center an element in a cell or to double the standard right margin for the element.

Cell read-write classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-write mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.
Cell read-only classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-only mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.
Inline style (not for production use) – You can use this field to define an inline style by entering CSS code. However, entering an inline style results in a guardrail warning. For maintainability and reuse, the recommended approach is to use read-write or read-only classes.

For more information, see CSS helper classes.

> Action area properties

The Table layout has two action areas, one at the top and one at the bottom of the display. You can use one or both. Select Action Top or Action Bottom and then display the Properties panel. Select a column header and open its properties panel.

Visible When – Optional: To control the visibility of the area, enter or select one of the following:
- The When Name key part of a when condition rule. Click the Open icon to review or create the rule.
- A simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
  
  As a best practice, use the Condition Builder to edit this field.
Run on Client? – This option is displayed when you enter a simple expression in the Visible When field. Select to cause dynamic execution of the condition each time the value of a property stated in the condition changes.
ID – Optional: Provide an identifier for this table, for JavaScript use. Start with a letter, use no spaces, and include only alphanumeric characters, hyphens, or underscores.

> Column properties

Select a column in one of the action areas and open its properties panel.

Width – Specify the column width in pixels.

Clear the Set width during execution check box (unlabeled) next to the width field to allow the browser at run time to determine the width of this column based on the size of the column contents and the size of other columns. The width may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no WIDTH= attribute.) The Width value is used as you view the rule form, but not at run time.

For example, clear this check box if the cell is to contain a section that may be wide in some situations and narrow in others.

Select (default) the Set width during execution check box to force the Width value to be used by the browser at run time, even when data values in this column or in other columns would otherwise cause the browser to present a wider or narrower column. If checked, data values may sometimes wrap or appear truncated.
Inline style – Optional: You can use this field to define an inline style by entering cascading style sheet (CSS) code.

> Row properties

Select the row in the top or bottom action area and open its properties panel.

Height – Enter a positive number for the cell height, in pixels.

Clear the Set height during execution check box (unlabeled) to allow the browser at run time to determine the height of this row based on the size of the row contents and the size of other rows. The height may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no HEIGHT= attribute.) The Height value is used as you update the rule, but not at run time.

For example, clear this check box if the cell is to contain a section that may be tall in some situations and short in others.

Select the Set height during execution check box to force the Height value to be used by the browser at run time, even when data values in this column or in other cells would otherwise cause the browser to present a taller or shorter column.
Inline style – Optional: You can use this field to define an inline style by entering cascading style sheet (CSS) code.
Make Header – Select this check box to display cell values in the row with the same style used by the column heading.

> Action cell properties

Add a control, property, or other section that is appropriate to the display and function of your data. Configure the element's properties by selecting it and then displaying the properties panel.

> Tab Group properties panel

When you select a Header Style of Tabbed, the layout appears in a Tab Group wireframe. Select it to make it active and click the Gear icon in the header to open the Tab Group Properties panel. Your settings apply to all the tabs in the group.

Use the Format field to specify the tab style and complete the General tab. There are no settings on the Advanced tab.

Format – Select the style for the tabs in the group.
Tab Position – Specify the placement of the tabs at run time. If you select Left or Right, use the corresponding Tab Orientation option to specify the horizontal or vertical orientation of the tabs.
Tab Orientation – If you selected a left or right tab position, use this option to display tabs horizontally or vertically. If you select vertical orientation, the tab title is rotated based on the tab position, left or right.
Stretch Tabs – Select this option to stretch the tabs horizontally or vertically.

> UI Gallery

The UI Gallery landing page contains a working example of this element. To display the gallery, click Designer Studio > User Interface > Gallery > UI elements.