root/Catalyst-View-JSON/trunk/lib/Catalyst/View/JSON.pm

Revision 2204 (checked in by miyagawa, 13 years ago)

Checking in changes prior to tagging of version 0.17. Changelog diff is:

=== Changes
==================================================================
--- Changes (revision 6486)
+++ Changes (local)
@@ -1,5 +1,10 @@

Revision history for Perl extension Catalyst::View
JSON

+0.17 Wed Apr 25 16:04:44 PDT 2007
+ - Switch to Module::Install
+ - include JSON.pm in inc/ for testing.
+ (Thanks to Matt S Trout)
+

0.16 Tue Apr 17 20:11:38 PDT 2007

- Added JSON
Any dependency

  • Property svn:keywords set to Id Revision
Line 
1 package Catalyst::View::JSON;
2
3 use strict;
4 our $VERSION = '0.17';
5
6 use base qw( Catalyst::View );
7 use Encode ();
8 use NEXT;
9 use Catalyst::Exception;
10 require JSON::Any;
11
12 __PACKAGE__->mk_accessors(qw( allow_callback callback_param expose_stash encoding json_dumper no_x_json_header ));
13
14 sub new {
15     my($class, $c, $arguments) = @_;
16     my $self = $class->NEXT::new($c);
17
18     for my $field (keys %$arguments) {
19         next if $field eq 'json_driver';
20         if ($self->can($field)) {
21             $self->$field($arguments->{$field});
22         } else {
23             $c->log->debug("Unknown config parameter '$field'");
24         }
25     }
26
27     my $driver = $arguments->{json_driver} || 'Syck';
28     $driver =~ s/^JSON:://; #backward compatibility
29
30     eval {
31         JSON::Any->import($driver);
32         $self->json_dumper(sub { JSON::Any->objToJson($_[0]) });
33     };
34
35     if (my $error = $@) {
36         die $error;
37     }
38
39     return $self;
40 }
41
42 sub process {
43     my($self, $c) = @_;
44
45     # get the response data from stash
46     my $cond = sub { 1 };
47
48     my $single_key;
49     if (my $expose = $self->expose_stash) {
50         if (ref($expose) eq 'Regexp') {
51             $cond = sub { $_[0] =~ $expose };
52         } elsif (ref($expose) eq 'ARRAY') {
53             my %match = map { $_ => 1 } @$expose;
54             $cond = sub { $match{$_[0]} };
55         } elsif (!ref($expose)) {
56             $single_key = $expose;
57         } else {
58             $c->log->warn("expose_stash should be an array referernce or Regexp object.");
59         }
60     }
61
62     my $data;
63     if ($single_key) {
64         $data = $c->stash->{$single_key};
65     } else {
66         $data = { map { $cond->($_) ? ($_ => $c->stash->{$_}) : () }
67                   keys %{$c->stash} };
68     }
69
70     my $cb_param = $self->allow_callback
71         ? ($self->callback_param || 'callback') : undef;
72     my $cb = $cb_param ? $c->req->param($cb_param) : undef;
73     $self->validate_callback_param($cb) if $cb;
74
75     my $json = $self->json_dumper->($data);
76
77     # When you set encoding option in View::JSON, this plugin DWIMs
78     my $encoding = $self->encoding || 'utf-8';
79
80     # if you pass a valid Unicode flagged string in the stash,
81     # this view automatically transcodes to the encoding you set.
82     # Otherwise it just bypasses the stash data in JSON format
83     if ( Encode::is_utf8($json) ) {
84         $json = Encode::encode($encoding, $json);
85     }
86
87     if (($c->req->user_agent || '') =~ /Opera/) {
88         $c->res->content_type("application/x-javascript; charset=$encoding");
89     } else {
90         $c->res->content_type("application/json; charset=$encoding");
91     }
92
93     if ($c->req->header('X-Prototype-Version') && !$self->no_x_json_header) {
94         $c->res->header('X-JSON' => 'eval("("+this.transport.responseText+")")');
95     }
96
97     my $output;
98
99     ## add UTF-8 BOM if the client is Safari
100     if (($c->req->user_agent || '') =~ m/Safari/ and $encoding eq 'utf-8') {
101         $output = "\xEF\xBB\xBF";
102     }
103
104     $output .= "$cb(" if $cb;
105     $output .= $json;
106     $output .= ");"   if $cb;
107
108     $c->res->output($output);
109 }
110
111 sub validate_callback_param {
112     my($self, $param) = @_;
113     $param =~ /^[a-zA-Z0-9\.\_\[\]]+$/
114         or Catalyst::Exception->throw("Invalid callback parameter $param");
115 }
116
117 1;
118 __END__
119
120 =head1 NAME
121
122 Catalyst::View::JSON - JSON view for your data
123
124 =head1 SYNOPSIS
125
126   # lib/MyApp/View/JSON.pm
127   package MyApp::View::JSON;
128   use base qw( Catalyst::View::JSON );
129   1;
130
131   # configure in lib/MyApp.pm
132   MyApp->config({
133       ...
134       'V::JSON' => {
135           allow_callback  => 1,    # defaults to 0
136           callback_param  => 'cb', # defaults to 'callback'
137           expose_stash    => [ qw(foo bar) ], # defaults to everything
138       },
139   });
140
141   sub hello : Local {
142       my($self, $c) = @_;
143       $c->stash->{message} = 'Hello World!';
144       $c->forward('MyApp::View::JSON');
145   }
146
147 =head1 DESCRIPTION
148
149 Catalyst::View::JSON is a Catalyst View handler that returns stash
150 data in JSON format.
151
152 =head1 CONFIG VARIABLES
153
154 =over 4
155
156 =item allow_callback
157
158 Flag to allow callbacks by adding C<callback=function>. Defaults to 0
159 (doesn't allow callbacks). See L</CALLBACKS> for details.
160
161 =item callback_param
162
163 Name of URI parameter to specify JSON callback function name. Defaults
164 to C<callback>. Only effective when C<allow_callback> is turned on.
165
166 =item expose_stash
167
168 Scalar, List or regular expression object, to specify which stash keys are
169 exposed as a JSON response. Defaults to everything. Examples configuration:
170
171   # use 'json_data' value as a data to return
172   expose_stash => 'json_data',
173
174   # only exposes keys 'foo' and 'bar'
175   expose_stash => [ qw( foo bar ) ],
176
177   # only exposes keys that matches with /^json_/
178   expose_stash => qr/^json_/,
179
180 Suppose you have data structure of the following.
181
182   $c->stash->{foo} = [ 1, 2 ];
183   $c->stash->{bar} = [ 3, 4 ];
184
185 By default, this view will return:
186
187   {"foo":[1,2],"bar":2}
188
189 When you set C<< expose_stash => [ 'foo' ] >>, it'll return
190
191   {"foo":[1,2]}
192
193 and in the case of C<< expose_stash => 'foo' >>, it'll just return
194
195   [1,2]
196
197 instead of the whole object (hashref in perl). This option will be
198 useful when you share the method with different views (e.g. TT) and
199 don't want to expose non-irrelevant stash variables as in JSON.
200
201 =item json_driver
202
203   json_driver: JSON::Syck
204
205 By default this plugin uses JSON to encode the object, but you can
206 switch to the other drivers like JSON::Syck. For now, JSON::Syck is
207 the only alternative encoding driver.
208
209 =item no_x_json_header
210
211   no_x_json_header: 1
212
213 By default this plugin sets X-JSON header if the requested client is a
214 Prototype.js with X-JSON support. By setting 1, you can opt-out this
215 behavior so that you can do eval() by your own. Defaults to 0.
216
217 =back
218
219 =head2 ENCODINGS
220
221 Due to the browser gotchas like those of Safari and Opera, sometimes
222 you have to specify a valid charset value in the response's
223 Content-Type header, e.g. C<text/javascript; charset=utf-8>.
224
225 Catalyst::View::JSON comes with the configuration variable C<encoding>
226 which defaults to utf-8. You can change it via C<< YourApp->config >>
227 or even runtime, using C<component>.
228
229   $c->component('View::JSON')->encoding('euc-jp');
230
231 This assumes you set your stash data in raw euc-jp bytes, or Unicode
232 flagged variable. In case of Unicode flagged variable,
233 Catalyst::View::JSON automatically encodes the data into your
234 C<encoding> value (euc-jp in this case) before emitting the data to
235 the browser.
236
237 Another option would be to use I<JavaScript-UCS> as an encoding (and
238 pass Unicode flagged string to the stash). That way all non-ASCII
239 characters in the output JSON will be automatically encoded to
240 JavaScript Unicode encoding like I<\uXXXX>. You have to install
241 L<Encode::JavaScript::UCS> to use the encoding.
242
243 =head2 CALLBACKS
244
245 By default it returns raw JSON data so your JavaScript app can deal
246 with using XMLHttpRequest calls. Adding callbacks (JSONP) to the API
247 gives more flexibility to the end users of the API: overcome the
248 cross-domain restrictions of XMLHttpRequest. It can be done by
249 appending I<script> node with dynamic DOM manipulation, and associate
250 callback handler to the returned data.
251
252 For example, suppose you have the following code.
253
254   sub end : Private {
255       my($self, $c) = @_;
256       if ($c->req->param('output') eq 'json') {
257           $c->forward('MyApp::View::JSON');
258       } else {
259           ...
260       }
261   }
262
263 C</foo/bar?output=json> will just return the data set in
264 C<< $c->stash >> as JSON format, like:
265
266   { result: "foo", message: "Hello" }
267
268 but C</foo/bar?output=json&callback=handle_result> will give you:
269
270   handle_result({ result: "foo", message: "Hello" });
271
272 and you can write a custom C<handle_result> function to handle the
273 returned data asynchronously.
274
275 The valid characters you can use in the callback function are
276
277   [a-zA-Z0-9\.\_\[\]]
278
279 but you can customize the behaviour by overriding the
280 C<validate_callback_param> method in your View::JSON class.
281
282 See L<http://developer.yahoo.net/common/json.html> and
283 L<http://ajaxian.com/archives/jsonp-json-with-padding> for more about
284 JSONP.
285
286 =head1 INTEROPERABILITY
287
288 JSON use is still developing and has not been standardized. This
289 section provides some notes on various libraries.
290
291 Dojo Toolkit: Setting dojo.io.bind's mimetype to 'text/json' in
292 the JavaScript request will instruct dojo.io.bind to expect JSON
293 data in the response body and auto-eval it. Dojo ignores the
294 server response Content-Type. This works transparently with
295 Catalyst::View::JSON.
296
297 Prototype.js: prototype.js will auto-eval JSON data that is
298 returned in the custom X-JSON header. The reason given for this is
299 to allow a separate HTML fragment in the response body, however
300 this of limited use because IE 6 has a max header length that will
301 cause the JSON evaluation to silently fail when reached. The
302 recommened approach is to use Catalyst::View::JSON which will JSON
303 format all the response data and return it in the response body.
304
305 In at least prototype 1.5.0 rc0 and above, prototype.js will send the
306 X-Prototype-Version header. If this is encountered, a JavaScript eval
307 will be returned in the X-JSON resonse header to automatically eval
308 the response body, unless you set I<no_x_json_header> to 1. If your
309 version of prototype does not send this header, you can manually eval
310 the response body using the following JavaScript:
311
312   evalJSON: function(request) {
313     try {
314       return eval('(' + request.responseText + ')');
315     } catch (e) {}
316   }
317   // elsewhere
318   var json = this.evalJSON(request);
319
320 =head1 SECURITY CONSIDERATION
321
322 Catalyst::View::JSON makes the data available as a (sort of)
323 JavaScript to the client, so you might want to be careful about the
324 security of your data.
325
326 =head2 Use callbacks only for public data
327
328 When you enable callbacks (JSONP) by setting C<allow_callbacks>, all
329 your JSON data will be available cross-site. This means embedding
330 private data of logged-in user to JSON is considered bad.
331
332   # MyApp.yaml
333   View::JSON:
334     allow_callbacks: 1
335
336   sub foo : Local {
337       my($self, $c) = @_;
338       $c->stash->{address} = $c->user->street_address; # BAD
339       $c->forward('View::JSON');
340   }
341
342 If you want to enable callbacks in a controller (for public API) and
343 disable in another, you need to create two different View classes,
344 like MyApp::View::JSON and MyApp::View::JSONP, because
345 C<allow_callbacks> is a static configuration of the View::JSON class.
346
347 See L<http://ajaxian.com/archives/gmail-csrf-security-flaw> for more.
348
349 =head2 Avoid valid cross-site JSON requests
350
351 Even if you disable the callbacks, the nature of JavaScript still has
352 a possiblity to access private JSON data cross-site, by overriding
353 Array constructor C<[]>.
354
355   # MyApp.yaml
356   View::JSON:
357     expose_stash: json
358
359   sub foo : Local {
360       my($self, $c) = @_;
361       $c->stash->{json} = [ $c->user->street_address ]; # BAD
362       $c->forward('View::JSON');
363   }
364
365 When you return logged-in user's private data to the response JSON,
366 you might want to disable GET requests (because I<script> tag invokes
367 GET requests), or include a random digest string and validate it.
368
369 See
370 L<http://jeremiahgrossman.blogspot.com/2006/01/advanced-web-attack-techniques-using.html>
371 for more.
372
373 =head1 AUTHOR
374
375 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
376
377 =head1 LICENSE
378
379 This library is free software; you can redistribute it and/or modify
380 it under the same terms as Perl itself.
381
382 =head1 CONTRIBUTORS
383
384 Following people has been contributing patches, bug reports and
385 suggestions for the improvement of Catalyst::View::JSON.
386
387 John Wang
388 kazeburo
389 Daisuke Murase
390 Jun Kuriyama
391
392 =head1 SEE ALSO
393
394 L<Catalyst>, L<JSON>, L<Encode::JavaScript::UCS>
395
396 =cut
Note: See TracBrowser for help on using the browser.