Dancer2
Dancer2 copied to clipboard
PerlDancer
Serialization documentation should point more clearly to 'send_as' for routes (templates) that may need them.
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.
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
Could you be specific on where? Prominently is good, but where would it be prominent enough for you?
"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.
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.