Praxis 0.19 is out!

[Josep Blanquer]

All,

 ...and just in time for Holiday gifts, we bring you Praxis 0.19. :)

This is a release with a fairly large number of changes, fixes and features especially located in its dependent gems. Because of that large of a change we've let it sit in the master branch for a little bit longer than usual.

Strictly, there aren't any incompatible changes to the published (i.e. documented) interfaces. However there were pretty big internal changes that if somebody was relying on (and we all know that in Ruby that is not unlikely), some things could potentially break. At the same time, though, since we're still in the 0.x series, we thought that bumping the major version to 1.0 was overkill.

Anyway, I'll let the  Changelog do the talking ( pasted below) but, as a quick summary here are the major affected areas:

• Inclusion of generated examples in all supported encodings in the JSON docs:
  
• This comes with a slew of improvements in the doc browser to display and enhance them.
• Introduction to a set of helpers, types and classes that allows trivial implementation of "field selection" in controllers to allow users to very easily define which fields of the media types they want to receive
• In other words: think custom views for media types , that can be as nested/deep as you desire. This is inspired (and compatible) with the basic structure of GraphQL as well as inspired by the "fields" parameters of Google Services and Facebook Graph API.
• These helpers come with an optional deep integration with Praxis mapper which automagically can map the media type fields selected in the API request to the automatic select queries performed in the DB to the field rendering on the output media types. Pretty cool.

To get a better feel of it all, I would highly recommend to look at the example app ( https://github.com/rightscale/praxis-example-app) which has controllers that show all of these helpers and new features.

Happy Praxing!

Josep M.

Changelog: ( https://github.com/rightscale/praxis/blob/master/CHANGELOG.md#0190 )

0.19.0

• Handle loading empty MediaTypeIdentifier values (to return nil)
• Doc browser now displays examples for action responses.
• Added Controller#media_type helper that returns the media_type defined for the current response, or defaults to the one defined by the controller's resource definition.
• Added assorted extensions, all under the Praxis::Extensions module:
  • FieldSelection adds a new type, Praxis::Extensions::FieldSelection::FieldSelector that wraps theAttributor::FieldSelector type and improves the definition of parameters for a set of fields. Must be required explicitly from 'praxis/extensions/field_selection'.
    • The parsed set of fields will be available as the fields accessor of the loaded value.
    • For example, to define a parameter that should take a set of fields for a Person media type, you would define a :fields attribute in the params like: attribute :fields, FieldSelector.for(Person). The parsed fields in the request would then be available with request.params.fields.fields.
  • Rendering adds render and display helper methods to controllers to reduce common boilerplate in producing rendered representations of media types and setting response "Content-Type" headers.
    • Controller#render(object, include_nil: false) loads object into the the current applicable MediaType (as from Controller#media_type) and renders it using the fields provided by Controller#expanded_fields (from theFieldExpansion extension).
    • Controller#display(object, include_nil: false) calls render (above) with object, assigns the result to the current response.body, sets the response's "Content-Type" header to the appropriate MediaType identifier, and returns the response.
    • To use this extension, include it in a controller with include Praxis::Extensions::Rendering.
  • MapperSelectors adds Controller#set_selectors, which sets selectors in the controller's identity_map to ensure any fields and associations necessary to render the :view and/or :fields params specified in the request are loaded for a given model when identity_map.load(model) is called.
    • To use this extension, include it in a controller with include Praxis::Extensions::MapperSelectors, and definebefore callbacks on relevant actions that call set_selectors. For example: before actions: [:index, :show] { |controller| controller.set_selectors }
  • FieldExpansion provides a Controller#expanded_fields helper for processing :view and/or :fields params to determine the final set fields necessary to handle the request.
    • Note: This is primarily an internal extension used by the MapperSelectors and Rendering extensions, and is automatically included by them.
• A slew of Doc browser improvements:
  • Now uses the new JSON format for responses.
  • Traits now get exposed in the doc browser.
  • Now displays examples for requesting actions.
  • Now correctly displays top-level collections in action payloads.
  • Has improved scrolling for the sidebar.
  • Displays more detailed HTML titles.
  • Has been switched back to having a separate page per action, however actions are now shown in the sidebar.
  • Will now display multiply nested resources in a proper hierarchy.
• Fix doc generator to only output versions in index for which we have resources (i.e. some can be nodoc!)