Added configurable areas

Author: rappasoft

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
 ### Added
 
 - Added ability to define additional select statements outside the scope of a column using the `setAdditionalSelects(array $selects)` configuration method.
+- Added 8 configurable areas, see `Configurable Areas` of the `Datatable` section of the documentation.
 
 ## [2.2.1] - 2022-04-27
 

docs/datatable/available-methods.md

@@ -373,6 +373,21 @@ public function configure(): void
 }
 ```
 
+## Builder
+
+### setAdditionalSelects
+
+By default the only columns defined in the select statement are the ones defined via columns. If you need to define additional selects that you don't have a column for you may:
+
+```php
+public function configure(): void
+{
+  $this->setAdditionalSelects(['users.id as id']);
+}
+```
+
+Since you probably won't have an `ID` column defined, the ID will not be available on the model to use. In the case of an actions column where you have buttons specific to the row, you probably need that, so you can add the select statement to make it available on the model.
+
 ## Misc.
 
 ### setEmptyMessage

docs/datatable/configurable-areas.md

@@ -0,0 +1,131 @@
+---
+title: Configurable Areas
+weight: 3
+---
+
+There are certain areas of the datatable as of `v2.2` where you can include your own view files. This is good for adding additional functionality to the toolbar, for example.
+
+## Available Methods
+
+### setConfigurableAreas
+
+You can use the `setConfigurableAreas` method to set the areas that you want to be configurable.
+
+```php
+public function configure(): void
+{
+  $this->setConfigurableAreas([
+    'toolbar-left-start' => 'path.to.my.view',
+    'toolbar-left-end' => 'path.to.my.view',
+    'toolbar-right-start' => 'path.to.my.view',
+    'toolbar-right-end' => 'path.to.my.view',
+    'before-toolbar' => 'path.to.my.view',
+    'after-toolbar' => 'path.to.my.view',
+    'before-pagination' => 'path.to.my.view',
+    'after-pagination' => 'path.to.my.view',
+  ]);
+}
+```
+
+**Note:** Only specify the keys you are actually implementing, otherwise you may get uneven spacing.
+
+## Example View
+
+Example dropdown for the toolbar:
+
+```php
+@aware(['component'])
+
+@php
+    $theme = $component->getTheme();
+@endphp
+
+@if ($theme === 'tailwind')
+    <div class="w-full mb-4 md:w-auto md:mb-0">
+        <div
+            x-data="{ open: false }"
+            @keydown.window.escape="open = false"
+            x-on:click.away="open = false"
+            class="relative z-10 inline-block w-full text-left md:w-auto"
+            wire:key="bulk-actions-button-{{ $component->getTableName() }}"
+        >
+            <div>
+                <span class="rounded-md shadow-sm">
+                    <button
+                        x-on:click="open = !open"
+                        type="button"
+                        class="inline-flex justify-center w-full px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md shadow-sm hover:bg-gray-50 focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 dark:bg-gray-700 dark:text-white dark:border-gray-600 dark:hover:bg-gray-600"
+                        aria-haspopup="true"
+                        x-bind:aria-expanded="open"
+                        aria-expanded="true"
+                    >
+                        @lang('My Dropdown')
+
+                        <svg class="w-5 h-5 ml-2 -mr-1" x-description="Heroicon name: chevron-down" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor">
+                            <path fill-rule="evenodd" d="M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z" clip-rule="evenodd"></path>
+                        </svg>
+                    </button>
+                </span>
+            </div>
+
+            <div
+                x-cloak
+                x-show="open"
+                x-transition:enter="transition ease-out duration-100"
+                x-transition:enter-start="transform opacity-0 scale-95"
+                x-transition:enter-end="transform opacity-100 scale-100"
+                x-transition:leave="transition ease-in duration-75"
+                x-transition:leave-start="transform opacity-100 scale-100"
+                x-transition:leave-end="transform opacity-0 scale-95"
+                class="absolute right-0 z-50 w-full mt-2 origin-top-right bg-white divide-y divide-gray-100 rounded-md shadow-lg md:w-48 ring-1 ring-black ring-opacity-5 focus:outline-none"
+            >
+                <div class="bg-white rounded-md shadow-xs dark:bg-gray-700 dark:text-white">
+                    <div class="py-1" role="menu" aria-orientation="vertical">
+                        <button
+                            wire:click="my-action"
+                            wire:key="bulk-action-my-action-{{ $component->getTableName() }}"
+                            type="button"
+                            class="flex items-center block w-full px-4 py-2 space-x-2 text-sm leading-5 text-gray-700 hover:bg-gray-100 hover:text-gray-900 focus:outline-none focus:bg-gray-100 focus:text-gray-900 dark:text-white dark:hover:bg-gray-600"
+                            role="menuitem"
+                        >
+                            <span>My Action 1</span>
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+@elseif ($theme === 'bootstrap-4' || $theme === 'bootstrap-5')
+    <div><!-- Implement Other Themes if needed--></div>
+@endif
+```
+
+**Note:** If you don't specify the theme conditional, it will show up on every
+
+## Areas
+
+Here are the placements for the available areas:
+
+Toolbar Left Start
+![Toolbar Left Start](https://imgur.com/eDQx67u.png)
+
+Toolbar Left End
+![Toolbar Left End](https://imgur.com/hmkfoyH.png)
+
+Toolbar Right Start
+![Toolbar Right Start](https://imgur.com/V99PQUv.png)
+
+Toolbar Right End
+![Toolbar Right End](https://imgur.com/rZgbeYO.png)
+
+Before Toolbar
+![Before Toolbar](https://imgur.com/KK9EiSM.png)
+
+After Toolbar
+![After Toolbar](https://imgur.com/VL0OGia.png)
+
+Before Pagination
+![Before Pagination](https://imgur.com/lVIGpDW.png)
+
+After Pagination
+![After Pagination](https://imgur.com/wJR2LEJ.png)

resources/views/components/pagination.blade.php

@@ -5,6 +5,10 @@
     $theme = $component->getTheme();
 @endphp
 
+@if ($component->hasConfigurableAreaFor('before-pagination'))
+    @include($component->getConfigurableAreaFor('before-pagination'))
+@endif
+
 @if ($theme === 'tailwind')
     <div>
         @if ($component->paginationVisibilityIsEnabled())
@@ -96,3 +100,7 @@
         @endif
     </div>
 @endif
+
+@if ($component->hasConfigurableAreaFor('after-pagination'))
+    @include($component->getConfigurableAreaFor('after-pagination'))
+@endif

resources/views/components/tools/toolbar.blade.php

@@ -4,9 +4,17 @@
     $theme = $component->getTheme();
 @endphp
 
+@if ($component->hasConfigurableAreaFor('before-toolbar'))
+    @include($component->getConfigurableAreaFor('before-toolbar'))
+@endif
+
 @if ($theme === 'tailwind')
     <div class="md:flex md:justify-between mb-4 px-4 md:p-0">
         <div class="w-full mb-4 md:mb-0 md:w-2/4 md:flex space-y-4 md:space-y-0 md:space-x-2">
+            @if ($component->hasConfigurableAreaFor('toolbar-left-start'))
+                @include($component->getConfigurableAreaFor('toolbar-left-start'))
+            @endif
+
             @if ($component->reorderIsEnabled())
                 <button
                     wire:click="{{ $component->currentlyReorderingIsEnabled() ? 'disableReordering' : 'enableReordering' }}"
@@ -126,9 +134,17 @@ class="w-full inline-flex items-center justify-center px-3 py-2 border border-gr
                     @endif
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-left-end'))
+                @include($component->getConfigurableAreaFor('toolbar-left-end'))
+            @endif
         </div>
 
         <div class="md:flex md:items-center space-y-4 md:space-y-0 md:space-x-2">
+            @if ($component->hasConfigurableAreaFor('toolbar-right-start'))
+                @include($component->getConfigurableAreaFor('toolbar-right-start'))
+            @endif
+
             @if ($component->showBulkActionsDropdown())
                 <div class="w-full md:w-auto mb-4 md:mb-0">
                     <div
@@ -270,6 +286,10 @@ class="block w-full border-gray-300 rounded-md shadow-sm transition duration-150
                     </select>
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-right-end'))
+                @include($component->getConfigurableAreaFor('toolbar-right-end'))
+            @endif
         </div>
     </div>
 
@@ -301,6 +321,10 @@ class="block text-sm font-medium leading-5 text-gray-700 dark:text-white">
 @elseif ($theme === 'bootstrap-4')
     <div class="d-md-flex justify-content-between mb-3">
         <div class="d-md-flex">
+            @if ($component->hasConfigurableAreaFor('toolbar-left-start'))
+                @include($component->getConfigurableAreaFor('toolbar-left-start'))
+            @endif
+
             @if ($component->reorderIsEnabled())
                 <div class="mr-0 mr-md-2 mb-3 mb-md-0">
                     <button
@@ -410,9 +434,17 @@ class="dropdown-item btn text-center"
                     </div>
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-left-end'))
+                @include($component->getConfigurableAreaFor('toolbar-left-end'))
+            @endif
         </div>
 
         <div class="d-md-flex">
+            @if ($component->hasConfigurableAreaFor('toolbar-right-start'))
+                @include($component->getConfigurableAreaFor('toolbar-right-start'))
+            @endif
+
             @if ($component->showBulkActionsDropdown())
                 <div class="mb-3 mb-md-0">
                     <div class="dropdown d-block d-md-inline">
@@ -499,6 +531,10 @@ class="form-control"
                     </select>
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-right-end'))
+                @include($component->getConfigurableAreaFor('toolbar-right-end'))
+            @endif
         </div>
     </div>
 
@@ -526,6 +562,10 @@ class="d-block">
 @elseif ($theme === 'bootstrap-5')
     <div class="d-md-flex justify-content-between mb-3">
         <div class="d-md-flex">
+            @if ($component->hasConfigurableAreaFor('toolbar-left-start'))
+                @include($component->getConfigurableAreaFor('toolbar-left-start'))
+            @endif
+
             @if ($component->reorderIsEnabled())
                 <div class="me-0 me-md-2 mb-3 mb-md-0">
                     <button
@@ -633,9 +673,17 @@ class="dropdown-item text-center"
                     </div>
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-left-end'))
+                @include($component->getConfigurableAreaFor('toolbar-left-end'))
+            @endif
         </div>
 
         <div class="d-md-flex">
+            @if ($component->hasConfigurableAreaFor('toolbar-right-start'))
+                @include($component->getConfigurableAreaFor('toolbar-right-start'))
+            @endif
+
             @if ($component->showBulkActionsDropdown())
                 <div class="mb-3 mb-md-0">
                     <div class="dropdown d-block d-md-inline">
@@ -722,6 +770,10 @@ class="form-control"
                     </select>
                 </div>
             @endif
+
+            @if ($component->hasConfigurableAreaFor('toolbar-right-end'))
+                @include($component->getConfigurableAreaFor('toolbar-right-end'))
+            @endif
         </div>
     </div>
 
@@ -747,3 +799,7 @@ class="d-block">
         </div>
     @endif
 @endif
+
+@if ($component->hasConfigurableAreaFor('after-toolbar'))
+    @include($component->getConfigurableAreaFor('after-toolbar'))
+@endif

src/Traits/ComponentUtilities.php

@@ -32,6 +32,16 @@ trait ComponentUtilities
     protected $collapsingColumnsStatus = true;
     protected string $emptyMessage = 'No items found. Try to broaden your search.';
     protected array $additionalSelects = [];
+    protected array $configurableAreas = [
+        'toolbar-left-start' => null,
+        'toolbar-left-end' => null,
+        'toolbar-right-start' => null,
+        'toolbar-right-end' => null,
+        'before-toolbar' => null,
+        'after-toolbar' => null,
+        'before-pagination' => null,
+        'after-pagination' => null,
+    ];
 
     /**
      * Set the custom query string array for this specific table

src/Traits/Configuration/ComponentConfiguration.php

@@ -297,4 +297,16 @@ public function setAdditionalSelects($selects): self
 
         return $this;
     }
+
+    /**
+     * @param  $areas
+     * 
+     * @return $this
+     */
+    public function setConfigurableAreas(array $areas): self
+    {
+        $this->configurableAreas = $areas;
+
+        return $this;
+    }
 }

src/Traits/Helpers/ComponentHelpers.php

@@ -311,4 +311,32 @@ public function getAdditionalSelects(): array
     {
         return $this->additionalSelects;
     }
+
+    /**
+     * @return array
+     */
+    public function getConfigurableAreas(): array
+    {
+        return $this->configurableAreas;
+    }
+
+    /**
+     * @param  string  $area
+     * 
+     * @return bool
+     */
+    public function hasConfigurableAreaFor(string $area): bool
+    {
+        return isset($this->configurableAreas[$area]) && $this->getConfigurableAreaFor($area) !== null;
+    }
+
+    /**
+     * @param  string  $area
+     * 
+     * @return string|null
+     */
+    public function getConfigurableAreaFor(string $area): ?string
+    {
+        return $this->configurableAreas[$area] ?? null;
+    }
 }