Documentation of converters feature is very sparse

Have you looked at http://grails.org/Converters+Reference ? Are there any facts missing that should be covered?

Feedback and suggestions are most welcome!

Cheers, sigi

I think several things could improve the documentation:

• how do you execute a deep conversion as opposed to a flat conversion?

• how do you use parse? (There are no examples of reverse conversion.)

• explain the meaning of the "Codecs" section (or remove it if it has no value).

I also think this documentation should be added to the official docs as requested in GRAILS-3095.

Brad,

thanks for your feedback. I've updated the wiki page... It would be nice, if you can take a look if the changes are understandable.

I agree that it should be added to the user guide.

Cheers, sigi

hi siegfried

You can add your information to the docs by checkout https://svn.codehaus.org/grails/trunk/grails-doc/

The syntax is roughly the same as the wiki so its easy to port over

Hi Graeme,

I had that already in mind. Should I add a dedicated "Converters" chapter to the below "Plug-ins"?

Cheers, sigi

I would put it in the REST section http://grails.org/doc/1.0.x/guide/13.%20Web%20Services.html#13.1%20REST

Siegfried,

The changes to the docs are great. There are a couple more things that might be useful to add:

• CODECS section: is the default the regular converter or deep converter? Is there a way to change between regular and deep?

• Parse section: can the example be extended to show how to take the parsed contents and update and/or create a domain object? (I'm unclear whether or not there is any real support for this. I currently have hand written code to convert parsed XML into domain objects. Even if there is no real support for this then it would still be good to explicitly say so – I think it is a common concern. I've been looking at the code and XStream docs and it seems that XStream supports decoding but not the Grails XML converters. Unless I'm missing something.)

Thanks,

Brad

My two cents is that a new Converters section is warranted for the following reasons:

• Converters are already relevant to (and should be cross referenced from):
  • 6.1.7 XML and JSON Responses
  • 6.7.4 Ajax on the Server
  • 6.8 Content Negotiation
  • 13.1 REST - Marshaling
• Converters have application beyond Ajax and REST. (In my case I'm interested in synchronizing domain objects to/from XML files.) If the documentation remains inside Ajax or REST sections is will most likely be overlooked by users that would like to do conversion that is unrelated to Ajax or REST.

There is no scope / time to resolve these remaining lower priority issues for 1.2 so moving to 1.3

for 1.2 final only issues considered blocking will now be fixed

There is an excellent article on the topic here http://jwicz.wordpress.com/2011/07/11/grails-custom-xml-marshaller/ that should be rolled into the documentation

It would make sense for this to be fixed for v2.2 with the planed additional REST support for that version of Grails.