5 use parent qw(Rose::Object);
10 use Rose::Object::MakeMethods::Generic
12 'scalar --get_set_init' => [ qw(_actions) ],
15 my %supported_methods = (
21 # DOM insertion, around
27 # DOM insertion, inside
35 # DOM insertion, outside
64 my ($self, @args) = @_;
66 my $method = $AUTOLOAD;
68 return if $method eq 'DESTROY';
70 my $num_args = $supported_methods{$method};
71 $::lxdebug->message(0, "autoload method $method");
73 croak "Unsupported jQuery action: $method" unless defined $num_args;
74 croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted: $num_args)" if scalar(@args) != $num_args;
77 # Force flattening from SL::Presenter::EscapedText: "" . $...
78 $args[0] = "" . $args[0];
82 push @{ $self->_actions }, [ $method, @args ];
93 return SL::JSON::to_json({ eval_actions => $self->_actions });
98 return $self->_actions;
110 SL::ClientJS - Easy programmatic client-side JavaScript generation
115 First some JavaScript code:
117 // In the client generate an AJAX request whose 'success' handler
118 // calls "eval_json_response(data)":
120 action: "SomeController/the_action",
121 id: $('#some_input_field').val()
123 $.post("controller.pl", data, eval_json_response);
127 # In the controller itself. First, make sure that the "client_js.js"
128 # is loaded. This must be done when the whole side is loaded, so
129 # it's not in the action called by the AJAX request shown above.
130 $::request->layout->use_javascript('client_js.js');
132 # Now in that action called via AJAX:
133 sub action_the_action {
136 # Create a new client-side JS object and do stuff with it!
137 my $js = SL::ClientJS->new;
139 # Show some element on the page:
140 $js->show('#usually_hidden');
142 # Set to hidden inputs. Yes, calls can be chained!
143 $js->val('#hidden_id', $self->new_id)
144 ->val('#other_type', 'Unicorn');
146 # Replace some HTML code:
147 my $html = $self->render('SomeController/the_action', { output => 0 });
148 $js->html('#id_with_new_content', $html);
150 # Finally render the JSON response:
156 This module enables the generation of jQuery-using JavaScript code on
157 the server side. That code is then evaluated in a safe way on the
160 The workflow is usally that the client creates an AJAX request, the
161 server creates some actions and sends them back, and the client then
162 implements each of these actions.
164 There are three things that need to be done for this to work:
168 =item 1. The "client_js.js" has to be loaded before the AJAX request is started.
170 =item 2. The client code needs to call C<eval_json_response()> with the result returned from the server.
172 =item 3. The server must use this module.
176 The functions called on the client side are mostly jQuery
177 functions. Other functionality may be added later.
179 Note that L<SL::Controller/render> is aware of this module which saves
180 you some boilerplate. The following two calls are equivalent:
182 $controller->render($client_js);
183 $controller->render(\$client_js->to_json, { type => 'json' });
185 =head1 FUNCTIONS NOT PASSED TO THE CLIENT SIDE
191 Returns the actions gathered so far as an array reference. Each
192 element is an array reference containing at least two items: the
193 function's name and what it is called on. Additional array elements
194 are the function parameters.
198 Returns the actions gathered so far as a JSON string ready to be sent
203 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
205 =head2 JQUERY FUNCTIONS
207 The following jQuery functions are supported:
213 C<hide>, C<show>, C<toggle>
215 =item DOM insertion, around
217 C<unwrap>, C<wrap>, C<wrapAll>, C<wrapInner>
219 =item DOM insertion, inside
221 C<append>, C<appendTo>, C<html>, C<prepend>, C<prependTo>, C<text>
223 =item DOM insertion, outside
225 C<after>, C<before>, C<insertAfter>, C<insertBefore>
231 =item DOM replacement
233 C<replaceAll>, C<replaceWith>
235 =item General attributes
237 C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>
241 C<data>, C<removeData>
245 =head1 ADDING SUPPORT FOR ADDITIONAL FUNCTIONS
247 In order not having to maintain two files (this one and
248 C<js/client_js.js>) there's a script that can parse this file's
249 C<%supported_methods> definition and convert it into the appropriate
250 code ready for manual insertion into C<js/client_js.js>. The steps
255 =item 1. Add lines in this file to the C<%supported_methods> hash. The
256 key is the function name and the value is the number of expected
259 =item 2. Run C<scripts/generate_client_js_actions.pl>
261 =item 3. Edit C<js/client_js.js> and replace the type casing code with
262 the output generated in step 2.
272 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>