Update Aggrid docs to explain javascript callback handling and details

[csrubin]

Recently, I spent a lot of time trying to figure out why my aggrid element was not updating properly, and seemingly not successfully calling run_grid_method() but it was failing "silently" so I couldn't tell what was wrong. Turns out, at first I wasn't defining getRowId in the grid options (took a while and lot of aggrid documentation searching to see that getRowId() is required for using the grid/row API. When that didn't work, it took even longer to realize that I was missing the preceding colon in options, and I did not understand the necessary usage of params. It did not help that AI was producing different responses, couldn't seem to find the error.

Wrong:
"getRowId": "params.data.id"

Correct:
":getRowId": "params => params.data.id"

All that to say, I think there is benefit in adding to the aggrid documentation so others don't fight these issues. For what it's worth, the docs do accurately show getRowId and params usage, but lacks explanation and clear definition that it is required for things to work.

• run_grid_method and run_row_method REQUIRE getRowId to be defined in options so aggrid doesn't get confused about which row to operate on
• keys in options dict that are preceded by a colon are javascript functions, and the keys' values are to be evaluated as javascript expression
• If defining a javascript func, the key's value must use params, sometimes needing arrow operator => depending on the situation. WHEREAS, other options (e.g., rowClassRules) that are not preceded by a colon can use data.<field> to access attributes of the grid

Separately, I think there is also value in giving tips for debugging when aggrid is not behaving as expected, which can be done with browser-side debugging and console logging.

Here's a link to a (pretty long) conversation I had with ChatGPT where I was finally able to figure out my issues. It gave a lot of really helpful information once I figured out what to ask for. If it is decided to add to the documentation, this conversation can probably help get that going.

[falkoschindler]

Hi @csrubin, thanks for writing this up in such detail! Getting stuck on a silent failure is frustrating, and you're right that the AG Grid page shows :getRowId and params without ever explaining them. Let's fix that.

Two small corrections first, so the docs end up accurate:

• run_grid_method doesn't need getRowId at all (the "Select all" demo works without it). And run_row_method falls back to the row index as a string if getRowId isn't defined. What does need a stable row ID is anything that has to match a row sent from Python against a row already in the grid: applyTransaction with update/remove, preserving selection across updates, and run_row_method with a meaningful ID. That's probably what bit you.
• The params name isn't special. A :-prefixed value is simply evaluated as JavaScript on the client, so ':getRowId': 'params => params.data.id' works because it evaluates to a function, and 'getRowId': 'params.data.id' fails because AG Grid receives a plain string where it expects a function. The confusing part is that AG Grid also has its own string expressions, e.g. 'cellClassRules': {'bg-red-300': 'x < 21'} in our docs, which AG Grid evaluates itself without any colon. Two different mechanisms that look alike.

Here's what I would change (roughly in order of value):

1. A new "JavaScript expressions in options" section on the AG Grid page, right after the introduction: the : prefix, that the value can be any JavaScript expression (a callback for getRowId/getRowHeight/valueFormatter, but also an object or a regular expression), and how it differs from AG Grid's own expression strings like x < 21. One demo with :getRowId and a :valueFormatter should cover it.
2. Make the "Run row methods" demo explicit about getRowId: which operations need it and that the fallback is the row index. Same sentence in the run_row_method docstring, which currently only says "as defined by the getRowId option".
3. A short "Debugging" text block at the end of the page: open the browser console; NiceGUI logs Method "..." not found for unknown grid/row methods and Error while converting :... attribute to function for broken expressions; use .on('someEvent', js_handler='console.log') to inspect event payloads (already documented for rowClicked); and use ui.run_javascript(f'return getElement({grid.id}).api...') to poke at the grid API directly.
4. Make the failure less silent: run_row_method with an unknown row ID currently does nothing at all, because getRowNode() returns undefined and that is swallowed. A one-liner in aggrid.js that logs an error like Row "..." not found would have saved you a lot of time. That's a tiny code change in the same PR.

Would you like to open a PR for this? You already did the hard part, which is understanding what was missing. The docs live in website/documentation/content/aggrid_documentation.py (demo functions with a Markdown docstring), python main.py runs the site locally, and CONTRIBUTING.md has the setup. Points 1 to 3 are pure docs; point 4 is optional if you'd rather leave the JavaScript to us. If you don't have the time, no problem, just say so and we'll take it from here. ※

[falkoschindler]

Hi @csrubin, we went ahead and put the above into a PR: #6362. It adds a section explaining the colon-prefixed JavaScript expressions, clarifies where the row ID for run_row_method comes from, adds a debugging section to the AG Grid page, and makes run_row_method log an error for an unknown row ID instead of doing nothing. One thing we found on the way: a colon-less 'getRowId': 'params.data.name' isn't silent in the browser, AG Grid throws a TypeError and shows no rows, it's only silent from Python's side. The docs now say so, which hopefully points the next person at the browser console sooner. Thanks again for the detailed write-up, it made this easy to fix. ※

[csrubin]

Hi @falkoschindler, sorry for being MIA. I tried setting up the dev environment to start a PR but got distracted and forgot. Thanks for pushing this through! Happy to continue writing detailed discussions in the future :)

[falkoschindler]

PR #6362 has just been released in version 3.18 ✔️