This is an old revision of the document!


TableViews

A Tableview is basically a list of all Cards of a special Proto. Essential elements in organising data in a tabular manner. :sunglasses:

Minimal vertical size of a TableView

Protogrid automatically adjusts the height of TableViews to fit the data they contain and the space available. The property 'Minimal Vertical Size' allows to set the minimum height of the TableViews. However, if there is still whitespace on the surrounding card, the TableView will be displayed as large as possible regardless of this property.

This property also controls how many rows this TableView loads together. It is therefore a possibility for performance optimizations by the developer. Optimal in most cases is “Medium”. For embedded TableViews with only few entries “Small” might fit better.

The setting “Large” is needed in rare cases:

  • When an embedded TableView should be displayed as large as possible (e.g. because it displays a lot of sophisticated data).
  • When as many rows as possible (up to 500) must be able to be selected together (e.g. for mass email sending functionality).
  • When users typically scroll back and forth a lot in this TableView (that is, when the user does not just search for a specific document in the TableView and opens it immediately).

Styling Cells of a TableView

Since Protogrid is based on web technologies you can use common HTML tags to influence how cells are presented to users. Just insert suitable HTML tags into the text of your fields/columns. You can do this either manually or by using a ScriptLibraries.

Inspiration:

<br>
 
<a href="www.google.com">Link into the world wide web</a>
 
<b>This entry is important!</b>
 
<small>You don't really have to read this text ;-)</small>
 
<font color="red">Urgent!</font>

Hide Certain Columns

It's also possible to hide certain fields you don't want to appear as a column in TableViews: Just open the field definition and set its “Display Priority” to 0. This will lead to the field being hidden in TableViews, automatic titles and short names. However, the field itself will still be displayed on Data Cards. If you also want to hide the field on Data Cards, simply take a ScriptLibrary.

Hide Certain List Entries By Using a Filter

It's also possible to hide certain Cards in the list of all Cards. For preparation you have to define a filter. By choosing one of the filter options the related Cards will be displayed.

Reload TableView Without Page Refresh

The following code example shows how a TableView can be reloaded programatically without a full page refresh.

datatables_by_id[FIELD_ID].fnDraw();

Filtering TableViews

There are several ways to filter the rows displayed in a TableView. Please see Filter for more details.

Search Dialog Boxes

Any number of dedicated Search Dialog Boxes (aka search masks) can be configured for a TableView.

Any number of Filter Fields can be assembled for a Search Dialog Box (each configured either as a filter or as a sorter). A maximum of two Tag Fields can be configured as filters per Search Dialog Box.

Please note that depending on the number of affected Cards, it may take several minutes before a newly created or modified search dialog box can be used by the users.

Display Client-Side Calculated Data as a Tableview

If the setting “Related Proto” on the TableView definition is left empty, Protogrid will not populate any data into the corresponding TableView. Instead, the TableView can be filled dynamically using Client-ScriptLibrary code.

To implement this, the following three JavaScript function calls are available:

Initialize Client-Side Calculated TableView

initialize_client_side_computed_tableview(tableview_id, header_cells, click_handler_callback, initial_table_data, initial_sorting_column_identifier, initial_sorting_descending);

This allows a client-side calculated TableView to be initialized. If a TableView has already been initialized, the function cannot be used a second time. The function parameters can be set as follows:

  • tableview_id [String]: ID of the TableView to be initialized (corresponds to the Card ID of the TableView definition).
  • header_cells [Array of Objects]: Definition of the columns used.
  • click_handler_callback [Function, optional]: Function which is called when the user clicks inside the TableView.
  • initial_table_date [Array of Objects]: Initial table data to display.
  • initial_sorting_column_identifier [String, optional]: Identifier of that column, by which the initial sorting should be done. If not set, the TableView will be sorted by the first sortable column by default.
  • initial_sorting_descending [Boolean, optional]: If “true”, the initially sorted column will be sorted in descending order (e.g. useful in case of date columns).

Example:

initialize_client_side_computed_tableview(
    "6e67b170-d6d3-4786-87b8-8db3e17ea960",
    [
        {
            "identifier": "test-text-column",                 // Must be a non-empty and unique string
            "text": "Test Text Column Header Text",           // Optional, defaults to ""
            "display_priority": 10,                           // Optional, defaults to 10
            "is_sortable": true                               // Optional, defaults to true
        },
        {
            "identifier": "test-number-column",
            "text": "Test Number Column Header Text",
            "display_priority": 9,
            "is_sortable": true
        },
        {
            "identifier": "test-date-column",
            "text": "Test Date Column Header Text",
            "display_priority": 8,
            "is_sortable": true
        },
        {
            "identifier": "test-html-column",
            "text": "Test HTML Column Header Text",
            "display_priority": 0,
            "is_sortable": true
        }
    ],    
    function(clicked_row, clicked_column_identifier) {
        alert("Click detected in row " + JSON.stringify(clicked_row) + " in column with identifier '" + clicked_column_identifier + "'.");
    },
    [
        {
            "row_identifier": "first-data-row",               // Must be a non-empty and unique string
            "test-text-column": "Aaron",                      // Optional, defaults to ""
            "test-number-column": 4,                          // Optional, defaults to ""
            "test-date-column": "11.11.2022 11:11",           // Optional, defaults to ""
            "test-html-column": "<i>Explanation text</i>"     // Optional, defaults to ""
        },
        {
            "row_identifier": "second-data-row",
            "test-text-column": "Damien",    
            "test-number-column": 3,
            "test-date-column": "12.11.2022 11:11",
            "test-html-column": "<i>Explanation text</i>"
        },
        {
            "row_identifier": "third-data-row",
            "test-text-column": "Mike",    
            "test-number-column": 2,
            "test-date-column": "11.12.2022 11:11",
            "test-html-column": "<i>Explanation text</i>"
        },
        {
            "row_identifier": "fourth-data-row",
            "test-text-column": "Paul",    
            "test-number-column": 1,
            "test-date-column": "11.12.2022 11:12",
            "test-html-column": "<i>Explanation text</i>"
        }
    ],
    "test-date-column",
    true
);

Do a Complete Update of the Data Displayed in a Client-Side Calculated TableView

complete_update_client_side_computed_tableview(tableview_id, new_table_data, sorting_column_identifier, sorting_descending);

This allows to update all data displayed in a client-side calculated TableView. The TableView has to already been initialized. The function parameters can be set as follows:

  • tableview_id [String]: ID of the TableView to be updated (corresponds to the Card ID of the TableView definition).
  • new_table_data [Array of Objects]: Initial table data to display.
  • sorting_column_identifier [String, optional]: Identifier of that column, by which the initial sorting should be done.
  • sorting_descending [Boolean, optional]: If “true”, the initially sorted column will be sorted in descending order (e.g. useful in case of date columns).

Example:

complete_update_client_side_computed_tableview(
    "6e67b170-d6d3-4786-87b8-8db3e17ea960",
    [
        {
            "row_identifier": "replaced-first-data-row",
            "test-text-column": "Miller",
            "test-number-column": 4004,
            "test-date-column": "2022-12-12T12:12:12",
            "test-html-column": "<b>Explanation text</b>"
        },
        {
            "row_identifier": "replaced-second-data-row",
            "test-text-column": "Smith",    
            "test-number-column": 3003,
            "test-date-column": "2024-12-12T12:12:12",
            "test-html-column": "<b>Explanation text</b>"
        },
        {
            "row_identifier": "replaced-third-data-row",
            "test-text-column": "Williams",    
            "test-number-column": 2002,
            "test-date-column": "2023-12-12T12:12:12",
            "test-html-column": "<b>Explanation text</b>"
        }
    ],
    "test-number-column",
    false
)

Update the Value of a Single Cell in a Client-Side Calculated TableView

cell_update_client_side_computed_tableview(tableview_id, new_cell_value, row_identifier, column_identifier)

This allows to update a single cell value in a client-side calculated TableView. The TableView has to already been initialized. The function parameters can be set as follows:

  • tableview_id [String]: ID of the TableView to be updated (corresponds to the Card ID of the TableView definition).
  • new_cell_value [String or Number]: Value with which the cell content is to be replaced.
  • row_identifier [String]: Identifier of the row in which the cell value is to be replaced.
  • column_identifier [String]: Identifier of the column in which the cell value is to be replaced.

Example:

cell_update_client_side_computed_tableview(
    "6e67b170-d6d3-4786-87b8-8db3e17ea960",
    "Aaron Williams",
    "replaced-first-data-row",
    "test-text-column"
)
Print/export