Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
protogrid:tableview [2019-11-29 13:54] 46.140.51.3protogrid:tableview [2021-12-21 22:48] (current) – [Display Client-Side Calculated Data as a Tableview] dru
Line 1: Line 1:
 ====== TableViews ====== ====== TableViews ======
- 
 A Tableview is basically a list of all Cards of a special Proto. Essential elements in organising data in a tabular manner. :sunglasses: A Tableview is basically a list of all Cards of a special Proto. Essential elements in organising data in a tabular manner. :sunglasses:
  
-=== Styling Cells of a TableView ===+===== 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 [[protogrid:script_library|ScriptLibraries]]. 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 [[protogrid:script_library|ScriptLibraries]].
  
 Inspiration: Inspiration:
- 
 <code html> <code html>
 <br> <br>
Line 21: Line 29:
 </code> </code>
  
-=== Hide Certain Columns === +===== 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 [[protogrid:field|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 [[protogrid:field|field]] itself will still be displayed on [[protogrid:card|Data Cards]]. If you also want to hide the field on Data Cards, simply take a [[protogrid:script_library|ScriptLibrary]]. It's also possible to hide certain fields you don't want to appear as a column in TableViews: Just open the [[protogrid:field|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 [[protogrid:field|field]] itself will still be displayed on [[protogrid:card|Data Cards]]. If you also want to hide the field on Data Cards, simply take a [[protogrid:script_library|ScriptLibrary]].
  
  
-=== Hide Certain List Entries By Using Filter ===+===== Hide Certain List Entries By Using Filter ===== 
 +It's also possible to hide certain Cards in the list of all Cards. For preparation you have to [[protogrid:filter|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. 
 + 
 +<code javascript> 
 +datatables_by_id[FIELD_ID].fnDraw(); 
 +</code> 
 + 
 +===== Filtering TableViews ===== 
 +There are several ways to filter the rows displayed in a TableView. Please see [[protogrid:Filter|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). Per target field only one Filter Field can be defined at a time. Note that a maximum of two Tag Fields can be configured as filters per Search Dialog Box. 
 + 
 +Unlike normal views, in Search Dialog Boxes users basically have to fill in/set all filters. An empty filter field in a Search Dialog Boxes means a filter for those Cards where the target field is also empty. 
 + 
 +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 ==== 
 +<code javascript>initialize_client_side_computed_tableview(tableview_id, header_cells, click_handler_callback, initial_table_data, initial_sorting_column_identifier, initial_sorting_descending);</code> 
 + 
 +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: 
 +<code javascript>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                               // Note that for correct sorting of dates, the cell values must be understood by Javascript's Date() object or comply with the following format: "DD.MM.YYYY( HH:mm(:ss))" 
 +        }, 
 +        { 
 +            "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 
 +);</code> 
 + 
 +==== Do a Complete Update of the Data Displayed in a Client-Side Calculated TableView ==== 
 +<code javascript>complete_update_client_side_computed_tableview(tableview_id, new_table_data, sorting_column_identifier, sorting_descending);</code> 
 + 
 +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: 
 +<code javascript>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": "05.06.2023 01:02:03", 
 +            "test-html-column": "<b>Explanation text</b>" 
 +        }, 
 +        { 
 +            "row_identifier": "replaced-second-data-row", 
 +            "test-text-column": "Smith",     
 +            "test-number-column": 3003, 
 +            "test-date-column": "05.06.2024 01:02:03", 
 +            "test-html-column": "<b>Explanation text</b>" 
 +        }, 
 +        { 
 +            "row_identifier": "replaced-third-data-row", 
 +            "test-text-column": "Williams",     
 +            "test-number-column": 2002, 
 +            "test-date-column": "05.06.2025 01:02:03", 
 +            "test-html-column": "<b>Explanation text</b>" 
 +        } 
 +    ], 
 +    "test-number-column", 
 +    false 
 +);</code> 
 + 
 +==== Update the Value of a Single Cell in a Client-Side Calculated TableView ==== 
 +<code javascript>cell_update_client_side_computed_tableview(tableview_id, new_cell_value, row_identifier, column_identifier);</code> 
 + 
 +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.
  
-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 records will be displayed.+Example: 
 +<code javascript>cell_update_client_side_computed_tableview( 
 +    "6e67b170-d6d3-4786-87b8-8db3e17ea960", 
 +    "Aaron Miller", 
 +    "replaced-first-data-row", 
 +    "test-text-column" 
 +);</code>
Print/export