Value Formatters

Value formatters allow you to format values for display. This is useful when data is one type (for example, numeric) but
needs to be converted for human reading (for example, putting in currency symbols and number formatting).
Note that it does not change the data, only how it appears in the grid.

Note that to use valueFormatter function when exporting data, the Column Definition
property useValueFormatterForExport must be set to True which is the default
(See Value Formatter for Export).

If using Cell Data Types, value formatters are set by
default to handle the display of each of the different data types.

You can supply your own custom function for displaying values, or you can use the functions defined in d3-format and
the d3-time-format libraries (See D3 Value Formatters).

Value Formatter vs Cell Renderer

A Cell Renderer allows you to put whatever HTML you
want into a cell. This sounds like value formatters and a cell renderers have cross purposes, so you may be wondering,
when do you use each one and not the other?

The answer is that value formatters are for text formatting and cell renderers are for when you want to include HTML
markup and potentially functionality to the cell. So for example, if you want to put punctuation into a value, use a
value formatter, but if you want to put buttons or HTML links use a cell renderer. It is possible to use a combination
of both, in which case the result of the value formatter will be passed to the cell renderer.

Value Formatter Example

In this example note that:

import dash_ag_grid as dag
from dash import Dash, html, dcc

app = Dash(__name__)

rowData = [
    dict(account='account a',  balance=522.31, name='Homer', grade="25"),
    dict(account='account b',  balance=1607.9, name='Marge', grade=90),
    dict(account='account c',  balance=-228.41, name='Lisa', grade=100),
]


columnDefs = [
    {
        "field": "account",
        "valueFormatter": {"function": "(params.value).toUpperCase();"},
    },
    {
        "field": "balance",
        "valueFormatter": {"function": "'$' + (params.value)"},
    },
    {
        "field": "name",
        "valueFormatter": {"function": "`Hello ${params.value}!`"},
    },
    {
        "field": "grade",
        "valueFormatter": {"function": "params.value >= 60 ? 'Pass' : 'Fail'"},
    },

]

defaultColDef = {
    "resizable": True,
    "editable": True,
}

app.layout = html.Div(
    [
        dcc.Markdown(
            "This demonstrates some basic string formatting functions"
        ),
        dag.AgGrid(
            id="value-formatter-grid-example-basic",
            columnDefs=columnDefs,
            rowData=rowData,
            columnSize="sizeToFit",
            defaultColDef=defaultColDef,
            dashGridOptions={"singleClickEdit": True},
        ),
    ],
    style={"margin": 20},
)


if __name__ == "__main__":
    app.run(debug=True)

This demonstrates some basic string formatting functions

Value Formatter for Export

By default, the grid uses the value formatter when performing other grid operations that need values in string format.

This behaviour can be prevented by setting the column definition property useValueFormatterForExport=False (note
this does not apply to rendering).

useValueFormatterForExport applies to Copy/Cut, Fill Handle, Copy Range Down,
CSV Export, and Excel Export.

Using a value formatter for export is normally used in conjunction with Using a Value Parser for Import, where
a Value Parser is defined that does the reverse of the value
formatter.

The following example shows the difference disabling or not the Value Formatter when exporting the data in CSV:

import dash_ag_grid as dag
from dash import Dash, html, dcc, callback, Input, Output

app = Dash(__name__)

rowData = [
    dict(account='account a', balance=522.31, name='Homer', grade="25"),
    dict(account='account b', balance=1607.9, name='Marge', grade=90),
    dict(account='account c', balance=-228.41, name='Lisa', grade=100),
]

columnDefs = [
    {"field": "account", "valueFormatter": {"function": "(params.value).toUpperCase()"}},
    {"field": "balance", "valueFormatter": {"function": "'$' + (params.value)"}},
    {"field": "name", "valueFormatter": {"function": "`Hello ${params.value}!`"}},
    {"field": "grade", "valueFormatter": {"function": "params.value >= 60 ? 'Pass' : 'Fail'"}},
]

app.layout = html.Div(
    [
        dcc.Checklist(
            id='chk-value-formatters-export-csv',
            options={'value-formatters-export-off': 'Disable Value Formatter For Export'},
            value=[],
        ),
        html.Button("Download CSV", id="btn-value-formatters-export-csv", style={'margin': 10}),
        dag.AgGrid(
            id="grid-value-formatters-export-csv",
            rowData=rowData,
            columnDefs=columnDefs,
            columnSize="sizeToFit",
            csvExportParams={"fileName": "ag_grid_test.csv"},
        ),
    ],
)


@callback(
    Output("grid-value-formatters-export-csv", "exportDataAsCsv"),
    Input("btn-value-formatters-export-csv", "n_clicks"),
    prevent_initial_call=True,
)
def export_data_as_csv(_):
    return True


@callback(
    Output("grid-value-formatters-export-csv", "defaultColDef"),
    Input("chk-value-formatters-export-csv", "value"),
)
def disable_value_formatter_for_export(options):
    if 'value-formatters-export-off' in options:
        return {"useValueFormatterForExport": False}
    return {"useValueFormatterForExport": True}


if __name__ == "__main__":
    app.run(debug=True)