Merge pull request #112 from sebastienheyd/feat/button-tooltip-custom

feat(datatables): add tooltip support and custom button helper

Author: sebastienheyd

docs/docs/8.x/datatables/button.md

@@ -20,6 +20,7 @@ Button::add()
 | [class](#class) | Sets additional class |
 | [route](#route) | Sets the button link href by using a route |
 | [link](#link) | Sets the button link href |
+| [tooltip](#tooltip) | Sets a tooltip for the button |
 | [attributes](#attributes) | Sets HTML attributes to the button |
 | [make](#make) | Renders the button |
 
@@ -93,6 +94,27 @@ Sets the button link href.
 ->link(route('boilerplate.users.edit', $user->id))
 ```
 
+## tooltip
+
+Sets a tooltip for the button using the HTML `title` attribute.
+
+```php
+->tooltip('Edit this user')
+```
+
+The tooltip is only rendered when a non-empty string is provided, avoiding unnecessary HTML attributes.
+
+**Example with tooltip:**
+
+```php
+Button::add('Edit')
+    ->route('boilerplate.users.edit', $user->id)
+    ->icon('pencil-alt')
+    ->color('primary')
+    ->tooltip('Edit this user')
+    ->make();
+```
+
 ## attributes
 
 Sets HTML attributes.
@@ -113,6 +135,8 @@ Renders the button.
 
 ## Button aliases
 
+### Predefined buttons
+
 ```php
 Button::show('route.to.resource.show', $resource);
 ```
@@ -126,3 +150,33 @@ Button::delete('route.to.resource.destroy', $resource);
 ```
 
 > `Button::delete` will show a modal to confirm the deletion. You can set another confirmation message by using the [`Datatable::locale()` method](options#locale).
+
+### Custom button helper
+
+The `custom()` method provides a convenient way to create custom buttons with all parameters in a single call:
+
+```php
+Button::custom(
+    'route.name',           // Route name (required)
+    $args,                  // Route arguments (optional, default: [])
+    'icon-name',            // FontAwesome icon (optional, default: '')
+    'Tooltip text',         // Tooltip text (optional, default: '')
+    'primary',              // Button color (optional, default: 'default')
+    ['data-action' => 'x']  // HTML attributes (optional, default: [])
+);
+```
+
+**Example:**
+
+```php
+Button::custom(
+    'users.export',
+    ['id' => $user->id],
+    'download',
+    'Export user data',
+    'success',
+    ['data-confirm' => 'Export this user?']
+);
+```
+
+**Note:** The icon parameter comes before the tooltip for better ergonomics. If no icon is provided, no empty HTML markup is generated.

src/Datatables/Button.php

@@ -10,6 +10,7 @@ class Button
     protected string $icon = '';
     protected string $label = '';
     protected array $attributes = [];
+    protected string $tooltip = '';
 
     /**
      * Instanciate a new button.
@@ -32,6 +33,28 @@ public static function add(string $label = ''): self
         return new static($label);
     }
 
+    /**
+     * Returns a custom button.
+     *
+     * @param  string  $route
+     * @param  mixed  $args
+     * @param  string  $icon
+     * @param  string  $tooltip
+     * @param  string  $color
+     * @param  array  $attributes
+     * @return string
+     */
+    public static function custom(string $route, mixed $args = [], string $icon = '', string $tooltip = '', string $color = 'default', array $attributes = []): string
+    {
+        $button = self::add()->route($route, $args)->tooltip($tooltip);
+
+        if (! empty($icon)) {
+            $button->icon($icon);
+        }
+
+        return $button->color($color)->attributes($attributes)->make();
+    }
+
     /**
      * Returns an edit button.
      *
@@ -41,7 +64,7 @@ public static function add(string $label = ''): self
      */
     public static function show(string $route, $args = []): string
     {
-        return self::add()->attributes(['data-action' => 'dt-show-element'])->route($route, $args)->icon('eye')->make();
+        return self::add()->attributes(['data-action' => 'dt-show-element'])->route($route, $args)->tooltip(__('boilerplate::datatable.show'))->icon('eye')->make();
     }
 
     /**
@@ -53,7 +76,7 @@ public static function show(string $route, $args = []): string
      */
     public static function edit(string $route, $args = []): string
     {
-        return self::add()->attributes(['data-action' => 'dt-edit-element'])->route($route, $args)->color('primary')->icon('pencil-alt')->make();
+        return self::add()->attributes(['data-action' => 'dt-edit-element'])->route($route, $args)->tooltip(__('boilerplate::datatable.edit'))->color('primary')->icon('pencil-alt')->make();
     }
 
     /**
@@ -68,6 +91,7 @@ public static function delete(string $route, $args = []): string
         return self::add()
             ->route($route, $args)
             ->attributes(['data-action' => 'dt-delete-element'])
+            ->tooltip(__('boilerplate::datatable.delete'))
             ->color('danger')
             ->icon('trash')
             ->make();
@@ -161,15 +185,26 @@ public function link(string $href): self
         return $this;
     }
 
+    /**
+     * Sets tooltip of button.
+     *
+     * @param  string  $tooltip
+     * @return $this
+     */
+    public function tooltip(string $tooltip): self
+    {
+        $this->tooltip = $tooltip;
+
+        return $this;
+    }
+
     /**
      * Renders the button.
      *
      * @return string
      */
     public function make(): string
     {
-        $str = '<a href="%s" class="btn btn-sm btn-%s ml-1%s" %s>%s%s</a>';
-
         if (! empty($this->label) && ! empty($this->icon)) {
             $this->label = $this->label.' ';
         }
@@ -182,6 +217,9 @@ public function make(): string
             return sprintf('%s="%s"', $k, $this->attributes[$k]);
         }, array_keys($this->attributes)));
 
-        return sprintf($str, $this->href, $this->color, $this->class, $attributes, $this->label, $this->icon);
+        $tooltip = ! empty($this->tooltip) ? sprintf(' data-toggle="tooltip" title="%s"', e($this->tooltip)) : '';
+        $str = '<a href="%s"%s class="btn btn-sm btn-%s ml-1%s" %s>%s%s</a>';
+
+        return sprintf($str, $this->href, $tooltip, $this->color, $this->class, $attributes, $this->label, $this->icon);
     }
 }

src/resources/lang/bg/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'Да изтриете този елемент?',
     'deleteSuccess' => 'Позицията е успешно изтрита',
+    'show'          => 'Преглед',
+    'edit'          => 'Редактиране',
+    'delete'        => 'Изтриване',
 ];

src/resources/lang/en/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'Delete this item?',
     'deleteSuccess' => 'Item successfully deleted',
+    'show'          => 'Show',
+    'edit'          => 'Edit',
+    'delete'        => 'Delete',
 ];

src/resources/lang/es/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => '¿Borrar este elemento?',
     'deleteSuccess' => 'Elemento eliminado con éxito',
+    'show'          => 'Ver',
+    'edit'          => 'Editar',
+    'delete'        => 'Eliminar',
 ];

src/resources/lang/fa/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'این مورد حذف شود؟',
     'deleteSuccess' => 'مورد با موفقیت حذف شد',
+    'show'          => 'نمایش',
+    'edit'          => 'ویرایش',
+    'delete'        => 'حذف',
 ];

src/resources/lang/fr/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'Supprimer cet élément ?',
     'deleteSuccess' => "L'élément a été supprimé",
+    'show'          => 'Voir',
+    'edit'          => 'Éditer',
+    'delete'        => 'Supprimer',
 ];

src/resources/lang/it/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'Cancellare questo elemento?',
     'deleteSuccess' => 'Elemento eliminato con successo',
+    'show'          => 'Mostra',
+    'edit'          => 'Modifica',
+    'delete'        => 'Elimina',
 ];

src/resources/lang/tr/datatable.php

@@ -3,4 +3,7 @@
 return [
     'deleteConfirm' => 'Bu öğe silinsin mi?',
     'deleteSuccess' => 'Öğe başarıyla silindi',
+    'show'          => 'Göster',
+    'edit'          => 'Düzenle',
+    'delete'        => 'Sil',
 ];

tests/Controllers/DatatablesTest.php

@@ -48,6 +48,6 @@ public function testUsersDatatables()
         $data = $resource->getOriginalContent()['data'][0];
 
         $this->assertEquals($user->email, $data['email']);
-        $this->assertEquals('<a href="/admin/users/1/edit" class="btn btn-sm btn-primary ml-1" data-action="dt-edit-element"><i class="fas fa-fw fa-pencil-alt"></i></a>', $data['dt-actions']);
+        $this->assertEquals('<a href="/admin/users/1/edit" data-toggle="tooltip" title="Edit" class="btn btn-sm btn-primary ml-1" data-action="dt-edit-element"><i class="fas fa-fw fa-pencil-alt"></i></a>', $data['dt-actions']);
     }
 }