Major Improvements & Changes pushed to Recess Edge

[Kris Jordan]

Folks,

Just merged the 'content-negotiation' branch on Recess Edge (http://www.github.com/recess/recess) with the master branch. There are some pretty big changes so I wanted to give an overview here and on the blog. I encourage you to ask any questions

#1) New View Selection System based on Requested Format(s)

The new native view system looks for an application's view template by matching a format to a file-extension. So, for example, if a visitor requests '/foo.xml' and your controller returns a view-name of 'foo', Recess now looks for the view template foo.xml.php - the same goes with json, rss, pdf, etc. For the default html format there is no additional extension, it's still just foo.php.

What about automatic JSON? It is no longer turned on by default (though, if you are using existing code, it should still work in version 0.20 but is now considered deprecated and will not be supported in 0.30). Recess has a new, more advanced mechanism for selecting views. Multiple views can be registered with a controller with the new !RespondsWith annotation, it looks like this:

/**

 * !RespondsWith Native, Json

 * !Prefix my/

 */

class MyController extends Controller {

   function foo() { }

}

The !Prefix annotation will be discussed shortly. Native and Json are both views with class names NativeView, JsonView respectively. These form the prioritized list which Recess will use to find a view. Suppose 'my/foo.json' is requested by the client. In this case Native view will be asked first 'can you render this response?', if the view template 'my/foo.json.php' exists then answer is yes and it will render and we're done. If that file does not exist, though, then the new JsonView will be asked 'can you render this response?' and it can always render  a json request so it will. If you *always* wanted to use automatic-json for json requests then you could simply reverse the order: Json, Native. This avoids the cost of checking the file system for a json template file.

A list of the supported formats is provided in the following section.

#2) More RESTful Goodness with Accept-based Content-Negotiation

Recess now has support for parsing the HTTP Accept header (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for content-negotiation! This means for folks using RIAs and smart-clients you can interact with your Recess applications truer to the way HTTP intends. Instead of appending a format like '.json' to a URL your clients can now use 'Accept: application/json'. Here are a list of supported mime-types and the formats they map to:

html = text/html, application/xhtml+xml 

xml = application/xml, text/xml, application/x-xml 

json = application/json, text/x-json application/jsonrequest 

js = text/javascript, application/javascript, application/x-javascript 

css = text/css 

rss = application/rss+xml 

yaml = application/x-yaml, text/yaml 

atom = application/atom+xml 

        pdf = application/pdf

text = text/plain

png = image/png 

jpg = image/jpeg, image/pjpeg 

gif = image/gif

form = multipart/form-data

url-form = application/x-www-form-urlencoded

csv = text/csv

In the rare case you need to accept a MIME-types not listed above you can add it to the mix with the following: MimeTypes::register('foo', 'application/foo'); The second argument can also be an array to support multiple mime types that refer to the same format.

#3) New Controller Annotations: !Prefix

It has become a common case in Recess development for the view and route prefix to be the same. A new annotation allows you to specify both with a single annotation:

!Prefix foo/     (now relative routes and views are prefixed with foo/)

!Prefix Routes: /, Views: home/      (allows you to set them individually)

===

Note: Deprecated Controller Annotations: !View, !RoutesPrefix

The !View annotation is still supported in 0.2 but is deprecated and will be unsupported in v0.3 - It is replaced by !RespondsWith

The !RoutesPrefix annotation is still supported in 0.2 but is deprecated and replaced by !Prefix

Warning: Not-yet-backwards-compatible: PUTing / POSTing JSON

Work is still being done on data that is PUT/POSTed to the server with alternate MIME-types. For folks who depend on POSTing/PUTing JSON please hold off on pulling the latest bits from Edge. This is coming soon and will allow other content-type parsers (XML, for example) to be plugged-in. We're also decoupling the format of input from output, so, for example, you could post JSON and ask for HTML back.

===

We're getting really close to the 0.2 release and I ask you for help in testing the bits, reporting and submitting patches for bugs, and contributing to the documentation. Can't wait to get 0.2 out the door!

-Kris

[Josh Lockhart]

Kris,

Thanks for the awesome update! There are a few things I did catch though:

1. The new "!RespondsWith" annotation is actually "!RespondWith". I would prefer "!RespondsWith" since that seems to describe the controller rather than tell it to do something.
2. I would still like you to add support for "template.html.php". I know the .html is unnecessary and verbose, but I think it will help visually organize templates if a lot of content types are being used.

But overall, excellent work! This framework just keeps getting better.

Best,

Josh

--
Josh Lockhart
Web Developer, New Media Campaigns
http://www.newmediacampaigns.com
Email: jo...@newmediacampaigns.com

[Kris Jordan]

Josh,

Thanks for the catch with !RespondsWith - I agree with you completely that this is an annotation describing controller, not a command. Not sure how this slipped but it has been changed in the source tree and now matches the examples shown in the email and on the blog. I have pushed the changeset to GitHub - anyone who has pulled the new bits and been playing around should do a search/replace on their controllers for 'RespondWith' => 'RespondsWith'.

Also, agree that '.html.php' should be an option as it is more explicit. Plain old '.php' is supported for backwards compatibility currently but '.html.php' should be available and preferred. The only real dilemma is it could incur an additional unnecessary disk hit checking if either exists. I think a good case could be made for '.html.php' to be the preferred option as it eliminates a special case and retains symmetry. Will keep thinking on this, expect to see support soon.

Kris