Skip to main content
Version: 0.4.3

Configuring data

This package contains a sole component named DashJsonGrid. To use this component, we can start from this minimal example:

minimal_example.py
import dash
import dash_json_grid as djg


app = dash.Dash("demo")
app.layout = djg.DashJsonGrid(
data=1
)

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

Sanitization

Simply change the data property of DashJsonGrid, users will be able to view the results:

...
app.layout = djg.DashJsonGrid(
data=[1]
)
...

We can find that the result does not change compared to the minimal example. That's because all literal value that is passed to data but not a Sequence or a Mapping will be automatically converted to a sequence with only one element. In other words, data=1 will be sanitized as data=[1] implicitly.

tip

Dash will not automatically serialize a customized class. Therefore, if the data you provide contains instances of customized classes, a good way is to convert the instances to str.

Render a sequence

The following example modifies the data property and renders a sequence.

...
app.layout = djg.DashJsonGrid(
data=[1, 2.0, "3", None, True]
)
...

A sequence containing literal or unstructured values will be rendered as a vertical list containing an index column and a value column.

Render a mapping

The following example modifies the data property and renders a mapping.

...
app.layout = djg.DashJsonGrid(
data={"key1": 1, "key2": "str", "key3": True, "key4": None}
)
...

A mapping not belonging to a table will be rendered as a vertical list containing a key column and a value column.

Render a table

The following example modifies the data property and renders a table.

...
app.layout = djg.DashJsonGrid(
data=[
{"key1": 1, "key2": "str"},
{"key1": True, "key2": None},
{"key1": 3.0},
{"key1": False, "key2": None, "key3": 4.0},
{"key5": "?"},
]
)
...

A table will be constructed when a Sequence is detected and all of its elements are Mappings. In this case, the Sequence itself will not be rendered as an indexed list, and the members of the sequence will not be rendered as key-value lists. Instead, the whole list will be rendered as a table.

The indicies of the table are just corresponding to the elements in the sequence. The columns of the table is a union of all appeared keywords in all elements. For any row, if some keywords are missing, the value will be marked by undefined.

Render the complicated, nested, and multi-level data

The following example shows the performance of rendering the complicated data. It has multiple levels, and the table, sequence, and mapping can be nested in each other. DashJsonGrid will automatically detect how to properly render the data, so the users can get rid of formatting the complicated data into nested HTML components.

...
app.layout = djg.DashJsonGrid(
data={
"literal": 1,
"sequence": [1, 2.0, "3", None, True],
"mapping": {"key1": 1, "key2": "str", "key3": True, "key4": None},
"table": [
{"key1": 1, "key2": "str"},
{"key1": True, "key2": None},
{"key1": 3.0},
{"key1": False, "key2": None, "key3": 4.0},
{"key5": "?"},
],
"not-a-table": [
{"val1": 1},
2.0,
["a", "b", "c"],
[{"key1": ["a"], "key2": 2, "key3": {"val1": True}}],
[{"key3": 1}],
],
}
)
...

Expand a part of the data

For a complicated data property like the above example, it may be necessary to expand a small part of the data by default. The following example shows how to configure this partial expanding feature by the property default_expand_key_tree:

...
app.layout = djg.DashJsonGrid(
data=...,
default_expand_key_tree={"not-a-table": {"2": True}}
)
...

Note that the leaf node of default_expand_key_tree should be boolean values. Any leaf node set by True will let that route expanded.

Alternative initializations

The data can be fed into the component by another two initialization methods.

Users can also initialize the component by a JSON string:

app.layout = dash_json_grid.DashJsonGrid.from_str(
json_string: str, ...
)

By using this method, the first argument json_string will be a string that can be decoded by a JSON decoder. In this case, data should not be used.

warning

Note that json_string and json_file are translated to data during the initialization. Therefore, json_string or json_file will not be properties that can be accessed by a callback.