Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update grid pro pages + new content - PTL-1517 #1969

Merged
merged 7 commits into from
Dec 3, 2024
Merged

docs: update grid pro pages + new content - PTL-1517 #1969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b05d72d
docs: update grid pro pages + new content - PTL-1517
MrBrunoWolff Nov 27, 2024
3cb41ca
docs: update grid pro pages + new content (2) - PTL-1517
MrBrunoWolff Nov 28, 2024
d5a4fd4
docs: update grid pro pages + new content (3) - PTL-1517
MrBrunoWolff Nov 28, 2024
468841f
Merge branch 'new-doc-structure' of github.com:genesiscommunitysucces…
MrBrunoWolff Dec 2, 2024
94a3528
fix: update grid-pro docs + tweak code examples and address live demo…
MrBrunoWolff Dec 2, 2024
3f98dc8
docs: massive update to renderers doc + with examples and API links -…
MrBrunoWolff Dec 2, 2024
8b5eb7f
docs: address failing react code - PTL-1517
MrBrunoWolff Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/001_develop/03_client-capabilities/005_grids/003_grid-pro/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +0,0 @@
collapsible: false
334 changes: 334 additions & 0 deletions ...velop/03_client-capabilities/005_grids/003_grid-pro/grid-pro_02_datasources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,334 @@
---
title: 'Datasources'
sidebar_label: 'Datasources'
id: grid-pro-datasources
keywords: [genesis, foundation, ui, grid, grid-pro, ag, datasource, client-side, server-side]
tags:
- connected
- datasource
- grid
- grid-pro
- ag
- client-side
- server-side
pagination_prev: develop/client-capabilities/grids/grid-pro/grid-pro
pagination_next: develop/client-capabilities/grids/grid-pro/grid-pro-cell-and-column
---

import GroovyFilterExpressions from '../../../../_includes/_groovy-filter-expressions.mdx'

# Datasources

## Overview

The `@genesislcap/grid-pro` package provides a collection of grid-pro datasource components. These components are responsible for fetching data for the Genesis Grid Pro component.

## `<grid-pro-client-side-datasource>`

### Client-Side Features

- **Sorting**: Order by any column, ASC or DESC.
- **Filtering**:
matteematt marked this conversation as resolved.
Show resolved Hide resolved
- Filtering options are automatically generated based on the resource’s metadata.
- **String Filters**:
- contains
- not contains
- equals
- not equals
- starts with
- ends with
- blank
- not blank
- **Number/Date Filters**:
- equals
- less than
- less than or equal
- greater than
- greater than or equal
- in range
- **Filter Combinations** (Max 2 filters can be combined):
- filter1 AND filter2
- filter1 OR filter2

### Client-Side Notes

- Works with both `DATASERVER` and `REQUEST_SERVER` resources.
- Operations like sorting and filtering are performed on the client-side.
- Suitable for datasets that are small to medium in size and can be entirely loaded into the client.

### Usage Example

```html
<rapid-grid-pro enable-row-flashing enable-cell-flashing>
<grid-pro-client-side-datasource
resource-name="ALL_TRADES"
criteria="INSTRUMENT_ID == 'TSLA'"
></grid-pro-client-side-datasource>
</rapid-grid-pro>
```

## `<grid-pro-server-side-datasource>`

### Server-Side Features

- **Sorting**: Order by any INDEX column/field, ASC or DESC.
- This is a server limitation. For each column that needs to have “sorting” the developer will need to have an INDEX for it. See more about indexes [here](/develop/server-capabilities/real-time-queries-data-server/#indices).
- By default, sorting is disabled on all columns, but if valid indexes are detected from the metadata, those columns/fields will have sorting enabled.
- If the user attempts to force `sortable`, we'll check its validity, warn in the logs if not, and mention other available indexes if any.
- **Filtering**:
- Filtering options are automatically generated based on the resource’s metadata.
- **String Filters**:
- blank
- contains
- equals
- notBlank
- notEqual
- wordStartsWith
- **Number Filters**:
- equals
- notEqual
- greaterThan
- greaterThanOrEqual
- lessThan
- lessThanOrEqual
- inRange
- blank
- notBlank
- **Date Filters**:
- equals
- lessThan
- greaterThan
- inRange
- isToday
- blank
- notBlank

### Server-Side Notes

- Operations like sorting and filtering are pushed to the backend.
- Filtering uses `CRITERIA_MATCH` param.
- Sorting uses `ORDER_BY` param.
- Once filtering/sorting is applied, the datasource component resets itself, starting a new stream with the updated params.
- **Limitations**:
- Sorting can only be applied to index fields/columns.
- `ROWS_COUNT` doesn’t reflect the correct amount when a `CRITERIA_MATCH` (filtering) is applied. For example, if a resource has 100 records and a criteria returns only 50, the server still reports 100. We have to calculate this manually.
- Suitable for large datasets where only a subset of data is loaded into the client based on user interactions.

### Usage Example

```html
<rapid-grid-pro enable-row-flashing enable-cell-flashing>
<grid-pro-server-side-datasource
resource-name="ALL_TRADES"
criteria="INSTRUMENT_ID == 'TSLA'"
></grid-pro-server-side-datasource>
</rapid-grid-pro>
```

## Common Attributes
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These attribute tables are good but they don't follow the format of every other API section

I know we're short on time now so happy for this to go in if you think you can't do it, and then you or I can tweak it when we get the chance

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will address in a follow up PR


There are many attributes that can be set on a datasource component. These attributes can be used to customize the behavior of the datasource and the grid component. Below is a list of some of the most commonly used attributes.

### Resource Attributes

Some **resource** attributes are `DATASERVER` or `REQUEST_SERVER` specific, while others can be used with both.

#### Attributes Common to DATASERVER and REQUEST_SERVER

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>resource-name</code></td>
<td><code>string</code></td>
<td>-</td>
<td>The name of the target <a href="/develop/server-capabilities/real-time-queries-data-server/">Data Server</a> <code>query</code> or <a href="/develop/server-capabilities/snapshot-queries-request-server/">Request Server</a> <code>requestReply</code>.</td>
</tr>
<tr>
<td><code>is-snapshot</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>Request a snapshot from the server.</td>
</tr>
<tr>
<td><code>criteria</code></td>
<td><code>string</code></td>
<td>-</td>
<td>Clients can send a Groovy expression to perform filters on the query server; these remain active for the life of the subscription.</td>
</tr>
<tr>
<td><code>max-rows</code></td>
<td><code>number</code></td>
<td>-</td>
<td>Maximum number of rows to be returned as part of the initial message and any additional MORE_ROWS messages. <strong>This will not affect the number of rows displayed.</strong></td>
</tr>
<tr>
<td><code>view-number</code></td>
<td><code>number</code></td>
<td>-</td>
<td>The desired view/page you want data from.</td>
</tr>
</tbody>
</table>

<GroovyFilterExpressions />

#### DATASERVER Only Attributes

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>fields</code></td>
<td><code>string</code></td>
<td>-</td>
<td>This optional parameter allows you to select a subset of fields from the query if the client is not interested in receiving all of them.</td>
</tr>
<tr>
<td><code>max-view</code></td>
<td><code>number</code></td>
<td>-</td>
<td>Maximum number of rows to track as part of a client "view".</td>
</tr>
<tr>
<td><code>moving-view</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>If true, when the maximum number of rows defined in <code>max-view</code> is reached, the Data Server will start discarding the oldest rows (in terms of timestamp) and sending newer rows. If false, updates in the server will be sent to the front end regardless of order. Note that this will only update the UI; no changes will be performed in the database.</td>
</tr>
<tr>
<td><code>order-by</code></td>
<td><code>string</code></td>
<td>-</td>
<td>This option can be used to select a <a href="/develop/server-capabilities/real-time-queries-data-server/#indices">Data Server index</a> (defined in the Data Server <code>query</code>), which is especially useful if you want the data to be sorted in a specific way. By default, Data Server rows are returned in order of creation (from oldest database record to newest).</td>
</tr>
<tr>
<td><code>reverse</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>This option changes the <a href="/develop/server-capabilities/real-time-queries-data-server/#indices">Data Server index</a> iteration. For example, if you are using the default index, the query will return rows in order from the newest database records to the oldest.</td>
</tr>
</tbody>
</table>

#### REQUEST_SERVER Only Attributes

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>disable-polling</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>This option disables polling if set to true (data updates for the grid will not be fetched automatically).</td>
</tr>
<tr>
<td><code>polling-interval</code></td>
<td><code>number</code></td>
<td>-</td>
<td>This option enables you to set a custom polling frequency (in milliseconds) for a <a href="/develop/server-capabilities/snapshot-queries-request-server/">Request Server</a> resource. Note that this option only works with Request Server resources; if your resource is a Data Server <code>query</code>, your grid is updated in real time.</td>
</tr>
<tr>
<td><code>request</code></td>
<td><code>string</code></td>
<td>-</td>
<td>Similar to <code>fields</code> but for <a href="/develop/server-capabilities/snapshot-queries-request-server/">Request Server</a> scenarios. This optional parameter enables you to specify request fields, which can include wildcards.</td>
</tr>
<tr>
<td><code>request-auto-setup</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>This option, if set to true, will automatically set up the <code>request</code> based on the datasource's metadata.</td>
</tr>
</tbody>
</table>

### Exclusive Attributes

Additional attributes that can affect the behavior of a datasource component.

#### `<grid-pro-client-side-datasource>`

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>restart-on-reconnection</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>If set to true, the resource data will be reloaded upon a reconnection event.</td>
</tr>
<tr>
<td><code>keep-col-defs-on-clear-row-data</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>If set to true, column definitions will be retained upon a <code>restart</code> or <code>clearRowData</code> event.</td>
</tr>
</tbody>
</table>

#### `<grid-pro-server-side-datasource>`

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pagination</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>Enables pagination if set to true; otherwise, the behavior will be infinite-scroll.</td>
</tr>
<tr>
<td><code>zero-based-view-number</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>If set to true, the starting <code>VIEW_NUMBER</code> will be zero-based (starting from 0 instead of 1).</td>
</tr>
<tr>
<td><code>live-updates</code></td>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td>Enables live updates for the grid if set to true.</td>
</tr>
</tbody>
</table>

## Summary

- **Client-Side Datasource**: Suitable for smaller datasets where all data can be loaded into the client. Operations like sorting and filtering are performed on the client-side.
- **Server-Side Datasource**: Ideal for large datasets, where operations are pushed to the backend to ensure performance and consistency. Data is fetched as needed based on user interactions.
Loading
Loading