-
Notifications
You must be signed in to change notification settings - Fork 17
How to create custom charts
Navigate from home page, navbar or charts page to the charts manage page (e.g. https://localhost:9000/charts/manage).
- Click the
New Chart
button - Choose a meaningful name
Don't worry about writing JavaScript code. A lot is prepared in order to support you while writing custom charts.
In the textarea named script
you will see a pre-filled template for your chart.
It looks like this:
/* This list will be dynamically filled with all the transactions between
* the start and and date you select on the "Show Chart" page
* and filtered according to your specified filter.
* An example entry for this list and tutorial about how to create custom charts ca be found in the BudgetMaster wiki:
* https://github.com/deadlocker8/BudgetMaster/wiki/How-to-create-custom-charts
*/
var transactionData = [];
// Prepare your chart settings here (mandatory)
var plotlyData = [{
x: [],
y: [],
type: 'bar'
}];
// Add your Plotly layout settings here (optional)
var plotlyLayout = {
title: {
// localizedTitle and localizedDateRange are the only available variables starting
// with "localized" inside custom charts!
text: formatChartTitle(localizedTitle, localizedDateRange),
},
};
// Add your Plotly configuration settings here (optional)
var plotlyConfig = {
showSendToCloud: false,
displaylogo: false,
showLink: false,
responsive: true
};
// Don't touch this line
Plotly.newPlot("containerID", plotlyData, plotlyLayout, plotlyConfig);
We will go through this step by step now.
After finishing all steps and saving your new custom chart you will find it on the charts page in the group custom
.
If you select your chart, choose a start and end date and optionally apply some filters and hit the Show Chart
button, the BudgetMaster server will aggregate all transactions meeting your criteria.
Afterwards your chart script will be loaded to the page and the variable transactionData
defined in var transactionData = [];
will be filled with these transactions.
The list will be filled with indiviudal transaction dictionaries. An entry representing a normal transaction will look like this:
{
"ID": 1,
"amount": -100,
"date": "2019-07-31",
"account": {
"ID": 2,
"name": "Default Account",
"accountState": "FULL_ACCESS",
"iconReference": {
"ID": 27,
"image": {}
},
"type": "CUSTOM"
},
"category": {
"ID": 1,
"name": "No Category",
"color": "#FFFFFF",
"type": "NONE",
"iconReference": {
"ID": 8,
"builtinIdentifier": "fas fa-coins"
}
},
"name": "test",
"description": "",
"tags": []
}
Note: The amount of each transaction is denoted in cents.
Recurring/repeating transactions will additionally include a complete repeatingOption
:
"repeatingOption": {
"ID": 33,
"startDate": "2019-06-22",
"modifier": {
"ID": 33,
"quantity": 1,
"localizationKey": "repeating.modifier.days"
},
"endOption": {
"times": 100,
"ID": 33,
"localizationKey": "repeating.end.key.afterXTimes"
}
}
A transfer will look like this:
{
"ID": 2,
"amount": -1500,
"date": "2019-07-18",
"account": {
"ID": 2,
"name": "Default Account",
"accountState": "FULL_ACCESS",
"iconReference": {
"ID": 27,
"image": {}
},
"type": "CUSTOM"
},
"category": {
"ID": 1,
"name": "No Category",
"color": "#FFFFFF",
"type": "NONE",
"iconReference": {
"ID": 23,
"builtinIdentifier": "fas fa-piggy-bank"
}
},
"name": "My Transfer",
"description": "",
"tags": [],
"transferAccount": {
"ID": 34,
"name": "Savings Bank",
"accountState": "FULL_ACCESS",
"iconReference": {
"ID": 29,
"image": {}
},
"type": "CUSTOM"
}
}
Note: the field transferAccount
describes the destination of the transfer.
Note: There is currently no field called type
that can be used to differentiate between normal and recurring transactions and transfers. In order to do so use the following characteristics:
Transaction type | repeatingOption |
transferAccount |
---|---|---|
normal | not existing | not existing |
recurring normal | filled | not existing |
transfer | not existing | filled |
recurring transfer | filled | filled |
Once you retrieved the transaction data and performed all your magic calculations you are ready to create the visualization. BudgetMaster uses Plotly to generate the charts https://plot.ly/javascript/. In order to create your own chart please have a look at the massive plotly online documentation.
Note: In most cases it will not be necessary to edit the variables plotlyLayout
an plotlyConfig
so you can skip them.
Important: Please don't touch the last line Plotly.newPlot('chart-canvas', plotlyData, plotlyLayout, plotlyConfig);
or edit any pre-defined variable names.
Save your created chart, head over to the charts page, select your chart and hit the Show Chart
button. Does everything work as expected?
If you are having any troubles or no chart is shown at all than consier opening the JavaScript debug console provided by your browser (e.g. in Firefox you hit F12
and switch to console
) All errors will be displayed there.
Note: You can't edit the default charts but you can view the source code to get an overview on how to create complex charts.