Extends filterUserField to pass the resource to all fieldGates

Background

Extends filterUserField to pass the resource to all fieldGates, to allow for context-dependent decisions.

Also documents the use of fieldGates, and adds some hints about using relationships in defaultFields and allowedFields.

Action Plan / Actions Taken

• Extended filterUserField to pass the resource to all fieldGates, so that gates with context-dependent logic can be used.
• Added documentation for gatedFields.
• Added mentions of the need to reference related resources in $defaultFields and/or $allowedFields.

Added tests?

• Yes, of course
• No, and here's why: no test suite to fit them into!
• I need help writing tests

Implications

• None

Setup

• Can be tested with feature/include_artworks_when_fetching_purchase in the Art Money API project.

How to test

• Code review.
• Review the new/updated tests carefully: are they correct, sufficient, and passing?
• Use feature/include_artworks_when_fetching_purchase to test it. Play around with the gate definition to allow/deny access.
• Try and break it!