@isoftdata/utility-dashboard-backend 2.0.2 → 2.1.0

package/schema.md

@@ -1,125 +0,0 @@
-## Reporting/Charting
-The dashboard component has a set of three database tables where reports, charts, and their associations are defined: `dashboard_report`, `dashboard_chart`, and `dashboard_report_chart`. Reports are a collection of various charts. Reports have parameters and charts can use said parameters. Currently Charts are rendered using [Google Charts](https://developers.google.com/chart/).
-
-### Defining a Report
-Reports can be created either with the frontend dashboard component or manually in the database. The frontend component supports setting the report's name, the charts contained within it, who it is shared with, and the default value of any parameters. Currently it is not possible to add or remove parameters for reports within the frontend component, as charts' queries also have to support any additional parameters.
-
-### Report Database Row - `dashboard_report`
-Property | Type | Description
----- | ---- | -----------
-dashboard_report_id | `Unsigned integer` | **Required** - Primary key. Auto incremented.
-report_name | `String` | **Required** - a unique name for the report.
-report_title | `String` | When rendered, this title will be displayed at the top of the card. If omitted, `name` will be used.
-json | `JSON` | Should be parsed into a JS object. This field contains JSON for an array of parameter objects, the format of which is detailed below.
-share_type | `Enum` | Controls access to reports within the dashboard. Possible values include: `everyone`, `group`, `store`, and `user`. Defaults to `everyone`.
-share_id | `Unsigned integer` | Used in conjunction with `share_type` to control access to reports. When `share_type` is 'everyone', this field is null. Otherwise, it contains the id of the user, group, or store to share the report with. Defaults to `NULL`.
-owner_id | `Unsigned integer` | The `user_account_id` of the user who created the report in the dashboard. This user will always have access to the given report, regardless of its sharing settings, and will be shown as the report owner on the configuration screen. Defaults to `NULL`, which designates it as a default report.
-
-#### Base Parameter Object
-Property | Type | Description
----- | ---- | -----------
-name | `String` | **Required** - a unique name for the parameter. This name is also used to reference param in a query.
-title | `String` | This is used to label the parameter for the user.
-type | `String` | Can be one of `dateRange`, `date`, or `selection`. See the tables below for parameter-type-specific properties
-
-##### `dateRange` Type Parameters
-> In the UI, the user will see a dropdown with the possible date range values(see `default` description below).
-
-Property | Type | Description
----- | ---- | -----------
-default | `String` | One of the following values: `'Today'`, `'Yesterday'`, `'Last 7 Days'`, `'Last 30 Days'`, `'Last 90 Days'`, `'Last 365 Days'`, `'This Week'`, `'This Month'`, `'This Quarter'`, `'This Year'`, `'Previous Week'`, `'Previous Month'`, `'Previous Quarter'`, or `'Previous Year'`. If the `default` property is omitted or [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), `'Last 30 Days'` will be used.
-
-##### `date` Type Parameters
-> In the UI, the user will see a dropdown with a date picker.
-
-Property | Type | Description
----- | ---- | -----------
-default | `String` | Can be an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string(eg. `'2021-01-13'`). If the `default` property is omitted or [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), the today's date will be used.
-
-##### `selection` Type Parameters
-> In the UI, the user will see a dropdown with the `optionList` values(if any) and the values returned from the `optionListQuery`(if any). If the user passes a value that isn't in the `optionList`, the first option in the array will be used instead.
-
-Property | Type | Description
----- | ---- | -----------
-default | `String` | The `id` of the option you'd like to be selected by default
-optionList | `Object` | Each object should have an `id`, and `name`. The `id` is the value that will be given to you at query time and `name` is what will be displayed in the dropdown to the user. Values are [escaped by the mysql library](https://github.com/mysqljs/mysql#escaping-query-values), unless `rawSql: true` is on an option's object.
-optionListQuery | `String` | A query that selects 2 columns `id` and `name`. The results of this query will be merged with `optionList` and put in the dropdown for the user.
-
-##### `session` Type Parameters
-> These parameters are not shown in the UI since they do not require or allow user input.
-
-The `name` property is camel cased and used to access the variable from the session object.
-
-#### Example
-'dashboard_report_id' | 'report_name' | 'report_title' | 'json' | 'share_type' | 'share_id' | 'owner_id'
--- | ---- | ---- | ------- | -- | -- | --
-1 | report_overview | Overview | `{"parameters": [{"name": "date_range", "type": "dateRange", "title": "Date Range", "default": "This Year"}]}` | everyone | `NULL` | `NULL`
-2 | shared_report | Shared Report | `{"parameters":[{"name":"date_range","type":"dateRange","title":"Date Range","default":"This Month"}]}` | user | 1 | 2
-
-### Defining a Chart
-Currently, charts cannot be defined within Pro web, and must be created in the database table `dashboard_chart`. Currently, 19 charts are defined, but some are set to not show as options in the user interface.
-
-### Chart Database Row - `dashboard_chart`
-Property | Type | Description
----- | ---- | -----------
-chart_id | `Unsigned integer` | **Required** - primary key. Auto incremented.
-chart_name | `String` | **Required** - a unique name for the chart
-chart_title | `String` | When rendered, this title will be displayed at the top of the card. If omitted, `name` will be used.
-supertype | `Enum` | **Required** - designates how the chart should be loaded. Options include `google`, `table`, and `embed`. Defaults to `google`.
-json | `json` | Should be parsed to a JS object on the server. Contains several properties: `query` (string, **required**), [`chartWrapper`](https://developers.google.com/chart/interactive/docs/reference#chartwrapper-class) (object, **required** for Google charts), `multiSeries` (object, **required** for multi-series charts), `formatting` (object).
-show_chart | `Bit` | **Required** - Should be cast as a boolean on the server. Whether or not to show a chart in the configuration UI. Defaults to `1`.
-
-#### MultiSeries Object
-Property | Type | Description
----- | ---- | -----------
-groupXAxisBy | `String` | **Required** - The name of the query column that determines the X axis of the chart.
-series | `String` | **Required** - The name of the query column that determines which series a query row corresponds to.
-value | `String` | **Required** - The namem of the query column that contains the value for that data point.
-tooltip | `String` | The name of the (optional) query column that contains a custom plaintext tooltip, which replaces the default Google Charts tooltip. Does not work for Tree Map type charts, which have special tooltip requirements.
-
-#### Formatting Object
-An object whose property names are the columns in the query to be formatted. Currently only currency formatting is supported.
-
-Property | Type | Description
----- | ---- | ---------
-type | `String` | The name of a [Google Charts Formatter](https://developers.google.com/chart/interactive/docs/reference?hl=en#formatters).
-format | `String` | The name of a formatter template, defined in `formatter-templates.json`.
-#### JSON Example
-
-```json
-{
-	"chartWrapper": {
-		"chartType": "AreaChart",
-		"options": {
-			"isStacked": true,
-			"width": 1000,
-			"height": 1000
-		}
-	},
-	"multiSeries": {
-		"groupXAxisBy": "Date",
-		"series": "Part Type",
-		"value": "Sales",
-		"tooltip": "Tooltip"
-	},
-	"formatting": {
-		"Sales": {
-			"type": "NumberFormat",
-			"format": "CURRENCY"
-		}
-	},
-	"query": "SELECT t.date AS `Date`,\r\n       IFNULL (t.part_type, 'Misc. Lineitems') AS `Part Type`,\r\n       ROUND(@running_total:=@running_total + t.sales, 2) AS `Sales`\r\nFROM\r\n(SELECT \r\n`wa_sale`.`document_date` AS `Date`,\r\nIF(wa_sale_line.part_type = '', 'Misc. Lineitems', wa_sale_line.part_type) AS `part_type`,\r\nFORMAT(SUM(wa_sale_line.quantity * `wa_sale_line`.`price`), 2) AS `sales`\r\nFROM \r\n`wa_sale_line`\r\nINNER JOIN `wa_sale` USING(`sale_id`)\r\nWHERE\r\n`wa_sale`.`status` = 'Invoice' AND wa_sale.document_date IS NOT NULL\r\n GROUP BY \r\n `wa_sale`.`document_date`, `wa_sale_line`.`part_type`) t\r\n JOIN (SELECT @running_total:=0) r\r\n ORDER BY t.Date;"
-}
-```
-
-### Adding charts to reports
-Adding charts to reports can be handled entirely within the dashboard component. Each row in the database table `dashboard_report_chart` defines the association of one chart to one report, the rank of the chart within the report, and any additional object properties to apply to the chart when displayed in that report.
-
-### Report Chart Database Row - `dashboard_report_chart`
-Property | Type | Description
----- | ---- | --------
-report_chart_id | `Unsigned integer` | **Required** - Primary key. Auto incremented.
-dashboard_report_id | `Unsigned integer` | **Required** - Foreign key constraint with `dashboard_report.dashboard_report_id`.
-chart_id | `Unsigned integer` | **Required** - Foreign key constraint with `dashboard_chart.dashboad_chart_id`. `chart_id` and `dashboard_report_id` must be a unique pair.
-rank | `Unsigned integer` | The order to display the chart in on the report. Defaults to 1.
-json_override | `Text` | Parsed as JSON on the server. Contains any JSON properties to be applied to the chart for the given report, overriding any of the same property on the base chart. Primarily used for chartWarpper options. Default `NULL`.

package/style-templates.js

@@ -1,31 +0,0 @@
-
-const mathjs = require('mathjs')
-const snakecaseKeys = require('snakecase-keys')
-
-function handleMathJsCellStyleTemplate(row, columnToStyle, templates) {
-	let outColumn = { value: row[columnToStyle] }
-	if (columnToStyle in templates) {
-		// MathJS mutates the object you pass it, and we need to ensure keys are single "word" strings, so snakeize a copy of the row
-		const scope = snakecaseKeys({ ...row }, { deep: true })
-		for (const key in templates[columnToStyle]) {
-			try {
-				outColumn[key] = mathjs.evaluate(templates[columnToStyle][key], scope)
-			} catch (err) {
-				// Obviously we don't want to break the whole table if one cell has a bad template
-				// For now, just log it to stderr and allow it to fall through even though it's not super debuggable
-				console.error(`Error evaluating expression: '${templates[columnToStyle][key]}'\n`, err)
-			}
-		}
-	}
-	return outColumn
-}
-
-function styleRow(row, templates) {
-	const outRow = {}
-	for (const column in row) {
-		outRow[column] = handleMathJsCellStyleTemplate(row, column, templates)
-	}
-	return outRow
-}
-
-module.exports = styleRow

package/stylingTest.jsonc

@@ -1,37 +0,0 @@
-{
-	"query": "SELECT 'False' AS 'Seller Invoice', 'True' AS 'Rec. Payment', '' AS 'Paid For'",
-	"formatting": {},
-	"chartWrapper": {
-		"options": {
-			"width": 500,
-			"height": 500,
-			"width_units": "%"
-		},
-		"chartType": "Table"
-	},
-	"greedyWidth": true,
-	"greedyHeight": true,
-	"hideTitle": true,
-	"table": {
-		"perPageCount": 15,
-		"showFooter": true,
-		"allowExport": true,
-		"style": {
-			"Seller Invoice": { // Column to style
-				"columnToCheck": false, // column to check condition against, falsy = this column
-				"in": [ // value is in the set
-					"False",
-					""
-				],
-				"class": "table-danger" // class to apply
-			},
-			"Rec. Payment": { // Column to style
-				"columnToCheck": "Paid For", // column to check condition against
-				"notIn": [ // value is not in the set
-					""
-				],
-				"class": "table-danger" // class to apply
-			}
-		},
-	}
-}