DataTables / DataTables/SearchPanes
documentation: ajax, array-access and code-base abbreviations
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 23
- Forks
- 14
- PR merge metrics
- No merged PRs in 30d
Description
When a column contains a list, the default DataTables/SearchPanes filter implementation use an includes() logic : is the value filtered-one appearing [in the array contained by this column].
The documentation & examples somehow referring to this behavior are:
- https://datatables.net/reference/option/columns.render#Array-access
- https://datatables.net/extensions/searchpanes/examples/advanced/renderArrays.html
Both of them explain the default behavior and the particular semantics of columns.render and its special <string> format for array-access but:
- ... it's difficult to "mimic" this behavior: The solution is actually this:
searchPanes: {
orthogonal: 'sp',
},
render: {
_: '[, ]',
sp: '[]'
}
... but it's really hard to figure out the magic under the hood and how to adapt this to more particular needs because little explanation is provided regarding A. Original data parsing B. filtering logic (DT? SP?). Talking exclusively about rendering doesn't make it clear.
-
But the main problems comes with server-side: It seems the above
orthogonalrendered is simply ignored and the default filtering logic doesn't apply anymore : Only rows whose array-value matches exactly the SP value are returned (data.length == 1 && data[0] == filter-value). I couldn't figure, from the documentation, how to change/bypass this behavior. -
Aside from documenting above point 2, it would be highly desirable to add more explanation about handling
searchPanes.options[field][i].value. It's expected to be a string, but how to handle the case of Array access then? -
Regarding codebase, after quite some time if found this line:
https://github.com/DataTables/SearchPanes/blob/81b3bb1b06679e050270e04d4ce1566c1d5a3c79/src/index.ts#L188-L190
from which one infers the SearchPanesST vs SearchPanes semantic distinction. But I think these abbreviations would desserve either a clarification in the readme file : ST (ServerTotal ??), ISST, ISTV, STC (or better file/class names)
- I searched a long time for the actual filtering logic in order to understand why server-side SearchPanes options would alter the behavior Array-access behavior... without success. It seems this is tightly bound to DataTables itself, where one of the
arrayFilter[i].filteris probably passed down to DT beforedraw()happen.
I expected it here:
https://github.com/DataTables/SearchPanes/blob/81b3bb1b06679e050270e04d4ce1566c1d5a3c79/src/SearchPaneST.ts#L141
But none of them was the actual code-path. This important part of the code would desserve better documentation too.
I hope these comments can help improving either the codebase of the documentation.
I previously expressed these concerns in this forum post: https://datatables.net/forums/discussion/74731/ajax-loaded-searchpanes-options-and-array-values/
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked columns.render and SearchPanes server-side documentation and compare them with src/SearchPaneST.ts and src/SearchPane.ts at the referenced code paths. Trace the array filtering and server-side option handling, then document the client/server behavior, array-access values, and the SearchPanes abbreviations. Done means the relevant examples and code path are explained clearly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100