How to create custom charts

1 Open charts manage page

Navigate from home page, navbar or charts page to the charts manage page (e.g. https://localhost:9000/charts/manage).

2 Create new chart

• Click the New Chart button
• Choose a meaningful name

3 Write the code

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.

3.1 Getting data

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

3.2 Creating the chart

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.

4 Save and Test

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.