WebshopApi: falsche sql update Abhängigkeit

[kivitendo-erp.git] / SL / Layout / ActionBar.pm

diff --git a/SL/Layout/ActionBar.pm b/SL/Layout/ActionBar.pm
index 3279ba8..32c2f7d 100644 (file)
--- a/SL/Layout/ActionBar.pm
+++ b/SL/Layout/ActionBar.pm
@@ -85,60 +85,211 @@ __END__
 
 SL::Layout::ActionBar - Unified action buttons for controllers
 
 
 SL::Layout::ActionBar - Unified action buttons for controllers
 

+=head1 SYNOPSIS
+
+  # short sugared syntax:
+  for my $bar ($::request->layout->get('actionbar')) {
+    $bar->add(
+      action => [
+        t8('Description'),
+        call      => [ 'kivi.Javascript.function', @arguments ],
+        accesskey => 'enter',
+        disabled  => $tooltip_with_reason_or_falsish,
+        only_if   => $precomputed_condition,
+        not_if    => $precomputed_condition,
+        id        => 'html-element-id',
+      ],
+      combobox => [
+        action => [...],
+        action => [...],
+        action => [...],
+        action => [...],
+      ],
+      link => [
+        t8('Description'),
+        link => $url,
+      ],
+      'separator',
+    );
+  }
+
+  # full syntax without sugar
+  for my $bar ($::request->layout->get('actionbar')) {
+    $bar->add(
+      (SL::Layout::ActionBar::Action->new(
+        text => t8('Description'),
+        params => {
+          call      => [ 'kivi.Javascript.function', @arguments ],
+          accesskey => 'enter',
+          disabled  => $tooltip_with_reason_or_falsish,
+        },
+      )) x(!!$only_id && !$not_if),
+      SL::Layout::ActionBar::ComboBox->new(
+        actions => [
+          SL::Layout::ActionBar::Action->new(...),
+          SL::Layout::ActionBar::Action->new(...),
+          SL::Layout::ActionBar::Action->new(...),
+          SL::Layout::ActionBar::Action->new(...),
+        ],
+      ),
+      SL::Layout::ActionBar::Link->new(
+        text => t8('Description'),
+        params => {
+          link => $url,
+        },
+      ),
+      SL::Layout::ActionBar::Separator->new,
+    );
+  }
+

 =head1 CONCEPT
 
 =head1 CONCEPT
 

-This is a layout block that does a unified action bar for any controller who
+This is a layout block that creates an action bar for any controller who

 wants to use it. It's designed to be rendered above the content and to be
 wants to use it. It's designed to be rendered above the content and to be

-fixed when scrolling.
+fixed when scrolling. It's structured as a container for elements that can be
+extended when needed.

 
 

-While it can be used as a generic widget container, it's designed to be able to
-provide commonly used functionality as a short cut. These shortcuts include:
+=head1 METHODS

 
 =over 4
 
 
 =over 4
 

-=item *
+=item * C<new>

 
 

-Calling a controller with parameters
+Will be used during initialization of the layout. You should never have to
+instanciate an action bar yourself. Get the current request instances from

 
 

-=item *
+  $::request->layout->get('actionbar')

 
 

-Submitting a form with added parameters
+instead.

 
 

-=item *
+=item * C<add>

 
 

-Arrangement utility
+Add new elements to the bar. Can be instances of
+L<SL::Layout::ActionBar::Action> or scalar strings matching the sugar syntax
+which is described further down.

 
 =back
 
 
 =back
 

+=head1 SYNTACTIC SUGAR

 
 

-=head1 METHODS
+Instead of passing full objects to L</add>, you can instead pass the arguments
+to be used for instantiation to make the code easier to read. The short syntax
+looks like this:
+
+  type => [
+    localized_description,
+    param => value,
+    param => value,
+    ...
+  ]
+
+A string type, followed by the parameters needed for that type. Type may be one of:
+
+=over 4
+
+=item * C<action>
+
+=item * C<combobox>
+
+=item * C<link>
+
+=item * C<separator>
+
+=back
+
+C<separator> will use no parameters, the other three will expect one arrayref.
+
+Two additional pseudo parameters are supported for those:

 
 =over 4
 
 
 =over 4
 

-=item C<add LIST>
+=item * C<only_if>

 
 

-to be documented
+=item * C<not_if>

 
 =back
 
 
 =back
 

-=head1 ACCESS FROM CODE
+These are meant to reduce enterprise operators (C<()x!!>) when conditionally adding lots
+of elements.

 
 

-This is accessable through
+The combobox element is in itself a container and will simply expect the same
+syntax in an arrayref.

 
 

-  $::request->layout->get('actionbar')
+For the full list of parameters supported by the elements, see L<SL::Layout::ActionBar::Action/RECOGNIZED PARAMETERS>.
+
+
+=head1 GUIDELINES
+
+The current implementation follows these design guidelines:

 
 

-=head1 DOM MODEL
+=over 4
+
+=item *
+
+Don't put too many elements into the action bar. Group into comboboxes if
+possible. Consider seven elements a reasonable limit.
+
+=item *
+
+If you've got an update button, put it first and bind the enter accesskey to
+it.
+
+=item *
+
+Put mutating actions (save, post, delete, check out, ship) before the separator
+and non mutating actions (export, search, history, workflow) after the
+separator. Combined actions (save and close) still mutate and go before the
+separator.
+
+=item *
+
+Avoid abusing the actionbar as a secondary menu. As a principle every action
+should act upon the current element or topic.

 
 

-The entire block is rendered into a div with the class 'layout-actionbar'.
+=item *
+
+Hide elements with C<only_if> if they are known to be useless for the current
+topic, but disable when they would be useful in principle but are not
+applicable right now. For example C<delete> does not make sense in a creating
+form, but makes still sense because the element can be deleted later. This
+keeps the actionbar stable and reduces surprising elements that only appear in
+rare situations.

 
 

-=head1 ACTION WIDGETS
+=item *

 
 

-Each individual action must be an instance of C<SL::Layout::ActionBar::Action>.
+Always add a tooltip when disabling an action.
+
+=item *
+
+Try to always add a default action with accesskey enter. Since the actionbar
+lies outside of the main form, the usual submit on enter does not work out of
+the box.
+
+=back
+
+=head1 DOM MODEL AND IMPLEMENTATION DETAILS
+
+The entire block is rendered into a div with the class 'layout-actionbar'. Each
+action will render itself and will get added to the div. To keep the DOM small
+and reduce startup overhead, the presentation is pure CSS and only the sticky
+expansion of comboboxes is done with javascript.
+
+To keep startup times and HTML parsing fast the action data is simply written
+into the data elements of the actions and handlers are added in a ready hook.

 
 =head1 BUGS
 
 none yet. :)
 
 
 =head1 BUGS
 
 none yet. :)
 

+=head1 SEE ALSO
+
+L<SL::Layout::ActioBar::Base>,
+L<SL::Layout::ActioBar::Action>,
+L<SL::Layout::ActioBar::Submit>,
+L<SL::Layout::ActioBar::ComboBox>,
+L<SL::Layout::ActioBar::Separator>,
+L<SL::Layout::ActioBar::Link>,
+

 =head1 AUTHOR
 
 Sven Schoeling E<lt>s.schoeling@linet-services.deE<gt>
 =head1 AUTHOR
 
 Sven Schoeling E<lt>s.schoeling@linet-services.deE<gt>