- clear stage

Signed-off-by: Dave Richer <dave@imexsystems.ca>
2024-02-16 12:50:51 -05:00
parent 46be569b4a 601fdbba39
commit e020f60d34
13 changed files with 977 additions and 22 deletions
--- a/_reference/reportFiltersAndSorters.md
+++ b/_reference/reportFiltersAndSorters.md
@@ -0,0 +1,126 @@
+# Filters and Sorters
+
+This documentation details the schema required for `.filters` files on the report server. It is used to dynamically
+modify the graphQL query and provide the user more power over their reports.
+
+## High level Schema Overview
+
+```javascript
+const schema = {
+    "filters": [
+        {
+            "name": "jobs.joblines.mod_lb_hrs", // Name and path of the field in the graphQL query
+            "translation": "jobs.joblines.mod_lb_hrs_1", // Translation key for the label used in the GUI
+            "label": "mod_lb_hrs_1",    // Label used in the case the GUI does not contain a translation
+            "type": "number" // Type of field, can be number or string currently
+        },
+        // ... more filters
+    ],
+    "sorters": [
+        {
+            "name": "jobs.joblines.mod_lb_hrs",  // Name and path of the field in the graphQL query
+            "translation": "jobs.joblines.mod_lb_hrs_1",  // Translation key for the label used in the GUI
+            "label": "mod_lb_hrs_1", // Label used in the case the GUI does not contain a translation
+            "type": "number"  // Type of field, can be number or string currently
+        },
+        // ... more sorters
+    ],
+    "dates": {
+        // This is not yet implemented and will be added in a future release
+    }
+}
+```
+
+## Filters
+
+Filters effect the where clause of the graphQL query. They are used to filter the data returned from the server.
+A note on special notation used in the `name` field.
+
+### Path without brackets, multi level
+
+`"name": "jobs.joblines.mod_lb_hrs",`
+This will produce a where clause at the `joblines` level of the graphQL query,
+
+```graphql
+query gendoc_hours_sold_detail_open($starttz: timestamptz!, $endtz: timestamptz!) {
+    jobs(
+        where: {date_invoiced: {_is_null: true}, date_open: {_gte: $starttz, _lte: $endtz}, ro_number: {_is_null: false}, voided: {_eq: false}}
+    ) {
+        joblines(
+            order_by: {line_no: asc}
+            where: {removed: {_eq: false}, mod_lb_hrs: {_lt: 3}}
+        ) {
+            line_no
+            mod_lbr_ty
+            mod_lb_hrs
+            convertedtolbr
+            convertedtolbr_data
+        }
+        ownr_co_nm
+        ownr_fn
+        ownr_ln
+        plate_no
+        ro_number
+        status
+        v_make_desc
+        v_model_desc
+        v_model_yr
+        v_vin
+        v_color
+    }
+}
+```
+
+### Path with brackets,top level
+
+`"name": "[jobs].joblines.mod_lb_hrs",`
+This will produce a where clause at the `jobs` level of the graphQL query.
+
+```graphql
+query gendoc_hours_sold_detail_open($starttz: timestamptz!, $endtz: timestamptz!) {
+    jobs(
+        where: {date_invoiced: {_is_null: true}, date_open: {_gte: $starttz, _lte: $endtz}, ro_number: {_is_null: false}, voided: {_eq: false}, joblines: {mod_lb_hrs: {_gt: 4}}}
+    ) {
+        joblines(
+            order_by: {line_no: asc}
+            where: {removed: {_eq: false}}
+        ) {
+            line_no
+            mod_lbr_ty
+            mod_lb_hrs
+            convertedtolbr
+            convertedtolbr_data
+        }
+        ownr_co_nm
+        ownr_fn
+        ownr_ln
+        plate_no
+        ro_number
+        status
+        v_make_desc
+        v_model_desc
+        v_model_yr
+        v_vin
+        v_color
+    }
+}
+```
+
+## Known Caveats
+
+- Will only support two level of nesting in the graphQL query `jobs.joblines.mod_lb_hrs` vs `[jobs].joblines.mod_lb_hrs`
+  is fine, but `jobs.[joblines.].some_table.mod_lb_hrs` is not.
+- The `dates` object is not yet implemented and will be added in a future release.
+- The type object must be 'string' or 'number' and is case-sensitive.
+- The `translation` key is used to look up the label in the GUI, if it is not found, the `label` key is used.
+- Do not add the ability to filter things that are already filtered as part of the original query, this would be
+  redundant and could cause issues.
+- Do not add the ability to filter on things like FK constraints, must like the above example.
+
+## Sorters
+
+- Sorters follow the same schema as filters, however, they do not do square bracket wrapping to indicate level hoisting,
+  a filter added on `job.md_status` would be added at the top level, and a filter added on `jobs.joblines.mod_lb_hrs`
+  would be added at the `joblines` level.
+- Most of the reports currently do sorting on a template level, this will need to change to actually see the results
+  using the sorters.