docs: split up into multiple files and clarify examples

[LordSimal]

Relates to #323 and #136

[codecov]

Codecov Report

Merging #324 (48b6587) into master (1994e97) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #324   +/-   ##
=========================================
  Coverage     94.13%   94.13%           
  Complexity      224      224           
=========================================
  Files            19       19           
  Lines           580      580           
=========================================
  Hits            546      546           
  Misses           34       34           

Help us with your feedback. Take ten seconds to tell us how you rate us.

[raul338]

This sounds like I used on #249
It can be done using the value filter

$manager->value('category_id', [
    'multiValue' => true,
    'multiValueSeparator' => ',',
    'field' => ['Categories.id'],
    'beforeProcess' => function (Query $query, array $args, $filter) {
        $query->innerJoinWith('Categories');
    },
]);

so in the URL you can pass category_id=1,2,3,4 (and I belive an array too)

[LordSimal]

Indeed this does work as well.
But in my opinion your solution is thinking quite "out of the box" just with the docs given currently.
Especially for newer people who are not that accustomed to the framework.
Or is there a benefit to your approach?

[raul338]

My code is combining two filter config in the docs beforeProcess and Value Filter

The code serves as an example of the value filter.
For the callback I would suggest the example would make use of the other parameters

[LordSimal]

I didn't mean that I don't understand your example 😉
I was just saying that especially for newcomers a little code block explaining how to filter HABTM associations works can go along way instead of having them reading through all filters and options to let them figure it out themselves.

Since the docs/README.md is already quite big I wouldn't mind splitting it up into several pages, so something like

• Basic Configuration
• All default filters incl. examples
• Additional docs (like everything after the Optional Fields in the current Readme)

[raul338]

I agree it would be better to show examples, or repeat titles/sections like it's done on the crud plugin documentation

[ndm2]

Since the docs/README.md is already quite big I wouldn't mind splitting it up into several pages

All the options on themselves can be quite overwhelming, so a restructuring of the docs would be quite nice I think, dedicated sections for all filters, each with an example would be very helpful especially for new users.

[LordSimal]

This is my first version of the split up doc including the more simpler, explicit filter examples:
https://github.com/LordSimal/search/tree/how-to-use-closure/docs

[LordSimal]

So are there any other objections if my approach of splitting up the docs is good/bad?

[ADmad]

The details are collapsed by default and I don't like the fact that an additional click is required to view the code e.g.

[LordSimal]

since most of these code snippets are only one liners I can actually remove that collapsible element.