File Coverage

blib/lib/Catalyst/View/JSON.pm
Criterion Covered Total %
statement 64 76 84.2
branch 32 42 76.2
condition 13 16 81.2
subroutine 10 13 76.9
pod 2 3 66.7
total 121 150 80.7


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