BC break to apos.get, snippets.get and friends

The apos.get migration

The apos.get method and all of its derivatives such as snippets.get and events.get have been changed effective 6/17/2013. This method now takes four parameters instead of three:

req, criteria, options, callback

Formerly the options parameter was a mishmash of custom options like sort and `and fields passed directly as a MongoDB query. This was clumsy, because the custom options had to be removed before the query as they were processed. And it also made it confusing to write more advanced MongoDB queries.

With this new change, you can pass really fancy MongoDB queries to apos.get and any of its derivatives, and they will still work, even when automatically combined with the new permissions support that ensures we can efficiently fetch (for instance) all of the pages that Bob is allowed to see or that Carol is allowed to edit. And you don't have to lift a finger to get those permissions checks; it's done for you automatically using MongoDB's $and clause.

The criteria parameter now accepts a MongoDB-compatible query object, such as:

// Matches pages in the page tree, as opposed to snippets etc.
{ slug: /^\/$/ }

// Matches events
{ type: 'event' }

While the options parameter accepts custom options as defined in the apos.get documentation. Some of the methods layered atop this method, like events.get, add their own options like upcoming.

"What happens if I don't account for this?"

You'll get lots of "undefined is not a function" errors.

"How do I fix that?"

Go find all of your custom overrides and calls to apos.get, snippets.get, etc. and separate the criteria parameter from the options parameter.

Also look at any customizations you may have made to snippet.addCriteria, snippet.addApiCriteria and derivatives. These methods have also changed to take an additional parameter for the same reasons.

"How do I know what's a criterion and what's an option?"

If it's a simple MongoDB query, something that would work at the MongoDB console prompt, then it belongs in the criteria object. If it's a custom option we added on top of that, it's an option.

See recent commits in the blog and events modules for good examples of how to handle this change correctly.