From c8f38f8803d322130fcb4dbe6b5170d6150ef551 Mon Sep 17 00:00:00 2001 From: pxpm Date: Wed, 9 Oct 2024 14:47:37 +0100 Subject: [PATCH 1/2] update v7 docs --- 7.x-dev/crud-columns.md | 4 ++++ 7.x-dev/crud-fields.md | 1 + 7.x-dev/crud-filters.md | 17 +++++++++++++++++ 7.x-dev/crud-operation-clone.md | 9 +++++++++ 7.x-dev/crud-operation-list-entries.md | 21 ++++++++++++++++++--- 7.x-dev/crud-operation-reorder.md | 15 ++++++++++++++- 7.x-dev/crud-operation-update.md | 3 ++- 7.x-dev/introduction.md | 4 ++-- 8 files changed, 67 insertions(+), 7 deletions(-) diff --git a/7.x-dev/crud-columns.md b/7.x-dev/crud-columns.md index 44b875fb..062e92d7 100644 --- a/7.x-dev/crud-columns.md +++ b/7.x-dev/crud-columns.md @@ -740,6 +740,8 @@ The select_multiple column will output a comma separated list of its connected e 'entity' => 'tags', // the method that defines the relationship in your Model 'attribute' => 'name', // foreign key attribute that is shown to user 'model' => 'App\Models\Tag', // foreign key model + // OPTIONAL + 'separator' => ',', // if you want to use a different separator than the default ',' ], ``` @@ -877,6 +879,8 @@ Show a link which opens in the new tab by default. 'type' => 'url', 'label' => 'URL', //'target' => '_blank' // let's you change link target window. + //'element' => 'a' // let's you change the element of the link. + //'rel' => false OR 'rel' => 'noopener' // let's you disable or change the rel attribute of the link. ], ``` diff --git a/7.x-dev/crud-fields.md b/7.x-dev/crud-fields.md index 082edb94..b9a69023 100644 --- a/7.x-dev/crud-fields.md +++ b/7.x-dev/crud-fields.md @@ -2291,6 +2291,7 @@ CRUD::field([ // select2_from_array 'allows_null' => false, 'default' => 'one', // 'allows_multiple' => true, // OPTIONAL; needs you to cast this to array in your model; + // 'sortable' => true, // requires the field to accept multiple values, and allow the selected options to be sorted. ]); ``` diff --git a/7.x-dev/crud-filters.md b/7.x-dev/crud-filters.md index 6c5d370b..205e3154 100644 --- a/7.x-dev/crud-filters.md +++ b/7.x-dev/crud-filters.md @@ -621,6 +621,23 @@ CRUD::filter('trashed') ## Tips and Tricks + +### Add a debounce time to filters + +Filters can be debounced, so that the filtering logic is only applied after the user has stopped typing for a certain amount of time. This is useful when the filtering logic is expensive and you don't want it to run on every keystroke. To debounce a filter, you can use the following code: + +```php + +CRUD::filter('name') + ->type('text') + ->debounce(1000) // debounce time in milliseconds + ->whenActive(function($value) { + // CRUD::addClause('where', 'name', 'LIKE', "%$value%"); + }); +``` + +All filter types accept a `debounce`, like for example the simple filter, range filter etc. + ### Adding a filter using array syntax diff --git a/7.x-dev/crud-operation-clone.md b/7.x-dev/crud-operation-clone.md index 23a24f5f..e6b259d7 100644 --- a/7.x-dev/crud-operation-clone.md +++ b/7.x-dev/crud-operation-clone.md @@ -50,6 +50,15 @@ class ProductCrudController extends CrudController CRUD::setModel(\App\Models\Product::class); CRUD::setRoute(backpack_url('product')); CRUD::setEntityNameStrings('product', 'products'); + + // optionally you can redirect the user after the clone operation succeeds + // if you set the `redirect_after_clone` option to true, it defaults to the edit page + $this->crud->set('clone.redirect_after_clone', true); + + // you can also use a closure to define the redirect URL + $this->crud->set('clone.redirect_after_clone', function($entry) { + return backpack_url('product/'.$entry->id.'/show'); // redirect to show view instead of edit + }); } } ``` diff --git a/7.x-dev/crud-operation-list-entries.md b/7.x-dev/crud-operation-list-entries.md index 7b5b74a9..fdd7c962 100644 --- a/7.x-dev/crud-operation-list-entries.md +++ b/7.x-dev/crud-operation-list-entries.md @@ -95,6 +95,21 @@ a) For all CrudController (globally) in the `config/backpack/operations/list.php b) For a specific CrudController, in its `setupListOperation()` define `CRUD::setOperationSetting('lineButtonsAsDropdown', true);` +##### Available options + +Additionally you can control the dropdown behavior with `lineButtonsAsDropdownMinimum` and `lineButtonsAsDropdownShowBefore`. By default the dropdown is created no matter how many buttons are present in the line stack. You can change this behavior by setting `lineButtonsAsDropdownMinimum` to a number. If the number of buttons in the line stack is less than this number, the buttons will not be converted to a dropdown. You can also set `lineButtonsAsDropdownShowBefore` to a number to drop the buttons after that number of buttons. + +```php +CRUD::setOperationSetting('lineButtonsAsDropdown', true); +CRUD::setOperationSetting('lineButtonsAsDropdownMinimum', 5); // if there are less than 5 buttons, don't create the dropdown (default: 1) +CRUD::setOperationSetting('lineButtonsAsDropdownShowBefore', 3); // force the first 3 buttons to be inline, and the rest in a dropdown (default: 0) + +// in the above example, when: +// - there are 3 or less buttons, they will be shown inline +// - there are 4 buttons, all 4 will be shown inline +// - there are 5 or more buttons, the first 3 will be shown inline, and the rest in a dropdown +``` + To learn more about buttons, **check out the [Buttons](/docs/{{version}}/crud-buttons) documentation page**. @@ -149,7 +164,7 @@ Exporting the DataTable to PDF, CSV, XLS is as easy as typing ```CRUD::enableExp **Please note that when clicked, the button will export** - **the _currently visible_ table columns** (except columns marked as ```visibleInExport => false```); -- **the columns that are forced to export** (with ```visibleInExport => true``` or ```exportOnlyField => true```); +- **the columns that are forced to export** (with ```visibleInExport => true``` or ```exportOnlyColumn => true```); **In the UI, the admin can use the "Visibility" button, and the "Items per page" dropdown to manipulate what is visible in the table - and consequently what will be exported.** @@ -159,7 +174,7 @@ Available customization: ``` 'visibleInExport' => true/false 'visibleInTable' => true/false -'exportOnlyField' => true +'exportOnlyColumn' => true ``` By default, the field will start visible in the table. Users can hide it toggling visibility. Will be exported if visible in the table. @@ -172,7 +187,7 @@ Setting `visibleInTable => true` will force the field to stay in the table no ma Using `'visibleInTable' => false` will make the field start hidden in the table. But users can toggle it's visibility. -If you want a field that is not on table, user can't show it, but will **ALWAYS** be exported use the `exportOnlyField => true`. If used will ignore any other custom visibility you defined. +If you want a field that is not on table, user can't show it, but will **ALWAYS** be exported use the `exportOnlyColumn => true`. If used will ignore any other custom visibility you defined. #### How to use different separator in DataTables (eg. semicolon instead of comma) diff --git a/7.x-dev/crud-operation-reorder.md b/7.x-dev/crud-operation-reorder.md index 5cd6ac55..a0eab207 100644 --- a/7.x-dev/crud-operation-reorder.md +++ b/7.x-dev/crud-operation-reorder.md @@ -12,7 +12,20 @@ This operation allows your admins to reorder & nest entries. ## Requirements -Your model should have the following integer fields, with a default value of 0: ```parent_id```, ```lft```, ```rgt```, ```depth```. +Your model should have the following integer fields, with a default value of 0: ```parent_id```, ```lft```, ```rgt```, ```depth```. The names are optional, you can change them in the ```setupReorderOperation()``` method. + +```php + +protected function setupReorderOperation() +{ + CRUD::setOperationSetting('reorderColumnNames', [ + 'parent_id' => 'custom_parent_id', + 'lft' => 'left', + 'rgt' => 'right', + 'depth' => 'deep', + ]); +} +``` Additionally, the `parent_id` field has to be nullable. diff --git a/7.x-dev/crud-operation-update.md b/7.x-dev/crud-operation-update.md index e6e7e92f..f994b6f9 100644 --- a/7.x-dev/crud-operation-update.md +++ b/7.x-dev/crud-operation-update.md @@ -374,6 +374,7 @@ class Product extends Model protected $primaryKey = 'id'; protected $fillable = ['name', 'category_id', 'options', 'price', 'tags']; protected $translatable = ['name', 'options']; +} ``` > You DO NOT need to cast translatable string columns as array/json/object in the Eloquent model. From Eloquent's perspective they're strings. So: @@ -453,4 +454,4 @@ If you want to display a **Delete** button right on the **Update** operation, yo } ``` -This will allow admins to remove entries right from the **Update Operation**, and it will redirect them back ot the **List Operation** afterwards. +This will allow admins to remove entries right from the **Update Operation**, and it will redirect them back to the **List Operation** afterwards. diff --git a/7.x-dev/introduction.md b/7.x-dev/introduction.md index 02ca3170..7bab24a6 100644 --- a/7.x-dev/introduction.md +++ b/7.x-dev/introduction.md @@ -88,14 +88,14 @@ Backpack is open-core: ### Versioning, Updates and Upgrades -Starting with the previous version, all our packages follow [semantic versioning](https://semver.org/). Here's what `major.minor.patch` (e.g. `7.0.1`) means for us: +Starting with the previous version, all our packages follow [semantic versioning](https://semver.org/). Here's what `major.minor.patch` (e.g. `6.0.1`) means for us: - `major` - breaking changes, major new features, complete rewrites; released **once a year**, in February; it adds features that were previously impossible and upgrades our dependencies; upgrading is done by following our clear and detailed upgrade guides; - `minor` - new features, released in backwards-compatible ways; **every few months**; update takes seconds; - `patch` - bug fixes & small non-breaking changes; historically **every week**; update takes seconds; When we release a new Backpack\CRUD version, all paid add-ons receive support for it the same day. -When you buy a premium Backpack add-on, you get access to not only _updates_, but also _upgrades_ (for 12 months), that means that **any time you buy a Backpack add-on, it is very likely that you're not only buying the _current_ version** (`v7` at the moment), **but also the upgrade to the _next version_** (`v8` for example). +When you buy a premium Backpack add-on, you get access to not only _updates_, but also _upgrades_ (for 12 months), that means that **any time you buy a Backpack add-on, it is very likely that you're not only buying the _current_ version** (`v6` at the moment), **but also the upgrade to the _next version_** (`v7` for example). ### Add-ons From b01a9c481b1a04677612cf56544c2af2943beeeb Mon Sep 17 00:00:00 2001 From: Pedro Martins Date: Wed, 9 Oct 2024 14:49:37 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- 7.x-dev/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/7.x-dev/introduction.md b/7.x-dev/introduction.md index 7bab24a6..02ca3170 100644 --- a/7.x-dev/introduction.md +++ b/7.x-dev/introduction.md @@ -88,14 +88,14 @@ Backpack is open-core: ### Versioning, Updates and Upgrades -Starting with the previous version, all our packages follow [semantic versioning](https://semver.org/). Here's what `major.minor.patch` (e.g. `6.0.1`) means for us: +Starting with the previous version, all our packages follow [semantic versioning](https://semver.org/). Here's what `major.minor.patch` (e.g. `7.0.1`) means for us: - `major` - breaking changes, major new features, complete rewrites; released **once a year**, in February; it adds features that were previously impossible and upgrades our dependencies; upgrading is done by following our clear and detailed upgrade guides; - `minor` - new features, released in backwards-compatible ways; **every few months**; update takes seconds; - `patch` - bug fixes & small non-breaking changes; historically **every week**; update takes seconds; When we release a new Backpack\CRUD version, all paid add-ons receive support for it the same day. -When you buy a premium Backpack add-on, you get access to not only _updates_, but also _upgrades_ (for 12 months), that means that **any time you buy a Backpack add-on, it is very likely that you're not only buying the _current_ version** (`v6` at the moment), **but also the upgrade to the _next version_** (`v7` for example). +When you buy a premium Backpack add-on, you get access to not only _updates_, but also _upgrades_ (for 12 months), that means that **any time you buy a Backpack add-on, it is very likely that you're not only buying the _current_ version** (`v7` at the moment), **but also the upgrade to the _next version_** (`v8` for example). ### Add-ons