Merge pull request #80 from rappasoft/develop

Exports

Author: rappasoft

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
 
 ## [Unreleased]
 
+## [0.3.2] - 2020-09-25
+
+### Added
+
+- Added thead class to option array
+- Ability to export the list set to CSV/XLS/XLSX/PDF
+- Ability to mark a visible column as not to be exported
+- Ability to mark a column as export only, which hides it from UI
+- Ability to format a single column differently for export as it is for its UI
+- Added option to change the button class from the config
+
 ## [0.3.1] - 2020-09-18
 
 ### Changed
@@ -119,7 +130,8 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
 
 - Initial release
 
-[Unreleased]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.3.1...development
+[Unreleased]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.3.2...development
+[0.3.2]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/rappasoft/laravel-livewire-tables/compare/v0.2.0...v0.2.1

README.md

@@ -164,6 +164,21 @@ public function hide() : self;
  * Hide this column based on a condition. i.e.: user has or doesn't have a role or permission. Must return a boolean, not a closure.
  */
 public function hideIf($condition) : self;
+
+/**
+ * This column is only included in exports and is not available to the UI
+ */
+public function exportOnly() : self;
+
+/**
+ * This column is excluded from the export but visible to the UI unless defined otherwise with hide() or hideIf()
+ */
+public function excludeFromExport() : self;
+
+/**
+ * If supplied, and the column is exportable, this will be the format when rendering the CSV/XLS/PDF instead of the format() function. You may have both, format() for the UI, and exportFormat() for the export only. If this method is not supplied, format() will be used and passed through strip_tags() to try to clean the output.
+ */
+public function exportFormat(callable $callable = null) : self;
 ```
 
 ### Properties
@@ -221,6 +236,13 @@ You can override any of these in your table component:
 | -------- | ------- | ----- |
 | $offlineIndicator | true | Whether or not to display an offline message when there is no connection |
 
+#### Exports
+
+| Property | Default | Usage |
+| -------- | ------- | ----- |
+| $exportFileName | data | The name of the downloaded file when exported |
+| $exports | [] | The available options to export this table as (csv, xls, xlsx, pdf) |
+
 #### Other
 
 | Property | Default | Usage |
@@ -292,7 +314,120 @@ public function email($email): string
 public function html($html): HtmlString
 ```
 
-### Setting Options
+### Exporting Data
+
+The table component supports exporting to CSV, XLS, XLSX, and PDF.
+
+In order to use this functionality you must install [Laravel Excel](https://laravel-excel.com) 3.1 or newer.
+
+In order to use the PDF export functionality, you must also install either [DOMPDF](https://github.com/dompdf/dompdf) or [MPDF](https://github.com/mpdf/mpdf).
+
+You may set the PDF export library in the config file under **pdf_library**. DOMPDF is the default.
+
+#### What exports your table supports
+
+By default, exporting is off. You can add a list of available export types with the $exports class property.
+
+`public $exports = ['csv', 'xls', 'xlsx', 'pdf'];`
+
+#### Defining the file name.
+
+By default, the filename will be `data`.*type*. I.e. `data.pdf`, `data.csv`.
+
+You can change the filename with the `$exportFileName` class property.
+
+`public $exportFileName = 'users-table';` - *Obviously omit the file type*
+
+#### Deciding what columns to export
+
+You have a couple option on exporting information. By default, if not defined at all, all columns will be exported.
+
+If you have a column that you want visible to the UI, but not to the export, you can chain on `excludeFromExport()`
+
+If you have a column that you want visible to the export, but not to the UI, you can chain on `exportOnly()`
+
+#### Formatting column data for export
+
+By default, the export will attempt to render the information just as it is shown to the UI. For a normal column based attribute this is fine, but when exporting formatted columns that output a view or HTML, it will attempt to strip the HTML out.
+
+Instead, you have available to you the `exportFormat()` method on your column, to define how you want this column to be formatted when outputted to the file.
+
+So you can have a column that you want both available to the UI and the export, and format them differently based on where it is being outputted.
+
+#### Exporting example
+
+```php
+<?php
+
+namespace App\Http\Livewire;
+
+use App\User;
+use Illuminate\Database\Eloquent\Builder;
+use Rappasoft\LaravelLivewireTables\TableComponent;
+use Rappasoft\LaravelLivewireTables\Traits\HtmlComponents;
+use Rappasoft\LaravelLivewireTables\Views\Column;
+
+class UsersTable extends TableComponent
+{
+    use HtmlComponents;
+
+    public function query() : Builder
+    {
+        return User::with('role')->withCount('permissions');
+    }
+
+    public function columns() : array
+    {
+        return [
+            Column::make('ID')
+                ->searchable()
+                ->sortable()
+                ->excludeFromExport(), // This column is visible to the UI, but not export.
+            Column::make('ID')
+                ->exportOnly(), // This column is only rendered on export
+            Column::make('Avatar')
+                ->format(function(User $model) {
+                    return $this->image($model->avatar, $model->name, ['class' => 'img-fluid']);
+                })
+                ->excludeFromExport(), // This column is visible to the UI, but not export.
+            Column::make('Name') // This columns is visible to both the UI and export, and is rendered the same
+                ->searchable()
+                ->sortable(),
+            Column::make('E-mail', 'email')
+                ->searchable()
+                ->sortable()
+                ->format(function(User $model) {
+                    return $this->mailto($model->email, null, ['target' => '_blank']);
+                })
+                ->exportFormat(function(User $model) { // This column is visible to both the UI and the export, but is formatted differently to the export via this method.
+                    return $model->email;
+                }),
+            Column::make('Role', 'role.name') // This columns is visible to both the UI and export, and is rendered the same
+                ->searchable()
+                ->sortable(),
+            Column::make('Permissions') // This columns is visible to both the UI and export, and is rendered the same, except the HTML tags will be removed because it is not specifically calling a exportFormat() function.
+                ->sortable()
+                ->format(function(User $model) {
+                    return $this->html('<strong>'.$model->permissions_count.'</strong>');
+                }),
+            Column::make('Actions')
+                ->format(function(User $model) {
+                    return view('backend.auth.user.includes.actions', ['user' => $model]);
+                })
+                ->hideIf(auth()->user()->cannot('do-this'))
+                ->excludeFromExport(), // This column is visible to the UI, but not export.
+        ];
+    }
+}
+```
+
+#### Customizing Exports
+
+Currently, there are no customization options available. But there is a config item called `exports` where you can define the class to do the rendering. You can use the `\Rappasoft\LaravelLivewireTables\Exports\Export` class as a base.
+
+More options will be added in the future, but the built in options should be good for most applications.
+
+### Setting Component Options
 
 There are some frontend framework specific options that can be set.
 
@@ -304,6 +439,12 @@ They are done this way instead of the config file that way you can have per-comp
 protected $options = [
     // The class set on the table when using bootstrap
     'bootstrap.classes.table' => 'table table-striped table-bordered',
+
+    // The class set on the table's thead when using bootstrap
+    'bootstrap.classes.thead' => null,
+
+    // The class set on the table's export dropdown button
+    'bootstrap.classes.buttons.export' => 'btn',
 
     // Whether or not the table is wrapped in a `.container-fluid` or not
     'bootstrap.container' => true,

composer.json

@@ -27,6 +27,9 @@
         "orchestra/testbench": "^5.0",
         "phpunit/phpunit": "^9.0"
     },
+    "suggest": {
+        "maatwebsite/excel": "Required to use export functionality"
+    },
     "autoload": {
         "psr-4": {
             "Rappasoft\\LaravelLivewireTables\\": "src"

config/config.php

@@ -2,6 +2,20 @@
 
 return [
 
+    /*
+     * The class to use to handle the export functionality
+     */
+    'exports' => \Rappasoft\LaravelLivewireTables\Exports\Export::class,
+
+    /*
+     * Which library you want to use for PDF generation
+     * Supports dompdf, mpdf
+     * You must install the appropriate third party package for each
+     * See: https://docs.laravel-excel.com/3.1/exports/export-formats.html
+     * And: https://phpspreadsheet.readthedocs.io/en/latest/topics/reading-and-writing-to-file/#pdf
+     */
+    'pdf_library' => 'dompdf',
+
     /*
      * The frontend styling framework to use
      * Options: bootstrap-4

resources/lang/ar/strings.php

@@ -2,6 +2,7 @@
 
 return [
     'clear' => 'مسح',
+    'export' => 'Export',
     'loading' => 'تحميل...',
     'no_results' => 'لا توجد نتائج لعرضها لهذا الاستعلام.',
     'offline' => 'أنت غير متصل حاليا بالإنترنت.',

resources/lang/en/strings.php

@@ -2,6 +2,7 @@
 
 return [
     'clear' => 'Clear',
+    'export' => 'Export',
     'loading' => 'Loading...',
     'no_results' => 'There are no results to display for this query.',
     'offline' => 'You are not currently connected to the internet.',

resources/views/bootstrap-4/includes/export.blade.php

@@ -0,0 +1,25 @@
+@if (count($exports))
+    <div class="dropdown table-export">
+        <button class="dropdown-toggle {{ $this->getOption('bootstrap.classes.buttons.export') }}" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+            @lang('laravel-livewire-tables::strings.export')
+        </button>
+
+        <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
+            @if (in_array('csv', $exports, true))
+                <a class="dropdown-item" href="#" wire:click.prevent="export('csv')">CSV</a>
+            @endif
+
+            @if (in_array('xls', $exports, true))
+                <a class="dropdown-item" href="#" wire:click.prevent="export('xls')">XLS</a>
+            @endif
+
+            @if (in_array('xlsx', $exports, true))
+                <a class="dropdown-item" href="#" wire:click.prevent="export('xlsx')">XLSX</a>
+            @endif
+
+            @if (in_array('pdf', $exports, true))
+                <a class="dropdown-item" href="#" wire:click.prevent="export('pdf')">PDF</a>
+            @endif
+        </div>
+    </div><!--export-dropdown-->
+@endif

resources/views/bootstrap-4/includes/options.blade.php

@@ -33,5 +33,7 @@ class="form-control"
                 @endif
             </div>
         @endif
+
+        @include('laravel-livewire-tables::'.config('laravel-livewire-tables.theme').'.includes.export')
     </div><!--row-->
 @endif

resources/views/bootstrap-4/includes/thead.blade.php

@@ -1,5 +1,5 @@
 @if ($tableHeaderEnabled)
-    <thead>
+    <thead class="{{ $this->getOption('bootstrap.classes.thead') }}">
         @include('laravel-livewire-tables::'.config('laravel-livewire-tables.theme').'.includes.columns')
     </thead>
 @endif

src/Exceptions/UnsupportedExportFormatException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Rappasoft\LaravelLivewireTables\Exceptions;
+
+use Exception;
+
+class UnsupportedExportFormatException extends Exception
+{
+}