1 package SL::Layout::ActionBar::Action;
4 use parent qw(Rose::Object);
6 use SL::Presenter::Tag qw(name_to_id);
8 use Rose::Object::MakeMethods::Generic (
9 'scalar --get_set_init' => [ qw(id params text) ],
12 # subclassing interface
15 die 'needs to be implemented';
19 sprintf q|$('#%s').data('action', %s);|, $_[0]->id, JSON->new->allow_blessed->convert_blessed->encode($_[0]->params);
22 # this is mostly so that outside consumer don't need to load subclasses themselves
24 my ($class, $data) = @_;
26 require SL::Layout::ActionBar::Submit;
28 my ($text, %params) = @$data;
29 return if exists($params{only_if}) && !$params{only_if};
30 return if exists($params{not_if}) && $params{not_if};
31 return SL::Layout::ActionBar::Submit->new(text => $text, params => \%params);
36 # shortcut for presenter
42 # unique id to tie div and javascript together
44 $_[0]->params->{id} // name_to_id('action[]')
55 SL::Layout::ActionBar::Action - base class for action bar actions
59 This base class for actions can be used to implement elements that can be
60 added to L<SL::Layout::ActionBar>.
62 Elements can be interactive or simply used for layout. Most of the actual
63 semantics are handled in the corresponding javascript C<js/kivi.ActionBar.js>, so
64 this is only used to generate the DOM elements and to provide information for
65 request time logic decisions.
71 package SL::Layout::ActionBar::Custom;
72 use parent qw(SL::Layout::ActionBar::Action);
75 SL::Layout::ActionBar::Custom->new(
76 text => t8('Description'),
84 # parse sugared version:
85 SL::Layout::ActionBar::Custom->from_params(
98 Needs to be implemented. Should render only the bare minimum necessary to
99 identify the element at run time.
103 Will be called during layout rendering. Defaults to dumping the params section
104 into data field of the rendered DOM element.
106 =item * C<from_params>
108 Parse sugared version. Defaults for historic reasons to the implementation of
109 L<SL::Layout::ActionBar::Submit>, all others must implement their own.
113 Used to determine whether an instance is callable or only a layout element.
123 Returns the current request presenter.
127 Will get initialized to either the provided id from the params or to a
128 generated unique id. Should be used to tie the rendered DOM and script
133 =head1 RECOGNIZED PARAMETERS
137 =item * C<< submit => [ $selector, \%params ] >>
139 On click, submit the form found with the first parameter. If params is present
140 and a hashref, the key value elements will be added to the form before
141 submitting. Beware that this will destroy the form if the user uses the browser
142 history to jump back to this page, so ony use parametrized submits for post
143 submits that redirect on completion.
145 =item * C<< link => $url >>
147 On click, will load the given url.
149 =item * C<< call => [ $function_name, @args ] >>
151 On click, will call the function name with the argument array. The return will
152 be discarded. It is assumed that the fucntion will trigger an asynchronous
155 Contrast with C<checks>.
157 =item * C<< checks => \@function_names >>
159 Before any of C<submit>, C<link>, or C<call> are evaluated all
160 functions in C<check> are called. Only if all of them return a true value the
161 action will be triggered.
163 Checks are expected not to trigger asynchronous actions (contrast with C<call>),
164 but may change the DOM to indicate to the user why they fail.
166 Each must return a boolean value.
168 =item * C<< confirm => t8('Yes/No Question') >>
170 Before any of C<submit>, C<link>, or C<call> are evaluated, the user
171 will be asked to confirm. If checks are present and failed, confirm will not be
174 =item * C<< only_if => $bool >>
176 Pseudo parameter. If present and false, the element will not be rendered.
178 =item * C<< not_if => $bool >>
180 Pseudo parameter. If present and true, the element will not be rendered.
182 =item * C<< only_once => 1 >>
184 If present, a click will C<disable> the action to prevent multiple activations.
186 =item * C<< accesskey => $text >>
188 Registers an accesskey for this element. While the most common accesskey is
189 'enter', in theory every other should work as well. Modifier keys can be added
190 to the accesskey string with 'ctrl+', 'alt+', or 'shift+'. 'shift+' is not
191 necessary for upper case letters.
193 =item * C<< disabled => t8('tooltip') >>
195 Renders the element disabled, ignores all actions (C<submit>, C<call>, C<link>)
196 and adds the given tooltip hopefully explaining why the element is disabled.
198 =item * C<< id => $id >>
200 Sets the DOM id of the rendered element. If missing, the element will get a
203 =item * C<< tooltip => t8('tooltip') >>
205 Sets a tooltip for the element.
215 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>