The formatter is a powerful feature in DataPicta that allows you to customize how text elements present data in your charts. You will find the formattor in various places throughout the DataPicta application with 4 different types.

Axis label formatter

For all 6 axes you can customize the label text using the formatter.
Lets look at an example of a vertical axis showing temperature values in Celsius during a nice summer day.

Fruit,Price
Apple,1.2
Banana,0.8
Cherry,2.5
Date,3.0
Elderberry,1.5

A bar chart created with this data looks like this:

The bar has its prices on the vertical (y) axis and the fruit names on the horizontal (x) axis. But the chart does not show any currency symbol for the prices. Also the data does not have any units. You can fix that using the formatter.

Adding a currency symbol

In the DataPicta app, you can open the vertical axis panel and enable the label, here you can find the formatter input field. If you click on it a dialog with a larger text area will open, this is because the formatter can take up more space than usually fits in an input field. Besides that the text area also has syntax highlighting to help you write the formatter syntax.

To add a dollar sign ($) in front of the prices, you can use the following format string:

In this example we add a dollar sign and use {item} to insert the data values. Whatever you write inside the curly braces {} has to do with the data. Anything outside the curly braces is just plain text.

You can do simple math operations as well, for example to add 25% tax to the prices you can use:

Resulting in this chart:

Let's also round the prices to two decimal places using the round function:

Resulting in:

Adding decimal places

The following example shows how to use expressions in the formatter.

Don't worry if this looks complicated, you may skip this step because it is hardly used. But if you have written code before, you probably notice the ternary operator condition ? valueIfTrue : valueIfFalse, which is a shorthand for an if-then-else statement. Within the valueIfFalse part, we have another ternary operator. This is a nested conditional expression.

What this expression does is to check if the value is a whole number (i.e., has no decimal part). If it is, it adds .00 to the value. If it is not a whole number, it checks if it has one decimal place by multiplying it by 10 and checking if that is a whole number. If it has one decimal place, it adds a 0. If it has two decimal places, it adds nothing (an empty string). Which results in this chart:

Picta label formatter

The picta label formatter works the same way as the axis label formatter, but there is more data available to you. Instead of {item}, you use {1} to access the data in the first column and {2} to access the data in the second column, etc.

Lets look at this pie chart showing website visits by referrer:

You can edit the formatter by opening the picta panel (pie in this case), enabling the label and clicking on the formatter input field. To show both the referrer and the amount of visits in the label, you can use this formatter:

Please note that we use two lines in the formatter, which reflects in the labels on the chart.

You could also choose to show the default label by not enabling the label at all, and show a different label when hovering over the pie slices. To do this disable the label and enable emphasis. Within the emphasis panel you can enable the label and set the formatter there. Using the same formatter as above will show the referrer and visits when hovering over the pie slices.

Tooltip formatter (trigger: 'item')

The tooltip formatter works similarly to the picta label formatter, it also uses {1}, {2}, etc. to access the data columns. But with the tooltip formatter you may even add html elements to format the tooltip content.

We will use a heatmap chart showing the Stranger Things TV series ratings per season and episode as an example, the data for this chart contains the following columns:

1. Season
2. Episode
3. Title
4. IMDb Rating
5. Year
6. Release Date

All these columns are available in the tooltip formatter with {1} to {6}.

When we use the following formatter:

Now hover over the heatmap cells to see the formatted tooltip. As you can see we used HTML <b> tags to make the title and date labels bold, and a <br> tag to add a line break between the title and date.

We can further enhance the tooltip by using a HTML table to align the labels and values:

Resulting in this tooltip when hovering over the heatmap cells:

Tooltip formatter (trigger: 'axis')

The tooltip formatter for axis tooltips works a bit differently than the item tooltip formatter. Here you do not have access to individual data columns using {1}, {2}, etc. Instead, you can use a special syntax to loop through all the series data for the given axis value.

which results in this tooltip when hovering over the horizontal axis values:

Color highlighting

As you might have noticed, the formatter text area has syntax highlighting to help you write the formatter code. Here is a quick overview of the colors used:

Operators

The formatter supports the following arithmetic operators:

Functions

In addition to the arithmetic operations, the formatter supports several functions to manipulate and format data values.

Tip

Just like all other dialogs in DataPicta, you can move the formatter dialog by dragging the title bar. If you screen is large enough you can move the dialog away from the chart to see the changes in real-time while you edit the formatter.

Debugging

If your formatter does not work as expected, you can use {print(item)} within the formatter to output the value to the console for debugging purposes. This can help you understand what value is being processed and identify any issues with your formatter logic. The output appears in the browser console, which you can open with F12 or Ctrl+Shift+I (or Cmd+Option+I on Mac). For label formatters, the output will appear immediately. For tooltip formatters, you need to hover over the chart elements to trigger the output.

In the examples above we used {1}, {2}, etc. to access data columns. This is just a shorthand for {item.data[0]}, {item.data[1]}, please note that the index is zero-based when using the item.data syntax.