Rendering Data
Handler actions can return data back to its callers in many different formats. Either to create RESTFul services, or just send data that's not HTML back to the user. The different usages can be:
Complex Data
HTML
Rendered Data via
event.renderData()
Complex Data
By default, any complex data returned from handler actions will automatically be marshaled to JSON:
Simple as that. ColdBox detects the complex object and tries to convert it to JSON for you automatically.
renderdata
Action Annotation
renderdata
Action AnnotationIf you want ColdBox to marshall the content to another type like XML or PDF. Then you can use the renderdata
annotation on the action itself. The renderdata
annotation can be any of the following values:
json
jsonp
jsont
xml
html
text
pdf
renderdata
Component Annotation
renderdata
Component AnnotationYou can also add the renderData annotation to the component definition and this will override the default of JSON. So if you want XML as the default, you can do this:
$renderData Convention
If the returned complex data is an object and it contains a function called $renderData(),
then ColdBox will call it for you automatically. So instead of marshaling to JSON automatically, your object decides how to marshal itself.
Native HTML
By default if your handlers return simple values, then they will be treated as returning HTML.
event.renderData()
Using the renderdata()
method of the event object is the most flexible for RESTFul web services or pure data marshaling. Out of the box ColdBox can marshall data (structs, queries, arrays, complex or even ORM entities) into the following output formats:
XML
JSON
JSONP
JSONT
HTML
TEXT
PDF
WDDX
CUSTOM
Here is the method signature:
Below are a few simple examples:
As you can see, it is very easy to render data back to the browser or caller. You can even choose plain and send HTML back if you wanted to.
Render PDFs
You can also render out PDFs from ColdBox using the render data method. The data argument can be either the full binary of the PDF or simple values to be rendered out as a PDF; like views, layouts, strings, etc.
Renderdata With Formats
The renderData()
method also has two powerful arguments: formats & formatsView
. If you currently have code like this:
Where you need to param the incoming format extension, then do a switch and do some code for marshalling data into several formats. Well, no more, you can use our formats argument and ColdBox will marshall and code all that nasty stuff for you:
That's it! ColdBox will figure out how to deal with all the passed in formats for you that renderdata
can use. By convention it will use the name of the incoming event as the view that will be rendered for HTML and PDF; implicit views. If the event was users.list, then the view would be views/users/list.cfm. However, you can tell us which view you like if it is named different:
If you need to redirect for html events, you can pass any arguments you normally would pass to setNextEvent
to formatsRedirect
.
Custom Data Conversion
You can do custom data conversion by convention when marshalling CFCs. If you pass in a CFC as the data
argument and that CFC has a method called $renderdata()
, then the marshalling utility will call that function for you instead of using the internal marshalling utilities. You can pass in the custom content type for encoding as well:
The CFC converter:
In this approach your $renderdata()
function can be much more customizable than our internal serializers. Just remember to use the right contentType argument so the browser knows what to do with it.
Last updated