> ## Documentation Index
> Fetch the complete documentation index at: https://docs.advancedtables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Indicators

> Give users quick access to active filter indicators with clickable controls and support for pinned filters.

![Advanced indicators](https://advancedtables.com/images/advanced-indicators.png)

> Important: Advanced Indicators is one of the biggest additions to Advanced Tables since it's initial launch and I'm very excited to be able to bring this functionality to Filament. However, since there are still [outstanding features](/v3/features/advanced-indicators#specifying-favorite-filters-with-user-views-under-development) to be implemented, [known limitations](/v3/features/advanced-indicators#current-limitations-and-unknowns) that are under development, and there may be custom Filament implementations that haven't been accounted for, I am launching this as a beta feature. Please read all the instructions fully to know what is currently supported, what is under development, and what may not be supported. If you do find an issue, please reach out to me on discord our through email.

Advanced Indicators gives your users quick access to their filters through Filament's indicator system. When enabled, each indicator can be clicked on to access that filter's settings. In addition, filters can be favorited and "pinned" so they always appear, even when not active.

## Updating to the Advanced Indicators Beta

1. Update to the beta

   To update to the beta update your `composer.json` file to:

   ```bash theme={null}
   "archilex/filament-filter-sets": "^3.10@beta",
   ```

2. Compile assets

   After updating be sure to run `npm run build` and `php artisan filament:upgrade`.

3. Update Custom Filter Classes

   Advanced Indicators automatically overrides any default Filament filters you have included in your resource or page. However, any custom filter classes that you have created that extends a Filament filter will need to be updated to use Advanced Table's versions. This can be easily accomplished by just updating your imported class with the plugins equivalent:

   ```php theme={null}
   - use Filament\Tables\Filters\Filter
   + use Archilex\AdvancedTables\Filament\Filter

   - use Filament\Tables\Filters\SelectFilter
   + use Archilex\AdvancedTables\Filament\SelectFilter

   - use Filament\Tables\Filters\TernaryFilter
   + use Archilex\AdvancedTables\Filament\TernaryFilter

   - use Filament\Tables\Filters\TrashedFilter
   + use Archilex\AdvancedTables\Filament\TrashedFilter
   ```

   Remember, you only need to override *custom* filter classes you have created. Filters used within Filament's resources and pages will be overridden automatically.

4. Enable Advanced Indicators

   Advanced Indicators is disabled by default. To enable, add `advancedIndicatorsEnabled()` to your panel provider:

   ```php theme={null}
   AdvancedTablesPlugin::make()
       ->advancedIndicatorsEnabled()
   ```

5. Add the AdvancedTables trait

   If you haven't already, [add the AdvancedTables trait](/v3/get-started/getting-started#adding-advanced-tables-to-your-table) to your table.

6. Install Managed Default Views (optional)

   If you would also like to use the new Managed Default Views, [follow these instructions](/v3/features/managed-default-views#updating-to-the-managed-default-views-beta).

## Using Advanced Indicators

Once enabled, Advanced Indicators should work right out the box with minimal configuration. Just click on any indicator to see the form field(s) associated with that filter. Any adjustments to that filter will be immediately reflected in the table and synced to filament's filter form.

### Custom Filters with Multiple Form Fields

When implementing custom filters with multiple form fields in Filament, there are two main ways to display the indicator(s). You could display a single indicator that adapts according to the fields that are set, or you could have individual indicators for each field. As an example, take the following date filter examples which have two date fields, but display the indicator differently.

**Example 1 - Display as a single indicator:**

![Single indicator](https://advancedtables.com/images/single-indicator.png)

```php theme={null}
Filter::make('created_at')
    ->form([
        DatePicker::make('created_from'),
        DatePicker::make('created_until'),
    ])
    ->query(function (Builder $query, array $data): Builder {
        ...
    })
    ->indicateUsing(function (array $data): ?Indicator {                        
        if (($data['created_from'] ?? null) && (! ($data['created_until'] ?? null))) {
            return Indicator::make('Created from ' . Carbon::parse($data['created_from'])->toFormattedDateString());
        } 

        if ((! ($data['created_from'] ?? null)) && ($data['created_until'] ?? null)) {
            return Indicator::make('Created until ' . Carbon::parse($data['created_until'])->toFormattedDateString());
        } 

        if (($data['created_from'] ?? null) && ($data['created_until'] ?? null)) {
            return Indicator::make('Created between ' . Carbon::parse($data['created_from'])->toFormattedDateString() . ' and ' . Carbon::parse($data['created_until'])->toFormattedDateString());
        }

        return null;
    })
```

**Example 2 - Display as multiple indicators:**

![Multiple indicators](https://advancedtables.com/images/multiple-indicators.png)

```php theme={null}
Filter::make('published_at')
    ->form([
        DatePicker::make('published_from'),
        DatePicker::make('published_until'),
    ])
    ->query(function (Builder $query, array $data): Builder {
        ...
    })
    ->indicateUsing(function (array $data): array {                        
        $indicators = [];

        if ($data['published_from'] ?? null) {
            $indicators[] = Indicator::make('Published from ' . Carbon::parse($data['published_from'])->toFormattedDateString())
                ->removeField('published_from');
        }

        if ($data['published_until'] ?? null) {
            $indicators[] = Indicator::make('Published until ' . Carbon::parse($data['published_until'])->toFormattedDateString())
                ->removeField('published_until');
        }

        return $indicators;
    }),
```

Advanced Indicators supports both of these use cases. In the first example, only one indicator will be shown, but the form will include both fields. In the second, only the indicator's respective field will be displayed.

If you are using return types (and you should be) then Advanced Indicators will automatically detect how the indicators should be displayed. If you are not using return types, then you will need to be explicit about how Advanced Indicators should display your form fields using the `->multipleIndicators()` method:

**Example 1 - Display as a single indicator:**

```php theme={null}
Filter::make('created_at')
    ->multipleIndicators(false)
```

**Example 2 - Display as multiple indicators:**

```php theme={null}
Filter::make('created_at')`
    ->multipleIndicators()
```

> Note: Displaying indicators outside of these two examples (ie. a single indicator for all form fields, or a one-to-one field/indicator setup), is not currently supported. If you have a filter set up like this, please contact me.

### Favorite Filters

![Favorite filters](https://advancedtables.com/images/favorite-filters.png)

Advanced Indicators not only gives you quick access to applied filters, but also allows you to specify "favorite" filters which will always be displayed in the indicator bar, even when the filter is not active. You can make a filter a favorite by using the `->favorite()` method:

```php theme={null}
SelectFilter::make('brand')
    ->favorite()
```

> Note: Support for Filament's `->columns()` method on filters is coming soon.

### Limiting the Indicator labels

![Advanced indicators](https://advancedtables.com/images/advanced-indicators.png)

Advanced Indicators also introduces the ability to limit the number of labels that are shown on a Select Filter. Since you now have easy access to filters through the indicator, it may not be necessary to pollute the indicator bar with an excessively long indicator. To limit the indicator labels you may use the `->limitIndicatorLabels()` method:

```php theme={null}
SelectFilter::make('brand')
    ->limitIndicatorLabels(3)
```

By default, once the limit is reached Filament's localized version of `& 3 more` will be displayed. However, you may change this by publishing and updating the plugin's language files and updating the `more_indicator_labels` value in the `advanced-tables.php` language file:

```php theme={null}
'indicators' => [
    'more_indicator_labels' => '+ :count', // display as "+ 4"
],
```

### Specifying Favorite Filters in Preset Views

If you are using [Preset Views](/v3/features/preset-views) you may configure which filters should be displayed as favorites using the `->defaultFavoriteFilters()` method:

```php theme={null}
'recentlyCreated' => PresetView::make()
    ->favorite()
    ->defaultFavoriteFilters(['created_at'])
    ->defaultFilters([
        'created_at' => [
            'created_from' => now()->startOfWeek()->toDateString(),
            'created_until' => now()->endOfWeek()->toDateString(),
        ],
    ])
```

> Note: When defining default favorite filters, the order of the filters will be determined by the order they are in listed in Filament's ->filters() array. Support for ordering by the order of the ->defaultFavoriteFilters() array is coming.

### Specifying Favorite Filters with User Views (Under Development)

User-specified favorite filters is currently under development and should be released soon. When released, your users will be able to favorite, rearrange, and even hide filters according to their needs and then save that configuration as a [User View](/v3/features/user-views).

### Deferring Advanced Indicators

The current implementation of Advanced Indicators is for each indicator form to be live even if you are using Filament's [filter deferring](https://filamentphp.com/docs/3.x/tables/filters/getting-started#deferring-filters). Since each indicator is a subset of all the filters, deferring a single filter doesn't seem necessary.

However, if there is sufficient demand/need for it, I will look into bringing deferring to Advanced Indicators in the future. If implemented, each indicator dropdown would have it's own "Apply" button. Please contact me if this is a feature you need.

## Current Limitations and Unknowns

While Advanced Indicators should work for the majority of implementations, there are currently a few limitations and unknowns:

1. [Advanced Filter Builder](/v3/features/advanced-filter-builder) is not currently supported, but under development.
2. Custom filters may not be fully supported, but the goal is to support any implementation with Filament's filters. If something is not working as expected please contact me.
3. Third-party filter plugins have not been tested. If a filter plugin is not working, please contact me. Please note, that full support may require the plugin developer to update their filter.
4. Filament's Query Builder Filter is not currently supported. I am looking into supporting it, but if support comes it will be at the very end of this development period.

## Disabling Advanced Indicators

If you wish to disable Advanced Indicators, you may pass false to the `->advancedIndicatorsEnabled()` method:

```php theme={null}
AdvancedFilter::make()
    ->advancedIndicatorsEnabled(false)
```