DataTables / DataTables/SearchPanes

documentation: ajax, array-access and code-base abbreviations

Open
#27 1 comment 0 reactions 0 assignees View on GitHub

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:

Both of them explain the default behavior and the particular semantics of columns.render and its special <string> format for array-access but:

  1. ... 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.

  1. But the main problems comes with server-side: It seems the above orthogonal rendered 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.

  2. 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?

  3. 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)

  1. 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].filter is probably passed down to DT before draw() happen.

I expected it here:
https://github.com/DataTables/SearchPanes/blob/81b3bb1b06679e050270e04d4ce1566c1d5a3c79/src/SearchPaneST.ts#L141

or here:
https://github.com/DataTables/SearchPanes/blob/81b3bb1b06679e050270e04d4ce1566c1d5a3c79/src/SearchPane.ts#L1706-L1723

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.