Serialization documentation should point more clearly to 'send_as' for routes (templates) that may need them.

[starlilyth]

Dancer1 allowed you to mix templates and serialized output fairly seamlessly.
Upgrading to Dancer2, where serialization is applied globally, breaks this templating expectation. While a couple of solutions are suggested, none are so easy as simply using 'send_as' for the minority of either templated or serialized routes, and setting the serializer on or off as appropriate for the majority.

Please mention 'send_as' more prominently in the migration guide and the cookbook when explaining the global nature of serialization, as a way to perform one-offs from whichever global default is chosen.

[shadowcat-mst]

I keep encountering users who run into this problem.

I think that the docs for serialization really need to (a) warn users that the serializer is global, and as such probably shouldn't be used except for a pure-JSON-API app or similar (b) document the two-app solution w/session sharing approach that #dancer often recommends (in the cookbook maybe?) (c) suggest that in many cases send_as is the right answer.

It seems send_as was added after I'd already given up on ever getting you to see sense on this front - I didn't even realise it existed as a solution to this problem until @starlilyth found it in the docs after we'd been trying workarounds and was kind enough to point out I'd missed a trick. It's an excellent solution to what is the single most common problem for new Dancer2 users that I'm helping. It should be advertised prominently

[xsawyerx]

Could you be specific on where? Prominently is good, but where would it be prominent enough for you?

[starlilyth]

"when explaining the global nature of serialization". The serialization section of the migration manual, which currently only contains the single line: "You no longer need to implement the loaded method. It is simply unnecessary." would be an excellent place to explain both. It is the first place I looked when I was having difficulty with serialization, and I was quite disappointed to find practically no information about this significant change in behavior.

[shadowcat-mst]

On Sun, Apr 02, 2017 at 02:39:13AM -0700, Sawyer X wrote: Could you be specific on where? *Prominently* is good, but where would it be prominent enough for you?

Anywhere 'set serializer' is prominently documented, plus the migration POD, would I think be a start.

…

-- Matt S Trout - Shadowcat Systems - Perl consulting with a commit bit and a clue http://shadowcat.co.uk/blog/matt-s-trout/ http://twitter.com/shadowcat_mst/ Email me now on mst (at) shadowcat.co.uk and let's chat about how our CPAN commercial support, training and consultancy packages could help your team.