Improve argument loader docs

rsyring commented 2 years ago

We've had two Slack discussions about how the loaders work:

The docs explain arg loaders but I think there is something missing. It mentions "priority" but I'm not sure what the priority of the loaders is or how it's set. Also, what's the recommended way the loaders should be used and why. For instance, why POST/SESSION instead of just GET.

rsyring commented 2 years ago

Thanks for the update. Although I'm still unclear about something:

Args loaders are run in order of priority, with the highest-priority loader first. The first loader gets a blank MultiDict as input, and then the results are chain-loaded through the list of loaders.

    class GridManager(WebGrid):
        args_loaders = (
            RequestArgsLoader,    # part of the default, takes args from URL query string
            RequestFormLoader,    # use args present in the POSTed form
            WebSessionArgsLoader, # part of the default, but lower priority from the form POST
        )

Something about this is unintuitive to me. RequestArgsLoader has priority three? So it's the "highest" priority and ran first? But it's results are fed to RequestFormLoader? I would intuit that RequestFormLoader would run filling the MultiDict with it's values, overriding what was there initially. But, the example indicates that isn't the case. Do the request loaders check the MultiDict input for an value and not set it if the key is already present?

guruofgentoo commented 2 years ago

I think I'll drop the wording about priority, as that's nowhere in the code. All I meant was that the first loader in the list gets the first look at args, and loaders down the chain inherit the previous set of args and can decide what to do with them.

The later loaders can honor the earlier set, or not, depending on the function. For instance, the web session loader needs to know if there were values on the request (either GET or POST) that would override what's stored in the session. So those request args loaders get run first (which in my mind meant higher priority). But the last loader gets the final say on the args that get sent to the grid, so that could be construed as priority as well, I suppose.

level12 / webgrid

Improve argument loader docs #158