This topic introduces the Logi Data Table, which is one of the primary structures for displaying report data. It consists of a grid of rows and columns, which displays data (usually) in a row and column arrangement. These "tabular" displays in a report look good and are easy to work with.
The fastest and easiest way to create a data table is to use the Data Table Wizard in Logi Studio. Here's how:
- As shown above, in a definition in Logi Studio, select an element and either click the Data Table item in the main menu's Wizards tab, or right-click the element and select Element Wizards, and then select Add a Data Table from the secondary menu.
- A series of dialog boxes, shown above, will be displayed. These all relate to the retrieval of the data. Make appropriate selections for your application and click Next to move to the next dialog box.
- The wizard will display a model data table in a dialog box, where you can adjust it, if desired. If the table is just as you want it, click Next to exit the wizard. If not, you can continue the customization, using the features identified above:
1- Click these buttons to add calculated or "Formula" columns, and to Filter the data based on column values;
2- Click the Gear icon to display the table's Configuration Panel (discussed below);
3- Hover your cursor over a table column header and use the drag handles that appear to change the column width or rearrange column order. Click the header text to see a configuration menu for that column (discussed below);
4- Select the maximum number of rows to be retrieved.
Table Configuration Panel
If you click the Gear icon, the table's Configuration Panel will be displayed:
As shown above, the Configuration Panel includes these controls:
- Columns - Select the columns that will be displayed (displayed vs. retrieved in the data).
- Sort - Specify the sort order of the data after it's been retrieved.
- Group - Specify the grouping of the data after it's been retrieved.
- Aggregate - Add new columns for aggregations including Sum, Average, Standard Deviation, Count, Distinct Count, Minimum, and Maximum.
- Paging - Specify whether the table will use paging and, if so, how many rows will be shown per page.
Click the Gear icon again to hide the Configuration Panel.
Column Configuration Menu
If you click a column's header text, a pop-up Configuration Menu for that column will be displayed:
Options on that menu allow you to do some of the same thing you can do in the Configuration Panel but other options, like Format, work specifically on the selected column. Changes in the displayed table will take affect immediately.
When you're done, the Wizard will add all of the elements for the table to your definition. The wizard automatically gives each column interactive sorting capabilities.
Only the elements for the table itself will be added, not any of the wizard's configuration controls you've just worked with.
If you already have your data table and datalayer elements added and configured, another wizard - "Add Data Columns" - is available when you select the Data Table element and is really useful if you don't have a list of table columns handy.
Data tables are dynamic, data-driven reporting components. Unlike basic HTML tables built using the Rows, Row, and Column Cell elements, data tables are designed column-by-column rather than row-by-row.
As shown above, every data table must have the following components:
- A Data Table element
- One or more DataLayer elements to retrieve and cache the data, possibly with child Filter elements
- One or more Data Table Column elements to display each column
- One or more report content elements, such as a Label, to present the data
This column-wise approach can be confusing. Just remember that, at runtime, everyrecord in the datalayer will be iterated and rows for all of the data will be displayed in the table. Developers create and configure each column, while the number of rows is entirely dependent on the data.
The Data Table Column element, for example, is configured to provide the column header text, column width (if not automatically determined), and so forth.
The actual data values in the datalayer are accessed using tokens, such as @Data.CategoryID~, where the second part of the token is the column name in the datalayer. This case-sensitive token can be used in Label element Captions, for example, to display the data. For more information about tokens, see Token Reference.
Note: the table shown above has had style applied to it to specify its fonts, borders, and background colors. An easy way to quickly style a data table is to apply a Theme to your report definition. For more information, see Themes.
The most common way to design data tables is to have a Data Table Column element for each column in the datalayer, as shown above. This works well when you have many records that you want to show in a table.
The order of the columns in the displayed data table is governed by the order of the Data Table Column elements in the definition. The top-most of these elements in the definition will be the left-most column in the displayed data table. Developers are free to rearrange the order of columns by selecting a Data Table Column element in Logi Studio and dragging it, or by using the Up/Down Arrow buttons in the toolbar. This is particularly useful if a wizard has been used to create the data table and a different column arrangement is desired.
The one-to-one correspondence of data columns to Data Table Columns elements discussed above is not required and developers have complete freedom over the way data is presented in a report. Suppose, for example, that you don't want the typical tabular format.
Suppose instead you want to stack the data in a kind of form when you display it. This is easy to do, as shown above. The data is presented in a form-like manner by using just one Data Table Column element and placing multiple Label elements within it. Each Label element displays the data from a different data column in the datalayer. There's no limit on the number of elements you can place beneath a single Data Table Column element and you can, in fact, even place HTML tables and charts there!
Important Scope Limitation The scope of the data in a datalayer is limited to the Data Table element that contains it and its child elements. So, looking at the example above, the token @Data.CategoryID~ is valid in all elements beneath the data table dtCategories, but will be empty if you attempt to use it elsewhere, such as in the Report Header element.
Tip: The only exception to this scope limitation is the Local Data element. This element works with a datalayer which retrieves just one result row but its data is available, using the @Local.<columnName>~ token, anywhere in the report definition.
You can create a data table in Studio manually by adding the appropriate elements to a report definition.
To do this, simply add the necessary elements to your definition in Studio. After you add your first Data Table Column and its child elements (Label, Sort, etc.), you can speed things up by copying and pasting it into the element tree as many times as necessary, then going back and configuring the individual elements. Copying the Data Table Column element will also copy all of its child elements, too.
In these circumstances, the issue of spelling becomes more important. @Data tokens are case-sensitive and column names must be spelled accurately. To ensure that you know exactly how column names are spelled, you may care to turn on debugging and view the actual data in the datalayer. For mor information about debugging, see Debug Reports.
Data Table Attributes
The Data Table element includes the following attributes. Note that Themes automatically set a number of these attributes "behind-the-scenes".
|Accessible Headers||Specifies whether or not to set the HTML "Headers" attribute, which can improve the accessibility and readability of tables. Default value: False.|
|Accessible Summary||Specifies whether or not to create a "table content summary", which has no visual effect but is used by screen readers to improve accessibility. Default value: False.|
|Ajax Paging and Sorting||Enables AJAX-style paging and sorting. When the user moves to another page of table data, or sorts a column, only the table portion of the page is updated. This method prevents the web page from flickering or losing its scroll position. This alters the behavior of the browser's "Back" button because the page history is updated with AJAX Paging. Default value: False|
|Alternate Row Class||Specifies a style class to be used for every other row of the table, making it easier to read across the columns in single row. Themes include a class called ThemeAlternatingRow which you can assign, if desired.|
|Border||Specifies, in pixels, the width of a border, if any, to be displayed around the table. A value of 1 displays a thin border.|
|Caption||Specifies the text of a caption, or "title", that will appear above the table. Leave this blank to suppress it.|
|Caption Class||Specifies a style class to be applied to the caption text entered in the previous attribute.|
|Cell Spacing||Specifies the width, in pixels, of the space between table cells, if any. Default: 0.|
|Class||Specifies a style class to be applied to the table as a whole.|
|Column Header Class||Specifies a style class to be applied to the column headers.|
|Draggable Columns||Specifies if the user can reposition columns by dragging the column header side-to-side. When enabled, any changed column positions are remembered for the table for the current session. Draggable Columns may not be used when there are custom header rows in use with columns that span multiple columns. Default: False|
|Hide When Zero Rows||Specifies it the Data Table is to be hidden when the datalayer returns zero rows. Default: False|
|Keep Scroll Position||When enabled, causes the browser's horizontal and vertical scroll positions to be retained when the current report is redisplayed without first going to another report. Use this to refresh the current report while avoiding resetting the scroll position to the top. Default: False|
|Layout||Specifies if the table layout should be automatically determined by all the data (Auto) or just the first row of data (Fixed). If Fixed is specified, the column layout is determined based on the width of the values in the first data row, instead of adjusting the column widths by examining data in every row. This can help with formatting issues, and can also significantly improve large table performance. Default: Auto|
|Remember Sort||Specifies whether or not to retain the user's sort selection. When True, and the user sorts the data table on a particular column, the report will be redisplayed with the same sort order the next time the report is displayed. Sort selections are retained only for the user's current session. Default: False|
|Resizable Columns||When enabled, a small icon appears on the right edge of the column header when the mouse hovers over it and the user can resize columns at runtime by dragging the icon right or left to a different width. The updated column width are remembered for the table for the duration of the current session. You may not use Resizable Columns when there are custom header rows in use with columns that span multiple columns. Default: False|
|Row Class||Specifies a style class to be applied to the table rows. This value can be an @Data token, so the class can be applied dynamically based on the data.|
|Security Right ID||When specified, access to this element can be controlled with Logi Security. Specify the ID of a Right defined in the application's _Settings Security element. Only users with matching rights will be able to see the element.|
|Sort Arrows||Specifies whether Sort direction indicators (arrows) will be displayed when the user clicks a column header to sort the table. Default: False|
|Width||Specifies the total width of the data table.|
|Width Scale||Specifies the scale to be used when applying the value of the previous attribute, px for pixels, or % for percentage of the table's parent container's width.|
In general, the fewer attributes you have to set for a Data Table, the better. Let a Theme or the browser figure out the best combination of attributes for you.
About Table and Column Widths
Browser engines are designed to do the best job they can with HTML tables (which is the structure underlying a Data Table) when it comes to automatically figuring out column widths. Here are some tips to make widths work for you.
First, always set a width for a Data Table, using its Width attribute.
Second, for most purposes, leave the Data Table element's Layout attribute blank. This defaults to Auto mode, which sets columns width to the widest data.
Third, if you're concerned about ensuring that one or two columns have a specific width, then set those widths in the appropriate Data Table Column elements but leave the widths for the other Data Table Column elements blank. You don't need to try to figure out what the width of every column will be, ensuring it all adds up to 100% of the table width. The browser will try to guarantee the widths you've specifically set and will divide and allocate the remaining space among the remaining columns, when it can.
And remember that it is possible to put so many conflicting restrictions (via attribute values) in place that the browser will get confused and produce weird results. If that happens, try removing width attribute values for columns until things look normal again, then reconsider the issue.
A common requirement is to be able to click the actual data in a data table cell and do something with the clicked value.
The image above shows an example of this, and here are the elements needed to make that work:
As shown above, an Action element is placed beneath the Label element used to display the data in each column. An appropriate Target element is also included.
Finally, a Link Parameters element is added, as shown above, to pass a data value to the target.