Ambiguity in datatable tooltip docs

[ybressler]

Specification of providing tooltip_data is unclear in the datatable documentation

Issues with Current:

• dtype = dict
  • This is misleading since a list of dictionaries works too.
• "The property name refers to the column ID." *this is confusing
• "Each property contains a list of tooltips mapped to the source data row index."
  • This makes it sound as if a dictionary with column ids as keys and lists as values would work.
• "The text syntax will be used in that case. tooltip_data has the following type: list of dicts with strings as keys and values of type string | dict containing keys 'delay', 'duration', 'type', 'value'."
  • This last point clarifies the dtype but is at the end of the paragraph and seemingly contradicts itself.

In simpler terms: It's not clear from the documentation whether tooltip_data is a dictionary with lists as values, a single dictionary, or a list of dictionaries. The overlapping language creates room for error. Also, it's not stated if you have to operate column-wise or row-wise.

Additionally, no working example is provided leaving the user to guess.

---

Suggested changes: Here's a more readable and clear version of the information:

• tooltip_data: a list of dictionaries (one for each row) >>
  • keys = column name(s)
  • value:
    • a string for the value to be shown on hover
    • a dictionary:
      • keys = "value", "type", "duration" etc. (according to documentation)
      • values = corresponding values as documented.

Example Code: Here's an example (in long form):

# an empty list for now
tooltip_data = []

# operate rowwise
for i in range(0,df.shape[0]):
    # each row needs a dictionary
    t_row = {}

    for col in ["col_1", "col_2"]: 
        if col in df.columns:
            # add to the row dict
            x = df[col][i]
            t_row[col] = x
            # Alternatively, the following format would work
            # t_row[col] = {"value" : x }

        # don't include empty rows
        if len(t_row)>0:
            tooltip_data.append(t_row)

Thanks for giving this your attention!

[nicolaskruchten]

Thanks for this feedback! I've transferred this issue to the dash-docs repository and I'm tagging @Marc-Andre-Rivet to take a look :)

[Marc-Andre-Rivet]

Probably the same issue as https://github.com/plotly/dash/issues/1205