Skip to content

add docs for chip widget #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 25, 2025
Merged

add docs for chip widget #631

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c0ed9c0
add docs for chip widget
tabacitu Jun 21, 2025
2042b56
add new page for chips
tabacitu Jun 21, 2025
1cdcd74
change general chip syntax, polish docs
tabacitu Jun 25, 2025
07d8bc2
better docs for chip command
tabacitu Jun 25, 2025
7ad8a04
note about eager loading
tabacitu Jun 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions 7.x-dev/base-widgets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,6 +347,23 @@ class ChartjsPieController extends ChartController

```

<hr>

<a name="chip"></a>
### Chip

Shows a chip blade view - which is useful to show more information about a database entry, using little screen real estate.

```php
[
'type' => 'chip',
'view' => 'crud::chips.general',
'title' => 'invoices',
'entry' => Invoice::first(),
]
```


<hr>

<a name="datatable"></a>
Expand All @@ -360,7 +377,7 @@ Shows a datatable component from a particular CrudController. For more info abou
'controller' => 'App\Http\Controllers\Admin\PetShop\InvoiceCrudController',
'name' => 'invoices',
'setup' => function($crud, $parent) {
// you can use this closure to modify your CrudController definition.
// you can use this closure to modify your CrudController definition.
if ($parent) {
$crud->addClause('where', 'owner_id', $parent->id);
}
Expand Down Expand Up @@ -388,7 +405,7 @@ Allows you to include multiple widgets within a "div" element with the attribute
]
```

Anything you specify on this widget, other than ```type``` and ```content```, has to be a string, and will be considered an attribute of the "div" element.
Anything you specify on this widget, other than ```type``` and ```content```, has to be a string, and will be considered an attribute of the "div" element.
For example, in the following snippet, ```class``` and ```custom-attribute``` are attributes of the "div" element:

```php
Expand Down
222 changes: 222 additions & 0 deletions 7.x-dev/crud-chips.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,222 @@
# Chips

---

<a name="about"></a>
## About

A chips helps show the information of a database entry, in a format that takes up little space visually.

It can be used inside operations to:
- show more info inside a table cell in **ListOperation**;
- show a related item in more detail in **ShowOperation**;

A chip consists of only one file - a blade file with the same name as the chip type (ex: ```general.blade.php```). Backpack provides you with one chip type, that is designed to accomodate many types of database entries, but you can easily [create an entirely new chip type](#creating-a-custom-chip-type).

<a name="default-chip-types"></a>
### Default Chip Types

<a name="general-chip"></a>
#### General Chip

// TODO: add image of general chip

This chip was designed to be so general, that it's useful to show _most_ types of information from the database.

```php
@include('crud::chips.general', [
'text' => 'John Doe',
'title' => 'Example of a chip without URL',
'url' => 'https://google.com',
'target' => '_blank',
'image' => asset('uploads/person1.jpg'),
'details' => [
[
'icon' => 'la la-hashtag',
'text' => '8AH13A7',
'url' => 'mailto:[email protected]',
'title' => 'Click to email',
],
[
'icon' => 'la la-envelope',
'text' => '[email protected]',
'url' => 'mailto:[email protected]',
'title' => 'Click to email',
],
[
'icon' => 'la la-phone',
'text' => '+1 (555) 123-4567',
'url' => 'tel:+15551234567',
'title' => 'Click to call',
]
]
])
```

<a name="how-to-use-chips"></a>
### How to use chips

Depending on _where_ you want to use a chip, there are a few ways you can do that. Remember - a chip is a simple blade file, so the methods below should be pretty intuitive:

<a name="how-to-use-a-chip-inside-a-custom-blade-view"></a>
#### How to use a chip inside a custom blade view

// TODO: image with chip inside a custom blade view

If you want to load a chip inside a custom page, custom component or anything else custom, you can just include the blade view directly, and pass whatever attributes you want to show. For example, if you want to use the `general` chip you can just include that blade file, and pass some of the variables it supports:

```php
{{-- Example of General chip for a person, with data from Eloquent model --}}
@include('crud::chips.general', [
'text' => $user->name,
'url' => backpack_url('user/'.$user->id.'/show'),
'showImage' => false,
// 'image' => backpack_avatar_url($user), // doesn't work well with dummy data
'details' => [
[
'icon' => 'la la-hashtag',
'text' => $user->id,
'url' => backpack_url('user/'.$user->id.'/show'),
'title' => 'Click to preview',
],
[
'icon' => 'la la-envelope',
'text' => $user->email,
'url' => 'mailto:'.$user->email,
'title' => 'Click to email',
],
[
'icon' => 'la la-calendar',
'text' => $user->created_at->format('F j, Y'),
'title' => 'Created at '.$user->created_at,
]
]
])
```

<a name="how-to-use-a-chip-as-a-datatable-column"></a>
#### How to use a chip as a datatable column

// TODO: image of CRUD before and after using chips in a Datatable

When your datatables have too many columns, chips become very useful. They allow you to group multiple columns inside a chip, reducing the number of columns and thereby showing more information in less space. No longer will your admins have to expand the table row or use horizontal scrolling to see important info.

Remember, a chip is just a simple blade file. So to use a chip as a column, we can just use the `view` column type, and pass the path to our chip file. For example:

```php
// after we create an `invoice` chip
// we can use that chip as a column:
CRUD::addColumn([
'name' => 'info',
'type' => 'view',
'view' => 'crud::chips.invoice',
]);
```
By default, the view column type is not searchable. In order to make your chip columns searchable you need to [specify a custom ```searchLogic``` in your declaration](/docs/{{version}}/crud-columns#custom-search-logic).

<a name="how-to-use-a-chip-as-a-widget"></a>
#### How to use a chip as a widget

// TODO: image with chip as a widget

Chip files usually only contain the minimum content and styling necessary. You can include them as widgets directly, but they probably won't look very pretty on a custom page, because they don't have a background, borders, shadow etc. That's why we've also created a `chip` widget, which adds wrappers just like the other widgets - so that your chip will look good when placed on a custom page (or an existing CRUD page, why not).

To use the `chip` widget, you can do:

```php
Widget::add()
->to('after_content') // optional
->type('chip')
->view('crud::chips.owner')
->title('Owner')
->entry($owner);
```

<hr>

<a name="overwriting-default-chip-types"></a>
## Overwriting Default Chip Types

You can overwrite a chip type by placing a file with the same name in your ```resources\views\vendor\backpack\crud\chips``` directory. But it is NOT recommended to do so. When you're overwriting a default chip type, you're forfeiting any future updates for that chip. We can't push updates to a file that you're no longer using.

In 99.9% of the cases, it's recommended NOT to override the default `general` chip file, but to create a _custom_ chip file. That will make it a lot easier to upgrade to newer versions of Backpack - because the file is completely in your control.

<hr>

<a name="creating-a-custom-chip-type"></a>
## Creating a Custom Chip Type

Chips consist of only one file - a blade file with the same name as the chip type (ex: ```person.blade.php```). You can create one by placing a new blade file inside ```resources\views\vendor\backpack\crud\chips```. Be careful to choose a distinctive name - usually the model name works best.

// TODO: create this command
To create a new chip file in the standard directory, you can run `php artisan backpack:chip {chip-file-name}`. This will create a new file in that directory, from a stub, for you to customize however you want.

For example, you can do `php artisan backpack:chip person` to create a ```person.blade.php``` then includes the HTML content directly:

```html
<div class="card mb-2">
<div class="card-body">
<div class="row align-items-center bp-chip">
<div class="col-auto">
<div class="d-block">
<a href="https://google.com" title="Example of a chip" target="_blank" class="d-inline-block"><span class="avatar avatar-2 rounded" style="background-image: url(http://bp-v7-alpha7.test/uploads/person1.jpg)"> </span></a>
</div>
</div>
<div class="col text-truncate">
<div class="d-block">
<a href="https://google.com" class="mb-1 d-inline-block " title="Example of a chip without URL" target="_blank">
John Doe
</a>
</div>
<div class="d-block text-secondary text-truncate mt-n1">
<small class="d-inline-block me-1">
<i class="la la-hashtag" title="Click to email"></i>
<a href="mailto:[email protected]" class="text-reset" title="Click to email">8AH13A7</a>
</small>
<small class="d-inline-block me-1">
<i class="la la-envelope" title="Click to email"></i>
<a href="mailto:[email protected]" class="text-reset" title="Click to email">[email protected]</a>
</small>
<small class="d-inline-block me-1">
<i class="la la-phone" title="Click to call"></i>
<a href="tel:+15551234567" class="text-reset" title="Click to call">+1 (555) 123-4567</a>
</small>
</div>
</div>
</div>
</div>
```

But most likely, you'll want to create a chip that outputs some information for a particular database entry. If you like how the `general` chip looks, and only want to make it easy to re-use the chip, you can create a chip that includes the `general` chip. For example:

```php
@php
$last_purchase = $entry->invoices()->orderBy('issuance_date', 'DESC')->first()->issuance_date;
@endphp

@include('crud::chips.general', [
'text' => $entry->name,
'url' => backpack_url('pet-shop/owner/'.$entry->id.'/show'),
'image' => asset($entry->avatar->url),
// 'showImage' => false,
'details' => [
[
'icon' => 'la la-dog',
'text' => $entry->pets->count().' pets',
'title' => 'Number of pets: '.$entry->pets->count(),
],
[
'icon' => 'la la-shopping-cart',
'text' => $entry->invoices->count(). ' purchases',
'title' => 'Number of purchases: '.$entry->invoices->count(),
],
[
'icon' => 'la la-calendar',
'text' => $last_purchase->format('F j, Y'),
'title' => 'Last purchase: '.$last_purchase,
]
]
])
```

Otherwise, you can create a completely custom chip, that looks and works differently from the `general` chip. There are no limitations - since chips are simple blade files.
4 changes: 3 additions & 1 deletion 7.x-dev/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
- [3. Advanced Features](/docs/{{version}}/getting-started-advanced-features)
- [4. Add-ons, License & Support](/docs/{{version}}/getting-started-license-and-support)
- [Tutorials](/docs/{{version}}/tutorials)

#### Admin UI

- [About](/docs/{{version}}/base-about)
Expand All @@ -36,6 +36,7 @@
+ [Columns](/docs/{{version}}/crud-columns)
+ [Buttons](/docs/{{version}}/crud-buttons)
+ [Filters](/docs/{{version}}/crud-filters)
+ [Chips](/docs/{{version}}/crud-chips)
+ [Create](/docs/{{version}}/crud-operation-create) & [Update](/docs/{{version}}/crud-operation-update)
+ [Fields](/docs/{{version}}/crud-fields)
+ [Save Actions](/docs/{{version}}/crud-save-actions)
Expand All @@ -44,6 +45,7 @@
+ [Delete](/docs/{{version}}/crud-operation-delete)
+ [Show](/docs/{{version}}/crud-operation-show)
+ [Columns](/docs/{{version}}/crud-columns)
+ [Chips](/docs/{{version}}/crud-chips)
- [Additional Operations](/docs/{{version}}/crud-operations)
+ [Clone](/docs/{{version}}/crud-operation-clone)
+ [Reorder](/docs/{{version}}/crud-operation-reorder)
Expand Down