Filament Menu Builder

https://github.com/biostate/filament-menu-builder
Admin
This package provides a powerful and elegant menu builder for the Filament admin panel, enabling...
Tokens:23,522
Snippets:181
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and serve GitBook locally

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/SETUP.md

Commands to install the GitBook CLI globally, install GitBook dependencies, and serve the documentation locally at http://localhost:4000.

```bash
npm install -g gitbook-cli
```

```bash
gitbook install
```

```bash
gitbook serve
```

--------------------------------

### Install package via Composer

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Generic Composer command to install the package without specifying a version. Use this if you are unsure which version to install.

```bash
composer require biostate/filament-menu-builder
```

--------------------------------

### Publish and run migrations

Source: https://github.com/biostate/filament-menu-builder/blob/main/README.md

Publish the package migrations and run them to create the necessary database tables. Run these commands after installing the package.

```bash
php artisan vendor:publish --tag="filament-menu-builder-migrations"
php artisan migrate
```

--------------------------------

### Install package for Filament v3, v4, or v5

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Composer commands for installing the package for Filament v3, v4, and v5 respectively. Use the command matching your Filament version.

```bash
composer require biostate/filament-menu-builder:^1.0
```

```bash
composer require biostate/filament-menu-builder:^4.0
```

```bash
composer require biostate/filament-menu-builder:^5.0
```

--------------------------------

### Render menu with custom view

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/blade-components.md

Specify a custom view to render the menu. The example uses the default Bootstrap 5 view.

```html
<x-filament-menu-builder::menu 
    slug="main-menu" 
    view="filament-menu-builder::components.bootstrap5.menu"
/>
```

--------------------------------

### Basic Menuable trait usage with getMenuLinkAttribute

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

Add the Menuable trait to a model and implement getMenuLinkAttribute() to return the URL for the menu item. This is the minimal setup required to enable menu-model relationships.

```php
use Biostate\FilamentMenuBuilder\Traits\Menuable;

class Product extends Model
{
    use Menuable;
    
    public function getMenuLinkAttribute(): string
    {
        return route('products.show', $this);
    }
}
```

--------------------------------

### Upgrade from <5.0.4: default getMenuNameAttribute coalesces to empty string

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

Starting in 5.0.4, the default getMenuNameAttribute() returns an empty string instead of throwing a TypeError when $this->name is null. This change only affects models that rely on the default implementation.

```php
public function getMenuNameAttribute(): string
{
    return (string) ($this->name ?? '');
}
```

--------------------------------

### Build GitBook for GitHub Pages

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/SETUP.md

Builds the GitBook static site into a `_book` directory for deployment to GitHub Pages.

```bash
gitbook build
```

--------------------------------

### Build custom theme

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Run this command in your project root to build your custom theme after adding the package views.

```bash
npm run build
```

--------------------------------

### Publish views command

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/blade-components.md

Run this artisan command to publish the package views for customization.

```bash
php artisan vendor:publish --tag="filament-menu-builder-views"
```

--------------------------------

### Publish config file

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Publish the config file to customize package behavior. This step is optional.

```bash
php artisan vendor:publish --tag="filament-menu-builder-config"
```

--------------------------------

### Run tests with composer test

Source: https://github.com/biostate/filament-menu-builder/blob/main/README.md

Run the package's test suite.

```bash
composer test
```

--------------------------------

### Create GitHub Release with gh CLI

Source: https://github.com/biostate/filament-menu-builder/blob/main/RELEASING.md

Create a GitHub Release on top of the tag, which notifies watchers and appears on the Releases page.

```bash
gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes "<release notes — usually the same content as the CHANGELOG entry>"
```

--------------------------------

### Create and push annotated release tag

Source: https://github.com/biostate/filament-menu-builder/blob/main/RELEASING.md

Create an annotated tag for the release and push it to the remote repository.

```bash
git tag -a vX.Y.Z -m "vX.Y.Z release notes..."
git push origin vX.Y.Z
```

--------------------------------

### Commit and push CHANGELOG update

Source: https://github.com/biostate/filament-menu-builder/blob/main/RELEASING.md

Commit the CHANGELOG update to main and push it to the remote repository.

```bash
git commit -m "Update CHANGELOG for vX.Y.Z"
git push origin main
```

--------------------------------

### Create hotfix branch from tag

Source: https://github.com/biostate/filament-menu-builder/blob/main/RELEASING.md

Create a hotfix branch off the latest tag to apply a critical fix.

```bash
git checkout -b hotfix/foo vX.Y.Z
```

--------------------------------

### Registering models in config file

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

Register models in the config file under the 'models' key. You can add multiple models as shown.

```php
return [
    'models' => [
        'Product' => \App\Models\Product::class,
        'Category' => \App\Models\Category::class,
    ],
];
```

--------------------------------

### Add package views to theme.css

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Add this line to your generated theme.css to include the package's views in your custom Filament theme. Required for the package to work.

```css
@source '../../../../vendor/biostate/filament-menu-builder/resources/views/**/*';
```

--------------------------------

### Extending MenuResource

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/customization.md

Extend the base MenuResource in a similar way to customize labels.

```php
<?php

namespace App\CustomClasses;

use Biostate\FilamentMenuBuilder\Filament\Resources\MenuResource as BaseMenuResource;

class MenuResource extends BaseMenuResource
{
    public static function getModelLabel(): string
    {
        return 'Custom ' . parent::getModelLabel();
    }

    public static function getPluralModelLabel(): string
    {
        return 'Custom ' . parent::getPluralModelLabel();
    }
}
```

--------------------------------

### Using Custom Resources in AdminPanelProvider

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/customization.md

In your AdminPanelProvider.php, specify custom resource classes for Menu and MenuItem using the plugin's usingMenuResource() and usingMenuItemResource() methods.

```php
use App\CustomClasses\MenuResource;
use App\CustomClasses\MenuItemResource;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configurations
        ->plugins([
            \Biostate\FilamentMenuBuilder\FilamentMenuBuilderPlugin::make()
                ->usingMenuResource(MenuResource::class)
                ->usingMenuItemResource(MenuItemResource::class),
        ]);
}
```

--------------------------------

### Extending MenuItemResource

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/customization.md

Extend the base MenuItemResource to customize labels. Must extend the base class or implement the MenuItemResourceInterface with getFormSchema(), getFormSchemaArray(), and getUrl().

```php
<?php

namespace App\CustomClasses;

use Biostate\FilamentMenuBuilder\Filament\Resources\MenuItemResource as BaseMenuItemResource;

class MenuItemResource extends BaseMenuItemResource
{
    public static function getModelLabel(): string
    {
        return 'Custom ' . parent::getModelLabel();
    }

    public static function getPluralModelLabel(): string
    {
        return 'Custom ' . parent::getPluralModelLabel();
    }
}
```

--------------------------------

### SUMMARY.md navigation entry format

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/SETUP.md

Format for entries in SUMMARY.md to define the navigation structure, with optional indented subsections linking to anchors.

```markdown
* [Page Title](filename.md)
  * [Subsection](filename.md#anchor)
```

--------------------------------

### Render menu by slug

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/blade-components.md

Use the Blade component with the slug attribute to render the menu with the given slug.

```html
<x-filament-menu-builder::menu slug="main-menu" />
```

--------------------------------

### Using Custom Models in AdminPanelProvider

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/customization.md

In your AdminPanelProvider.php, specify custom model classes for Menu and MenuItem using the plugin's usingMenuModel() and usingMenuItemModel() methods.

```php
use App\Models\CustomMenu;
use App\Models\CustomMenuItem;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configurations
        ->plugins([
            \Biostate\FilamentMenuBuilder\FilamentMenuBuilderPlugin::make()
                ->usingMenuModel(CustomMenu::class)
                ->usingMenuItemModel(CustomMenuItem::class),
        ]);
}
```

--------------------------------

### Register FilamentMenuBuilderPlugin in AdminPanelServiceProvider

Source: https://github.com/biostate/filament-menu-builder/blob/main/README.md

Add the FilamentMenuBuilderPlugin to the Filament panel's plugin list in AdminPanelServiceProvider.php. This is required to enable the menu builder in the admin panel.

```php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Biostate\FilamentMenuBuilder\FilamentMenuBuilderPlugin::make(),
        ]);
}
```

--------------------------------

### Using model name as menu item name with getMenuNameAttribute

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

Extends the basic usage by adding getMenuNameAttribute() to control the label displayed for the menu item. Use this when the model name should be used as the menu item name.

```php
use Biostate\FilamentMenuBuilder\Traits\Menuable;

class Product extends Model
{
    use Menuable;
    
    public function getMenuLinkAttribute(): string
    {
        return route('products.show', $this);
    }
    
    public function getMenuNameAttribute(): string
    {
        return $this->name;
    }
}
```

--------------------------------

### Upgrade from <5.0.2: restore old label behavior

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

For upgrades from versions before 5.0.2, if you previously overrode getFilamentSearchLabel() to a non-name column and didn't override getMenuNameAttribute(), add this method to restore the old behavior. It returns the column value or an empty string.

```php
public function getMenuNameAttribute(): string
{
    return (string) ($this->title ?? '');
}
```

--------------------------------

### Add plugin to Filament panel

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/installation.md

Add the FilamentMenuBuilderPlugin to your Filament panel in AdminPanelServiceProvider.php. Place this line inside the plugins array.

```php
public function panel(Panel $panel): Panel
{
    return $panel
        // Your other configurations
        ->plugins([
            \Biostate\FilamentMenuBuilder\FilamentMenuBuilderPlugin::make(), // Add this line
        ]);
}
```

--------------------------------

### Customizing the search column with getFilamentSearchLabel

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/menuable-trait.md

Override getFilamentSearchLabel() to change the database column used in the LIKE search query. Must return an actual column name. The display label is controlled independently by getMenuNameAttribute().

```php
use Biostate\FilamentMenuBuilder\Traits\Menuable;

class Page extends Model
{
    use Menuable;

    public function getMenuLinkAttribute(): string
    {
        return route('pages.show', $this);
    }

    public function getMenuNameAttribute(): string
    {
        return $this->title;
    }

    public static function getFilamentSearchLabel(): string
    {
        return 'title';
    }
}
```

--------------------------------

### Custom route exclusion configuration

Source: https://github.com/biostate/filament-menu-builder/blob/main/docs/routes.md

Configure the 'exclude_route_names' option in your config file to exclude additional routes. The patterns use regular expressions for flexible matching.

```php
return [
    'exclude_route_names' => [
        '/^debugbar\./', // Exclude debugbar routes
        '/^filament\./',   // Exclude filament routes
        '/^livewire\./',   // Exclude livewire routes
        '/^api\./',        // Exclude API routes
        '/^admin\./',      // Exclude admin routes
    ],
];
```

--------------------------------

### Merge contributor PR with merge commit

Source: https://github.com/biostate/filament-menu-builder/blob/main/RELEASING.md

Merge a contributor PR using a merge commit and delete the branch, preserving contributor history.

```bash
gh pr merge <number> --merge --delete-branch
```
Tokens:
Raw