--- url: /filament-relation-navigator/reference/ai-agents.md --- # AI agents The package teaches AI coding agents how to use it, so Claude Code, Codex, Cursor, Copilot and the like write the traits and options correctly: * **Laravel Boost**: the package ships guidelines and a skill (`relation-navigator-development`). Pick `wit3/filament-relation-navigator` when you run `php artisan boost:install` (or `boost:update`). * **llms.txt**: the documentation is also published for agents, as an index ([llms.txt](https://wit3.github.io/filament-relation-navigator/llms.txt)) and as one file ([llms-full.txt](https://wit3.github.io/filament-relation-navigator/llms-full.txt)). Every page has a Markdown version too: add `.md` to its URL. * **Without Boost**: point your agent to `vendor/wit3/filament-relation-navigator/resources/boost/skills/relation-navigator-development/SKILL.md`, for example from your `AGENTS.md` or `CLAUDE.md`. --- --- url: /filament-relation-navigator/reference/api.md --- # API reference Everything below is public API, covered by [semantic versioning](/reference/upgrade): it does not change in a breaking way within 1.x. Anything not listed here is internal. ## Traits | Trait | Use it on | What it does | |---|---|---| | `Concerns\HasRelationPages` | a resource | Every relation manager gets its own page | | `Concerns\InteractsWithRelationPage` | a relation manager | This relation manager gets a page; reads the optional static properties below | | `Concerns\HasRelationNavigator` | a record page (view, edit, custom) | The breadcrumb menu, and the page is listed in it | All in the `Wit3\FilamentRelationNavigator` namespace. ## On a resource All static, all optional. | Method | Purpose | |---|---| | `hasRelationPage(string $slug): bool` | Leave a relation out | | `canAccessRelationPage(Model $record, string $slug): bool` | Veto a relation page for a record (pages, menu, global search, redirect) | | `relationPageHeader(Schema $schema): Schema` | Header above the relation on every relation page | | `getRelationPageHeaderActions(): array` | Header actions of the relation pages | | `getRelationPageHeaderWidgets(): array`, `getRelationPageFooterWidgets(): array` | Widgets of the relation pages (they receive `$record`) | | `hasRelationPageLinks(): bool` | "Open as page" on its relation managers | | `configureRelationPageAction(Action $action, RelationManager $manager): Action` | Change that action for this resource | | `hasRelationPageGlobalSearchActions(): bool` | Global search links for this resource | | any [option method](/reference/configuration#options), static | The option for all the resource's pages | ## On a relation manager All static, all optional. Properties need `InteractsWithRelationPage`; methods work without it. | Property or method | Purpose | |---|---| | `$hasRelationPage`, `hasRelationPage(): bool` | A page for this relation manager or not | | `$relationPageSlug`, `getRelationPageSlug(): ?string` | The slug of its page | | `$hasRelationPageLink`, `hasRelationPageLink(): bool` | "Open as page" on its table | | `$hasRelationPageGlobalSearchAction`, `hasRelationPageGlobalSearchAction(): bool` | Its link under global search results | | `$hasRelationNavigatorBadge`, `hasRelationNavigatorBadge(): bool` | Its badge in the menu (the tab keeps its own) | | `getRelationPageTitle(Model $ownerRecord)` | Title of its page; `null` keeps the default | | `getRelationPageSubheading(Model $ownerRecord)` | Subheading of its page | | `getRelationPageBreadcrumb(Model $ownerRecord): ?string` | Last breadcrumb of its page | | `relationPageHeader()`, `getRelationPageHeaderActions()`, `getRelationPageHeaderWidgets()`, `getRelationPageFooterWidgets()` | Like on the resource, for its page only | | `configureRelationPageAction(Action $action, RelationManager $manager): Action` | Change its "Open as page" action | Filament's own `isBadgeLazyLoaded()` (or `$isBadgeLazyLoaded`) also makes its menu badge lazy. ## On a record page (`HasRelationNavigator`) Override any of them on the page: | Method | Purpose | |---|---| | the [option methods](/reference/configuration#options) | Options for this page | | `getRelationNavigatorRecordNavigationQuery(): ?Builder` | The records previous and next walk through | | `withRelationNavigator(array $breadcrumbs): array` | Add the menu to breadcrumbs you build yourself | ## A relation page class of your own Extend `Pages\RelationPage` (or run `php artisan make:filament-relation-navigator CustomerResource`), and spread `...CustomerRelationPage::relationRoutes()` into `getPages()`. | Member | Purpose | |---|---| | `protected static ?array $relations` | Only these slugs | | `protected static array $excludedRelations` | Never these slugs | | `protected static ?string $contextPage` | Key of the page it stands for (default: the view page, else the edit page) | | `$title`, `$subheading`, `$breadcrumb`, and every Filament page method | As on any Filament page | ## Helpers Static methods of `RelationNavigator`: | Method | Purpose | |---|---| | `getItems(string $resource, Model $record, ...)` | The menu items of a record | | `getRecordSubNavigation(Page $page): array` | The same items as Filament sub-navigation | | `getRelationManagerPageUrl(RelationManager $manager): ?string` | The page of a relation manager, for buttons of your own | | `getGlobalSearchResultActions(string $resource, Model $record): array` | Global search links, to merge into your own | | `configureRelationPageActionUsing(Closure $callback): void` | Change every "Open as page" action | | `makeRelationPageAction(RelationManager $manager): Action` | Build that action | | `getRelationPageClass(string $resource): ?string` | The relation page class of a resource | | `RELATION_PAGE_ACTION` | Name of the "Open as page" action | `RelationNavigatorItem` (in `$items`): `key`, `label`, `url`, `icon`, `badge`, `badgeColor`, `isActive`, `isBadgeDeferred`, `isRelationPage()`. ## Routes, views and commands * Route names: `{resource route base}.relations.{slug}`, for `getUrl('relations.orders', [...])`. * Views: `filament-relation-navigator::menu.github`, `menu.simple`, `menu.mobile`, `menu.partials.list`, `menu.partials.trigger-attributes`. Their variables are listed under [A preset of your own](/guide/menu-presets#a-preset-of-your-own). * Commands: `make:filament-relation-navigator {resource}`, `make:filament-relation-navigator-preset {name} --from=github|simple`. * Translations: `filament-relation-navigator::navigator.*`. --- --- url: /filament-relation-navigator/reference/changelog.md --- # Changelog All notable changes to `filament-relation-navigator` are documented here. ## Unreleased ## 1.8.1 - 2026-11-15 The package stays out of the relation managers and the lists that do not use it, and keeps the key of the last breadcrumb. The documentation site reads better on phones. No API changes. ### Fixed * The "Open as page" action is added only to the relation managers that have a relation page, their own or their group's. Before, every relation manager of the app got it, hidden, first in the header of its table: a test or a piece of code that took the first header action found it instead of its own. * With `record_navigation` turned on in the config, only the lists of resources that can show previous and next remember their records. Before, the list pages of every resource of the app wrote them to the session, at every render, including resources that do not use the package. * `withRelationNavigator()` keeps the key of the last breadcrumb when it is text: `[..., 0 => 'View']` no longer comes back as `[..., 1 => ...]`. A linked last breadcrumb still moves to a numeric key, so that the menu never ends up inside a link. ### Documentation * The example of a page that builds its own breadcrumbs declares `@return array`: the last breadcrumb becomes an `Htmlable`, and PHPStan (larastan) rejects Filament's `array`. * The documentation site reads better on phones: the screenshot under the heading at full width, tables as one card per row, long inline code wrapping, and the Arabic pages no longer wider than the screen. ## 1.8.0 - 2026-11-14 25 more languages in the package, and the documentation in eight more. No API changes. ### Added * Translations for Arabic, Bulgarian, Catalan, Chinese (simplified and traditional), Czech, Danish, Finnish, Greek, Hebrew, Hungarian, Indonesian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (Portugal), Romanian, Russian, Slovak, Swedish, Turkish, Ukrainian and Vietnamese: 32 languages, with Filament's codes. * In right to left languages the previous and next arrows turn around, as in Filament's pagination. ### Documentation * The documentation and the README in Spanish, Portuguese, French, German, Chinese, Japanese, Russian and Arabic (right to left), besides English and Italian. English is the reference: every translated page says so and links to it. ## 1.7.0 - 2026-11-14 Previous and next record on nested resources. No API changes. ### Added * Previous and next record on nested resources, within the same parent record: from one of a customer's orders to the next order of the same customer, on the view, edit and relation pages. * On a nested resource they follow the parent's relation manager table the user came from (sort, filters, search), when the nested resource is its related resource (`$relatedResource`). Not with the `cookie` session driver, which keeps the parent's list only. ## 1.6.2 - 2026-11-14 A keyboard fix in the menu, and documentation for every minor version. No API changes. ### Fixed * Opening the menu with a click no longer takes the focus back to the search field when the arrow keys have already moved it to a page. Menu views you published keep the old behaviour until you publish them again. ### Documentation * Documentation for every minor version, at `/vX.Y/` and in the versions menu: from its own site where it had one (1.4 onwards), else its README and changelog. * Screenshots of global search links, "Open as page" and the relation page header, and a GIF of previous and next record, in the README and the docs. * A banner on documentation of versions with a published security advisory: fixed and not dismissible for critical and high, dismissible for medium and low. Older versions without advisories say that a newer one exists. ## 1.6.1 - 2026-11-14 Fixes from a review of the whole package, faster relation pages, and the documentation site. No API changes. ### Fixed * "Open as page" links only to a relation page the user can open: the relation manager's `canViewForRecord()` and the resource's `canAccessRelationPage()` were not checked, so the link could end in a 403. It picks the best page the user can open. * Relation group badges: the color callback receives the badge, as in the tab, and a lazy group badge (`deferBadge()`) is lazy in the menu too. * Menu views that cannot load badges later (published before 1.3, presets of your own) get lazy tab badges with the page too: nothing disappears. * Shortcuts: the `cmd` alias works everywhere (tooltip, `aria-keyshortcuts`), a shortcut that cannot be matched is no longer advertised, and one returned by a page method is normalized and kept away from the global search like the config's. * `configureRelationPageAction()` also works as an instance method on a relation manager. * Previous and next: the remembered list is one compact string (about 170 numeric keys or 30 UUIDs per KB, so up to 100 records as documented), only one list is kept with the `cookie` session driver, records the user can edit but not view are offered, and neighbour queries skip the resource's eager loads. * The `?relation=` redirect leaves a reload of the view page alone, so its tabs stay reachable. * Properties of configured relation managers that are models or objects are compared by value, so "Open as page" stays after a table interaction. * No global search links for nested resources (their URLs need each result's parent). * A relation group without a string key whose label has no slug (a non-Latin script) gets `group-{key}` instead of no page. * Resources registered only through a configuration get their Livewire components registered. * The "Open as page" icon is the same with or without a published config. ### Changed * Relation pages work out their definitions, context page and class once per request: a relation page reads the resource's `getRelations()` 2 times instead of 66, a view page 3 instead of 19. * Filament 4.13 is now the lowest version allowed in `composer.json`, as tested since 1.2.1. * Package plumbing that was public or protected is marked `@internal` (`RelationNavigator::optsIn()`, `registerRoutes()`, `supportsDeferredBadges()`, the remembered-list methods and constants, most of `GeneratedRelationPages`, `RelationPage`'s protected helpers): not covered by semantic versioning from now on. Everything documented in the API reference stays. * `configureRelationPageActionUsing()` callbacks live in the application container: one list per application. ### Documentation * The site shows the latest release (home page, menu and footer, read from this changelog) and adds a configuration reference with defaults and levels, an API reference, recipes, troubleshooting, community links and a sitemap, in English and Italian. ## 1.6.0 - 2026-11-14 A security fix for relation pages of resources whose view page is not registered as `view` (or that have none), security hardening from an audit, badges loaded when the menu opens by default, and a customisable "Open as page" action. ### Security * **Relation pages applied the record's `view` policy only when the view page was registered under the key `view` (or the edit page under `edit`)** (1.3.0 to 1.5.0, [GHSA-mjj3-c8gm-4j73](https://github.com/wit3/filament-relation-navigator/security/advisories/GHSA-mjj3-c8gm-4j73)). With the view page under another key (`'details' => ViewCustomer::route(...)`), or with no view or edit page at all, relation pages checked only `canAccess()` and the relation manager's `canViewForRecord()`. The view page is now also found by its class, and without one the `view` policy applies. * A policy that denies "as not found" (`Response::denyAsNotFound()`) gives a 404 on relation pages too, as on the view page, instead of a 403 that told existing records apart. * Generated relation page classes: in the system temporary directory they go to a directory of this user only (0700, owner checked), and a file whose content is not the expected code is rewritten, never included. * Package methods that the browser does not need are `#[Unexposed]` (Filament 4.16 and later refuse browser calls to them); `getRelationNavigatorBadges()` stays callable and computes once per request. * `make:filament-relation-navigator-preset` accepts plain names and the package presets only. * "Open as page" and the tab redirect check the relation page's `canAccess()` before linking to it. ### Changed * The list remembered for previous and next is one session entry with the five most recent lists, about 1 KB each at most, so cookie sessions keep fitting in 4 KB. A table with `deferLoading()` is never loaded for it. * `menu.max_height` must be a CSS length (`24rem`, `400px`, `60vh`...); anything else falls back to `24rem`. * **Menu badges are loaded when the menu opens by default** (`menu.badges` = `'lazy'`): the menu is closed until then, so pages render without the badge queries, also on every Livewire request that redraws the breadcrumbs. Apps that published the config keep what they set. Menu views that cannot load badges later (published before 1.3, or presets of your own) get them with the page, as before. For the old behaviour: `'badges' => true`. ### Added * `canAccessRelationPage(Model $record, string $slug)` on a resource vetoes a relation page for a record: relation pages, menu, global search and redirect. It is the place for checks a view page makes in its own `authorizeAccess()` or `getRelationManagers()`, which relation pages do not run. * A relation manager can leave its badge out of the menu, keeping it in its tab: `hasRelationNavigatorBadge()` or `$hasRelationNavigatorBadge` with `InteractsWithRelationPage`. * `RelationNavigator::supportsDeferredBadges()`. * **"Open as page" can be customised**: config `relation_manager_action` (`style`: `link`, `button` or `icon_button`; `label`, `icon`, `icon_position`, `color`, `size`, `new_tab`), `RelationNavigator::configureRelationPageActionUsing()` for any change to the Filament action, and `configureRelationPageAction()` on a resource or a relation manager. `RelationNavigator::makeRelationPageAction()` builds it. ### Internal * CI: checkouts without persisted credentials; the documentation deploys from `main` only. ## 1.5.0 - 2026-11-14 Six improvements: global search links, per-relation titles, "Open as page" on group pages, lazy tab badges in the menu, previous/next that follow the list, and the documentation in Italian. Two behaviour changes, both in "Changed". ### Changed * **Previous and next follow the list the user came from** (config `record_navigation_follows_list`, default `true`; `shouldRelationNavigatorRecordNavigationFollowList()` on a page or resource): its sort, filters, search and tab, up to 100 records, instead of the key order. They stop at the ends of that list. Records not in the list, or with the option off, still walk by key. The list remembers its records in the session only when record navigation is on in the config or on the resource. * "Open as page" opens a relation manager's own page before the page of a relation group it also belongs to (it used to open whichever came first in `getRelations()`). A manager that exists only inside a group still opens the group's page. ### Added * **Documentation in Italian**: [wit3.github.io/filament-relation-navigator/it/](https://wit3.github.io/filament-relation-navigator/it/), from `README.it.md` (same sections as the README, checked by a test). * **Lazy tab badges stay lazy in the menu**: a relation manager with `$isBadgeLazyLoaded` (or `$isBadgeDeferred` on Filament 4.13) gets its menu badge when the menu opens, the others still come with the page. Filament's default is not lazy, so nothing changes unless you set it. `RelationNavigatorItem::$isBadgeDeferred`, and `RelationNavigator::getItems(..., resolveDeferredBadges: true)` to get every badge now. Published `menu/partials/list.blade.php` views need updating for it. * **Global search links to relation pages** (config `global_search_actions`: `false` by default, `true`, or the most links per result; resource `hasRelationPageGlobalSearchActions()`; relation manager `hasRelationPageGlobalSearchAction()` or `$hasRelationPageGlobalSearchAction`). `HasRelationPages` adds them to `getGlobalSearchResultActions()`; `RelationNavigator::getGlobalSearchResultActions()` for resources that define it themselves. * **"Open as page" on relation group pages**: a relation manager shown on its group's page links to its own page when it has one. * **Title, subheading and breadcrumb of one relation page** from its relation manager, given the owner record: `getRelationPageTitle()`, `getRelationPageSubheading()`, `getRelationPageBreadcrumb()` (static, optional, `null` keeps the default). The menu keeps the tab title. ## 1.4.1 - 2026-11-14 No code changes: documentation, AI tooling and repository hygiene. ### Added * **Laravel Boost skill** `relation-navigator-development` (`resources/boost/skills/`), next to the guidelines: workflows for relation pages, the menu, options, headers, presets and testing. The guidelines tell agents to use it. ### Documentation * A documentation site with search: [wit3.github.io/filament-relation-navigator](https://wit3.github.io/filament-relation-navigator/). It is built from the README, the changelog and the config file, so it always matches them. `composer.json` points `homepage` and `support.docs` to it. * The documentation is published for AI agents too: [llms.txt](https://wit3.github.io/filament-relation-navigator/llms.txt), [llms-full.txt](https://wit3.github.io/filament-relation-navigator/llms-full.txt) and a Markdown version of every page. ### Internal * GitHub Actions pinned to commit SHAs; Dependabot with a 7-day cooldown, now also for the npm dependencies of the browser tests and of the documentation site. * `AGENTS.md` (and `CLAUDE.md`) for contributors working with AI agents. ## 1.4.0 - 2026-11-14 Every feature can now be turned on or off globally, per resource and per page or relation manager. ### Added * **Options per resource**: every option of the menu is read from the page, then from a static method with the same name on the resource, then from the config. For example `public static function hasRelationNavigatorRecordNavigation(): bool` on a resource turns previous/next on for all its pages. Methods: `getRelationNavigatorPreset()`, `isRelationNavigatorSearchable()`, `hasRelationNavigatorBadges()`, `hasDeferredRelationNavigatorBadges()`, `getRelationNavigatorShortcut()`, `hasRelationNavigatorMobileMenu()`, `hasRelationNavigatorRecordNavigation()`, `shouldRedirectRelationNavigatorTabs()`. * **"Open as page" per resource and per relation manager**: `hasRelationPageLinks()` on a resource, `hasRelationPageLink()` (or `$hasRelationPageLink` with `InteractsWithRelationPage`) on a relation manager, on top of the config `relation_manager_link`. * **Laravel Boost guidelines** (`resources/boost/guidelines/core.blade.php`): pick the package in `boost:install` and AI agents learn the traits and options. * `RelationNavigator::addRelationPageAction()`, `hasRelationPageAction()` and the `RELATION_PAGE_ACTION` constant. ### Changed * **"Open as page" is now an action in the header of the relation manager's table**, next to its title and before its own actions, with an arrow icon. In 1.3.0 it was a link above the table, with an icon that looked like "full screen". ### Deprecated * `RelationNavigator::renderRelationManagerLink()` and the `relation-manager-link` view: the package no longer uses them. They still render the 1.3.0 link, for a render hook of your own, and will be removed in 2.0. ## 1.3.0 - 2026-11-14 A security fix, new features behind config switches, and a new default look for the menu. Update now if you use policies on your records. No breaking changes: every new key has a default in the code, so a published config from 1.2 keeps working. ### Security * **Relation pages did not apply the record's `view` policy** (1.0.0 to 1.2.1, [GHSA-v3mh-w7qp-37gc](https://github.com/wit3/filament-relation-navigator/security/advisories/GHSA-v3mh-w7qp-37gc)). Filament checks it when the view page mounts, not in `canAccess()`, and relation pages only called `canAccess()`: a user denied `view` on a record, but allowed `viewAny`, could open its relation pages and see the related records and the header. Relation pages now run the same record check as the page they stand for (`view` for a view page, `update` for an edit page), also on every Livewire request. ### Added * **Links to relation manager tabs open the relation page** (config `redirect_relation_tabs`, default `false`): `/customers/1?relation=bills` on the view or edit page redirects to `/customers/1/bills`, with `wire:navigate` in SPA mode. Tabs without a relation page, or that the record cannot see, stay where they are. Per page: `shouldRedirectRelationNavigatorTabs()` and `getRelationNavigatorTabRedirectUrl()`. * **Deferred badges**: `menu.badges` also takes `'lazy'`. The page then renders without the badge queries, and the menu loads the badges when it opens (one request, a spinner meanwhile). New page methods `hasDeferredRelationNavigatorBadges()` and `getRelationNavigatorBadges()`, and `$hasDeferredBadges` for preset views. If you published the package views, update `menu/partials/list.blade.php` before turning it on, or the menu shows no badges. * **Previous and next record** buttons before the header actions of the pages with the menu (config `record_navigation`, default `false`). They open the neighbour by key on the same page (view, edit, a relation page), or on its first page in the menu when it cannot open that one, and are disabled at the ends. They use the resource's own query, so tenancy and your scopes apply. Per page: `hasRelationNavigatorRecordNavigation()`, `getRelationNavigatorRecordNavigationQuery()`, `getRelationNavigatorRecordNeighbours()`. Nested resources are not supported yet: they show no buttons. * **"Open as page"** link above the table of every relation manager that has its own page, on the view and edit pages (config `relation_manager_link`, default `true`). It links to the relation group's page for a manager inside a group, and tells apart two entries of the same manager (`PostsRelationManager::make([...])`) by their properties. `RelationNavigator::getRelationManagerPageUrl()` returns the same URL for your own buttons. * `RelationPage::canAccessRecord()` and `RelationNavigator::canAccessRecordPage()`: the record check of the view and edit pages. ### Fixed * The menu lists the view and edit pages only when the user can open them for the record (`view` and `update` policies): a user who cannot edit a record no longer sees an Edit item that ends in a 403. ### Changed * **The default menu is now the `github` preset with the search field** (`menu.preset` = `github`, `menu.searchable` = `true`): it is the one with the most features. Apps that published the config keep what they set. To keep the menu of 1.2 and earlier, set `'preset' => 'simple'` and `'searchable' => false` in `config/filament-relation-navigator.php`, or override `getRelationNavigatorPreset()` and `isRelationNavigatorSearchable()` on the page. ### Internal * Tests for each feature, tenancy, nested resources and record policies included, and a browser test for the deferred badges. README with a GIF and new screenshots. ## 1.2.1 - 2026-11-14 Bug fixes and tests. No API changes. ### Fixed * Resources registered through a configuration (`UserResource::make('admins')`) had no generated relation pages: they now get them under the configuration's slug, with its middleware, as Filament does for the resource's own pages. * On a read-only storage (read-only containers, serverless) the generated page classes go to the system temporary directory. If no directory is writable, the error says how to choose one. * With a `mod` shortcut, `aria-keyshortcuts` declares both variants (`Meta+…` and `Control+…`) instead of only `Meta`. * While searching, the separator line no longer shows on top of the list when the block above it is filtered out. ### Internal * Tests with cached routes, configured resources and `RelationManager::make([...])` entries. * CI: a job on the lowest allowed versions (Filament 4.13, Laravel 12, Livewire 3.8), browser tests on Filament 4 too, releases published from the changelog when a tag is pushed, Dependabot for the GitHub Actions. ## 1.2.0 - 2026-11-14 ### Added * **Tooltip** on the button that opens the menu: the heading and the shortcut keys, shown as ⌥ ⇧ R on a Mac and Alt Shift R elsewhere. * **Shortcut** that opens the menu from anywhere on the page with the search field ready, like GitHub's repository switcher. Config `menu.shortcut` (default `alt+shift+r`, `null` turns it off), or `getRelationNavigatorShortcut()` per page. It matches the physical key (any keyboard layout, Option on a Mac), does nothing while typing in a field, opens only the visible menu, and is never registered when it equals one of the panel's global search shortcuts. * `RelationNavigator::getShortcutKeys()`, `getShortcutCondition()` and `clashesWithFilament()`; `$shortcut` and `$shortcutKeys` for preset views, and the `menu.partials.trigger-attributes` partial for buttons of your own. ### Changed * The caret of the `github` preset has a light background, lighter on hover, as on GitHub. Run `php artisan filament:assets` after updating. * `HasRelationNavigator` declares `getRecord()` and `hasRecord()` as abstract. Record pages already have them, so nothing changes for them. A page using the trait without a record, which already failed when rendered since 1.0.1, now fails when its class is loaded, with a clear PHP error; because the menu loads the record pages of the resource, this also breaks the other record pages of that resource until the trait is removed from that page. ## 1.1.0 - 2026-11-14 New features, all backwards compatible. ### Added * **Small screens**: Filament hides the breadcrumbs below 40rem; there the menu now shows above the page heading, on the pages that use `HasRelationNavigator`. Config `menu.mobile` (default `true`), or `hasRelationNavigatorMobileMenu()` per page. Its few style rules are inline, so it works even if `filament:assets` was not run after the update. * **Keyboard navigation** in the menu: Down from the search field enters the list, Up and Down move between the pages, Up from the first one goes back to the search field. * **Separator** between the record pages and the relation pages. Config `menu.separator` (default `true`). * `RelationNavigatorItem::isRelationPage()`, and `$hasSeparator` for preset views. * Translations: Spanish, German, French, Brazilian Portuguese and Dutch. ### Changed * The menu looks slightly different with the separator on (a line between the two blocks). Set `menu.separator` to `false` to keep the 1.0 look. * Run `php artisan filament:assets` after updating to get the separator line. ## 1.0.1 - 2026-11-14 Bug fixes and tests. No API changes. ### Fixed * With a relation page class you wrote, a relation whose URL equals one of the resource's own pages (for example `relationRoutes()` spread after `'timeline' => ...::route('/{record}/timeline')`) replaced that page. The resource's page now always wins and that relation has no page. Generated relation pages were not affected. * Relation managers' badges are computed once per request, even when the breadcrumb menu and the record sub-navigation both show them. * A menu preset pointing to a missing view now says which config option to check, instead of a generic "View not found". ### Changed * `HasRelationNavigator` assumes the page has a record, as documented. On a page without a record it did nothing before; now it fails like any other record method. ### Internal * Tests for nested resources, clusters, tenancy and SPA mode, and browser tests for the searchable menu. * PHPStan (Larastan) at level 8 in CI. ## 1.0.0 - 2026-11-14 First public release. * Every relation manager of a resource can have its own page at `/{record}/{slug}`, rendering the relation manager you already have: same table, actions, badges and authorization. * Opt in with `HasRelationPages` on the resource or `InteractsWithRelationPage` on a relation manager. No page class to write: the routes join the resource's own route group and the page class is generated on demand. Works with `route:cache`. * Optional page class of your own (`make:filament-relation-navigator`) to customise the relation pages. * Header above the relation (`relationPageHeader()`), header actions and header/footer widgets, from the resource or the relation manager. * Breadcrumb menu with the record pages that use `HasRelationNavigator` and every relation page the user can see. * Menu presets `simple` and `github`, optional search, badges, presets of your own (`make:filament-relation-navigator-preset`) and publishable views. * Native record sub-navigation from the same items. * English and Italian translations. * Filament 4 and 5, Laravel 12 and 13, PHP 8.2 to 8.5. --- --- url: /filament-relation-navigator/reference/configuration.md --- # Configuration Publish the config file to change the defaults for every resource: ```bash php artisan vendor:publish --tag=filament-relation-navigator-config ``` A published config keeps working across minor versions: every key has a default in the code, so new keys only need adding when you want to change them. ## Options Most options can also be set **per resource** (a static method on the resource) or **per page or relation manager**: * **Menu options** (`menu.*` with a method, record navigation, tab redirect): the page wins, then the resource, then the config. * **"Open as page"** and **a relation manager's menu badge**: shown only when every level allows it; any level can turn it off. * **Global search links**: the resource's method replaces the config for that resource; a relation manager can only leave itself out. * **The list remembered for previous and next**: decided by the resource or the config only, since the list page cannot ask a record page. * `menu.presets`, `menu.search_from`, `menu.max_height` and `menu.separator` are config only. | Key | Default | What it does | Other levels | |---|---|---|---| | `menu.preset` | `'github'` | The menu's look: `github`, `simple`, a preset of yours or a view name | `getRelationNavigatorPreset()` | | `menu.presets` | `simple`, `github` | Names and views of the presets | | | `menu.searchable` | `true` | A search field on top of the list | `isRelationNavigatorSearchable()` | | `menu.search_from` | `0` | Show the search field from this many items | | | `menu.badges` | `'lazy'` | `'lazy'`: badges load when the menu opens; `true`: with the page; `false`: none | `hasRelationNavigatorBadges()`, `hasDeferredRelationNavigatorBadges()`; relation manager: `hasRelationNavigatorBadge()` | | `menu.max_height` | `'24rem'` | Height of the list before it scrolls (a CSS length) | | | `menu.separator` | `true` | Record pages and relation pages in two blocks | | | `menu.mobile` | `true` | The menu above the heading on small screens | `hasRelationNavigatorMobileMenu()` | | `menu.shortcut` | `'alt+shift+r'` | Keyboard shortcut that opens the menu; `null`: none | `getRelationNavigatorShortcut()` | | `relation_manager_link` | `true` | The "Open as page" action on relation manager tables | resource `hasRelationPageLinks()`, relation manager `hasRelationPageLink()` | | `relation_manager_action` | link with an arrow | Look of that action: `style`, `label`, `icon`, `icon_position`, `color`, `size`, `new_tab` | `configureRelationPageActionUsing()`, `configureRelationPageAction()` | | `global_search_actions` | `false` | Links to relation pages under global search results: `true` or the most per result | resource `hasRelationPageGlobalSearchActions()`, relation manager `hasRelationPageGlobalSearchAction()` | | `record_navigation` | `false` | Previous and next record buttons | `hasRelationNavigatorRecordNavigation()` | | `record_navigation_follows_list` | `true` | Previous and next follow the list the user came from | `shouldRelationNavigatorRecordNavigationFollowList()` | | `redirect_relation_tabs` | `false` | `?relation=x` on the view page opens the relation page | `shouldRedirectRelationNavigatorTabs()` | Page methods are instance methods on a record page using `HasRelationNavigator`; on a resource the same method is static and applies to all its pages. See [Page, resource or config](/guide/menu-presets#page-resource-or-config). ## The whole file As shipped with the current version: ```php 'simple'` and `'searchable' => false`. | | Add your own preset by pointing a name to any view, or publish the | package views and change them: | | php artisan vendor:publish --tag=filament-relation-navigator-views | | A page can override these with getRelationNavigatorPreset(), | isRelationNavigatorSearchable() and hasRelationNavigatorBadges(). | */ 'menu' => [ 'preset' => 'github', 'presets' => [ 'simple' => 'filament-relation-navigator::menu.simple', 'github' => 'filament-relation-navigator::menu.github', ], 'searchable' => true, // With `searchable`, the search field appears from this many items. 'search_from' => 0, // The relation managers' badges, as in their tabs. 'lazy' (default) // loads them when the menu opens, so the page renders without their // queries; true renders them with the page; false turns them off. A // relation manager can leave its badge out: hasRelationNavigatorBadge(). 'badges' => 'lazy', 'max_height' => '24rem', // The record pages and the relation pages in two blocks. 'separator' => true, // Filament hides the breadcrumbs on small screens: show the menu // above the page heading there. 'mobile' => true, // Opens the menu from anywhere on the page, outside text fields: // modifiers (alt, shift, ctrl, meta, or mod: ⌘ on a Mac, Ctrl // elsewhere) plus a letter, a digit or / . , ; Null turns it off. // A shortcut of the panel's global search is ignored, never doubled. 'shortcut' => 'alt+shift+r', ], /* |-------------------------------------------------------------------------- | Relation managers on the record pages |-------------------------------------------------------------------------- | | An "Open as page" action in the header of the table of every relation | manager that has its own page, on the view and edit pages. Per resource: | hasRelationPageLinks(); per relation manager: hasRelationPageLink(). | */ 'relation_manager_link' => true, // Its look. `style`: link, button or icon_button (the label becomes a // tooltip). `label`: text or translation key (null: "Open as page", // translated). `icon`: any Filament icon, or null for none. For more, // RelationNavigator::configureRelationPageActionUsing() in a service // provider, or configureRelationPageAction() on a resource or a relation // manager. 'relation_manager_action' => [ 'style' => 'link', 'label' => null, 'icon' => 'heroicon-m-arrow-up-right', 'icon_position' => 'after', 'color' => 'gray', 'size' => null, 'new_tab' => false, ], /* |-------------------------------------------------------------------------- | Global search |-------------------------------------------------------------------------- | | Links to the record's relation pages under its global search results: | false, true, or the most links to show per result. Per resource: | hasRelationPageGlobalSearchActions(); per relation manager: | hasRelationPageGlobalSearchAction(). They run the relation managers' | canViewForRecord() for every result. | */ 'global_search_actions' => false, /* |-------------------------------------------------------------------------- | Previous and next record |-------------------------------------------------------------------------- | | Two buttons before the header actions of the pages with the menu: they | open the previous or the next record on the same page. Off by | default: they add a few queries per render. Per page, override | hasRelationNavigatorRecordNavigation(); to change the records, | getRelationNavigatorRecordNavigationQuery(). Not for nested resources. | */ 'record_navigation' => false, // Previous and next follow the list the user came from (the list page, // or the parent's relation manager for a nested resource): its sort, // filters, search and tab (up to 100 records), instead of the key order. 'record_navigation_follows_list' => true, /* |-------------------------------------------------------------------------- | Links to relation manager tabs |-------------------------------------------------------------------------- | | A link to a tab of the view or edit page (`/customers/1?relation=bills`) | opens the relation page instead (`/customers/1/bills`). Handy once the | relation pages replace the tabs; off by default. | */ 'redirect_relation_tabs' => false, ]; ``` --- --- url: /filament-relation-navigator/reference/contributing.md --- # Contributing Issues and pull requests are welcome. Please run `composer test`, `composer analyse` and `composer format` before opening a pull request. ## Testing ```bash composer test # the test suite composer analyse # PHPStan, level 8 composer format # Pint ``` The suite runs on Filament 4 and 5, Laravel 12 and 13, PHP 8.2 to 8.5, and covers nested resources, clusters, tenancy and SPA mode. The browser tests (the searchable menu) need Playwright: ```bash npm install && npx playwright install chromium vendor/bin/testbench filament:assets composer test:browser ``` ## Security Please report security issues privately through [GitHub security advisories](https://github.com/wit3/filament-relation-navigator/security/advisories/new) rather than in public issues. ## Credits * [Salvatore Scalzi](https://github.com/wit3) * [All contributors](https://github.com/wit3/filament-relation-navigator/contributors) ## License The MIT License (MIT). See [LICENSE](https://github.com/wit3/filament-relation-navigator/blob/main/LICENSE.md). --- --- url: /filament-relation-navigator/guide/customising-the-relation-pages.md --- # Customising the relation pages ### Title, subheading and breadcrumb of one relation A relation manager can set them for its own page, from the record, with no page class: ```php class OrdersRelationManager extends RelationManager { public static function getRelationPageTitle(Model $ownerRecord): string|Htmlable|null { return "Orders of {$ownerRecord->name}"; } public static function getRelationPageSubheading(Model $ownerRecord): string|Htmlable|null { return 'Last 12 months'; } public static function getRelationPageBreadcrumb(Model $ownerRecord): ?string { return 'Orders'; } } ``` Return `null` to keep the default. A page class you wrote (below) wins with its own `$title`, `$subheading` and `$breadcrumb`. The menu and the tabs keep the relation manager's title. Relation groups have no relation manager, so their page uses the group label. ### A page class of your own The generated relation pages cover most needs. To change their title, their breadcrumbs or anything else a Filament page can do, write the page class yourself; the package then uses yours for that resource: ```bash php artisan make:filament-relation-navigator CustomerResource ``` ```php class CustomerRelationPage extends RelationPage { protected static string $resource = CustomerResource::class; protected static ?array $relations = ['orders', 'invoices']; // only these protected static array $excludedRelations = ['notes']; // never these } ``` ```php public static function getPages(): array { return [ 'index' => ListCustomers::route('/'), 'view' => ViewCustomer::route('/{record}'), ...CustomerRelationPage::relationRoutes(), ]; } ``` The class is a regular Filament page: override `getTitle()`, `getBreadcrumbs()`, `getHeaderActions()`, use your own traits, and so on. --- --- url: /filament-relation-navigator/guide/global-search.md --- # Global search Global search results can link straight to the record's relation pages: search a customer, jump to its orders. Off by default, since it runs the relation managers' `canViewForRecord()` for every result: ```php // config/filament-relation-navigator.php 'global_search_actions' => 3, // true for all of them, or the most links per result ``` ```php // On a resource: on or off for this resource only public static function hasRelationPageGlobalSearchActions(): bool { return true; } ``` ```php // On a relation manager (with InteractsWithRelationPage): never linked protected static bool $hasRelationPageGlobalSearchAction = false; ``` Resources with `HasRelationPages` get the links by themselves. A resource that defines `getGlobalSearchResultActions()` itself, or that opts in only from its relation managers, merges them in: ```php public static function getGlobalSearchResultActions(Model $record): array { return [ // ...your actions ...RelationNavigator::getGlobalSearchResultActions(static::class, $record), ]; } ``` The links follow the same rules as the menu: only the relation pages the user can open. --- --- url: /filament-relation-navigator/guide/header-actions-and-widgets.md --- # Header, actions and widgets Above the relation, a relation page can show part of the record's view, header actions and widgets. Define them on the resource for every relation page, or on a relation manager for its own page: ```php public static function relationPageHeader(Schema $schema): Schema { // The whole infolist (static::infolist($schema)) or a piece of it. return $schema->components([ CustomerCard::make(), ]); } public static function getRelationPageHeaderActions(): array { return [ Action::make('email') ->url(fn (Customer $record): string => "mailto:{$record->email}"), ]; } public static function getRelationPageHeaderWidgets(): array { return [CustomerStats::class]; // receives the record as $record } public static function getRelationPageFooterWidgets(): array { return []; } ``` * The header of a relation manager replaces the resource's one; actions and widgets of both are shown, the resource's first. * Header actions act on the record the relation belongs to. * With a header, the record's name is not repeated under the title. * Pieces that only exist inside the view page class (its own methods and modals) are not reachable from here: move them to the resource, to an action class or to a trait. --- --- url: /filament-relation-navigator/reference/how-it-works.md --- # How it works * The routes are registered through Filament's own `Resource::registerRoutes()`, inside each resource's route group: slug, cluster, parent resource and tenant are handled by Filament. * The page class of a resource is written on demand to `storage/framework/cache`, the way Laravel's real-time facades work, and registered with Livewire. It works with `route:cache`. * The relation page embeds the relation manager as Filament does in the tabs, so its state, actions and modals stay in the relation manager. --- --- url: /filament-relation-navigator/guide/installation.md --- # Installation ```bash composer require wit3/filament-relation-navigator php artisan filament:assets ``` Run `filament:assets` again after each update: Filament copies the plugin's stylesheet into `public/`. --- --- url: /filament-relation-navigator/guide/introduction.md --- # Introduction Give every relation manager of a Filament resource **its own page**, and jump between them from a **menu in the breadcrumb**. * `/customers/1?relation=orders` becomes **`/customers/1/orders`**: a real route you can link, bookmark and open in a new tab. * The page renders the **relation manager you already have**: same table, filters, actions, badges and authorization. Nothing is duplicated. * Add a **header** above the relation (the record's card, widgets, actions), taken from the resource. * The last breadcrumb opens a **menu** with the record's pages and every relation the user can see, with icons and badges. Two looks, optional search and keyboard navigation, a view of your own, and a version for small screens. * **Previous and next record** on the same page, an **"Open as page"** action on every relation manager table, and links to old tabs that land on the new pages: each one switchable globally, per resource or per page. * **One trait, no page classes**: no files to generate, nothing to add to `getPages()` or to the panel provider. * **32 languages**, right to left ones included, with Filament's codes. The documentation is in 10. ## Requirements | Package | Version | | -------- | -------------------- | | PHP | 8.2+ | | Laravel | 12, 13 | | Filament | 4.13+, 5.x | --- --- url: /filament-relation-navigator/guide/links-to-relation-manager-tabs.md --- # Links to relation manager tabs Once the relation pages replace the tabs, old links such as `/customers/1?relation=orders` can open `/customers/1/orders` instead: ```php 'redirect_relation_tabs' => true, ``` Tabs without a relation page, or that the record cannot see, stay where they are. --- --- url: /filament-relation-navigator/guide/menu-presets.md --- # Menu presets and options Publish the config: ```bash php artisan vendor:publish --tag=filament-relation-navigator-config ``` ```php 'menu' => [ 'preset' => 'github', // 'simple', a preset of yours, or a view name 'presets' => [ 'simple' => 'filament-relation-navigator::menu.simple', 'github' => 'filament-relation-navigator::menu.github', ], 'searchable' => true, // a search field on top of the list, whatever the preset 'search_from' => 0, // ...from this many items 'badges' => 'lazy', // the relation managers' badges: 'lazy' when the menu opens, true with the page, false off 'max_height' => '24rem', 'separator' => true, // record pages and relation pages in two blocks 'mobile' => true, // the menu above the heading on small screens 'shortcut' => 'alt+shift+r', // opens the menu; null turns it off ], ``` **github** (the default): the last breadcrumb stays text and a caret next to it opens a panel with a heading, a search field and a check on the current page, like GitHub's repository switcher. The field gets the focus when the menu opens and Enter opens the first match. **simple**: the last breadcrumb itself opens the list. For the menu of 1.2 and earlier, set `'preset' => 'simple'` and `'searchable' => false`. ### Badges The menu shows the relation managers' badges, as in their tabs. By default they are **loaded when the menu opens**: the menu is closed until then, so the page renders without their queries, also on every Livewire request that redraws the breadcrumbs. A spinner shows for the moment they take. ```php 'badges' => 'lazy', // default; true: with the page; false: no badges ``` Turn them off where you need to: ```php // A page, or a resource (static): no badges in this menu public function hasRelationNavigatorBadges(): bool { return false; } // A relation manager (with InteractsWithRelationPage): its badge stays in // the tab, not in the menu protected static bool $hasRelationNavigatorBadge = false; ``` A relation manager whose tab badge is lazy in Filament (`protected static ?bool $isBadgeLazyLoaded = true;`, or `$isBadgeDeferred` on Filament 4.13) is lazy in the menu too, even with `'badges' => true`. Menu views that cannot load badges later (package views published before 1.3, or presets of your own that render `$item->badge` themselves) get them with the page, as before: nothing disappears. **Keyboard**: from the search field, Down moves into the list; Up and Down move between the pages, Enter opens one, Escape closes the menu. ### Shortcut and tooltip The button that opens the menu has a tooltip with the shortcut, shown with Mac or Windows/Linux keys. The shortcut opens the menu from anywhere on the page, with the search field ready, like GitHub's repository switcher: ⌥ ⇧ R on a Mac, Alt Shift R elsewhere. Change it in the config or per page: ```php 'shortcut' => 'mod+shift+p', // mod is ⌘ on a Mac and Ctrl elsewhere ``` ```php public function getRelationNavigatorShortcut(): ?string { return null; // no shortcut on this page } ``` It is built not to get in the way: * it matches the physical key, so it works with any keyboard layout and with Option on a Mac (where ⌥⇧R types ‰); * it does nothing while you type in a field; * a shortcut of the panel's global search (`globalSearchKeyBindings()`) is never taken: the menu then has no shortcut; * only the visible menu opens (breadcrumbs or small screens). Supported keys: `alt`, `shift`, `ctrl`, `meta`, `mod` plus a letter, a digit or `/ . , ;`. ### Page, resource or config Every option has three levels. The page wins, then the resource, then the config: | Page method (static on the resource) | Config key | |---|---| | `getRelationNavigatorPreset(): string` | `menu.preset` | | `isRelationNavigatorSearchable(): bool` | `menu.searchable` | | `hasRelationNavigatorBadges(): bool` | `menu.badges` | | `hasDeferredRelationNavigatorBadges(): bool` | `menu.badges` = `'lazy'` | | `getRelationNavigatorShortcut(): ?string` | `menu.shortcut` | | `hasRelationNavigatorMobileMenu(): bool` | `menu.mobile` | | `hasRelationNavigatorRecordNavigation(): bool` | `record_navigation` | | `shouldRelationNavigatorRecordNavigationFollowList(): bool` | `record_navigation_follows_list` | | `shouldRedirectRelationNavigatorTabs(): bool` | `redirect_relation_tabs` | ```php // On one page public function isRelationNavigatorSearchable(): bool { return false; } ``` ```php // On a resource: the same method, static, for all its pages public static function hasRelationNavigatorRecordNavigation(): bool { return true; } ``` ### Small screens Filament hides the breadcrumbs below 40rem. There the menu shows above the page heading instead, on every page that uses `HasRelationNavigator`, with the same preset options. Turn it off with `'mobile' => false`, or per page: ```php public function hasRelationNavigatorMobileMenu(): bool { return false; } ``` ### Translations 32 languages, with the same codes as Filament: Arabic, Bulgarian, Catalan, Chinese (simplified and traditional), Czech, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (Portugal and Brazil), Romanian, Russian, Slovak, Spanish, Swedish, Turkish, Ukrainian and Vietnamese. In right to left languages the previous and next arrows turn around. Publish the translations to change them or add a language: ```bash php artisan vendor:publish --tag=filament-relation-navigator-translations ``` ### A preset of your own Start from one of the package presets: ```bash php artisan make:filament-relation-navigator-preset compact --from=github ``` It copies the preset to `resources/views/filament/relation-navigator/compact.blade.php`. Register it and change it as you like: ```php 'preset' => 'compact', 'presets' => [ // ... 'compact' => 'filament.relation-navigator.compact', ], ``` Any view name works as `preset` too. To change the package presets themselves, publish their views: ```bash php artisan vendor:publish --tag=filament-relation-navigator-views ``` A preset view receives: | Variable | Content | | -------------------- | ----------------------------------------------------------------------- | | `$label` | The last breadcrumb | | `$items` | The menu items: `key`, `label`, `url`, `icon`, `badge`, `badgeColor`, `isActive` | | `$heading` | "Switch page", translated | | `$isSearchable` | Whether to show the search field | | `$hasSeparator` | Whether to split record pages and relation pages in two blocks | | `$shortcut` | The shortcut, or null | | `$shortcutKeys` | The shortcut keys to show: `['mac' => [...], 'other' => [...]]` | | `$searchPlaceholder` | "Find a page…", translated | | `$emptyLabel` | "No pages found.", translated | | `$maxHeight` | `menu.max_height` | To give your button the tooltip and the shortcut, include `filament-relation-navigator::menu.partials.trigger-attributes` inside its tag. Each item also has `isRelationPage()`. To reuse the search field, the list (with the separator and the keyboard navigation) and the "no results" line, include `filament-relation-navigator::menu.partials.list` with `showCheck`. --- --- url: /filament-relation-navigator/guide/native-record-sub-navigation.md --- # Native record sub-navigation The same items can feed Filament's record sub-navigation: ```php public static function getRecordSubNavigation(Page $page): array { return RelationNavigator::getRecordSubNavigation($page); } ``` --- --- url: /filament-relation-navigator/guide/open-as-page.md --- # Open as page On the view and edit pages, every relation manager that has its own page gets an **Open as page** action in the header of its table, next to its title and before its own actions. It opens the relation manager's own page, or the page of its relation group when it has no page of its own. On a group's page the managers with a page of their own get the action too; on its own page a manager never links to itself. Turn it off where you need to: ```php // config/filament-relation-navigator.php: everywhere 'relation_manager_link' => false, ``` ```php // On a resource: all its relation managers public static function hasRelationPageLinks(): bool { return false; } ``` ```php // On a relation manager (with InteractsWithRelationPage) protected static bool $hasRelationPageLink = false; // or, without the trait public static function hasRelationPageLink(): bool { return false; } ``` ### Its look A link with an arrow by default. Change it in the config: ```php 'relation_manager_action' => [ 'style' => 'button', // link, button or icon_button (the label becomes a tooltip) 'label' => 'Full page', // text or translation key; null: "Open as page", translated 'icon' => 'heroicon-m-arrow-top-right-on-square', // any Filament icon, or null 'icon_position' => 'after', // or before 'color' => 'gray', 'size' => null, // sm, md, lg... 'new_tab' => false, ], ``` Or change the Filament action itself, for everything else but its URL and when it shows, which the package sets. Every level gets the action as the previous one left it: ```php // A service provider: every relation manager RelationNavigator::configureRelationPageActionUsing( fn (Action $action, RelationManager $relationManager) => $action->outlined()->badge('new'), ); ``` ```php // A resource, or a relation manager: only there public static function configureRelationPageAction(Action $action): Action { return $action->iconButton()->tooltip('Open the orders on their own page'); } ``` `RelationNavigator::getRelationManagerPageUrl($relationManager)` returns the same URL, for a button of your own. --- --- url: /filament-relation-navigator/guide/previous-and-next-record.md --- # Previous and next record Two buttons before the header actions open the previous or the next record **on the same page**: from a customer's invoices to the next customer's invoices. A record that cannot open that page opens on its first page in the menu. They are off by default, since they add a few queries per render: ```php 'record_navigation' => true, ``` They follow **the list the user came from**: its sort, filters, search and tab, as on screen (up to 100 records; about 30 with UUID keys). From the first or the last record of that list there is nothing further, rather than a jump to another order. A record that is not in the list (opened from a link) walks by key. To always walk by key: ```php 'record_navigation_follows_list' => false, ``` The list remembers its records only when record navigation is on in the config or on the resource (`hasRelationNavigatorRecordNavigation()`), since the list page cannot ask a record page. They walk through the resource's own query (`getRecordRouteBindingEloquentQuery()`), so tenancy and your scopes apply, and skip the records the user cannot view. Per page: ```php public function hasRelationNavigatorRecordNavigation(): bool { return true; } public function getRelationNavigatorRecordNavigationQuery(): ?Builder { return Customer::query()->where('active', true); } ``` On a **nested resource** they stay within the parent: from one of a customer's orders to the next order of the same customer. The list there is the parent's relation manager: they follow its order when the nested resource is its related resource (`protected static ?string $relatedResource`), except with the `cookie` session driver, which keeps the parent's list only. --- --- url: /filament-relation-navigator/guide/quick-start.md --- # Quick start **1. Give the relations a page.** Add the trait to the resource: ```php use Wit3\FilamentRelationNavigator\Concerns\HasRelationPages; class CustomerResource extends Resource { use HasRelationPages; public static function getRelations(): array { return [ 'orders' => OrdersRelationManager::class, 'invoices' => InvoicesRelationManager::class, NotesRelationManager::class, ]; } } ``` Every relation now has its page: `/customers/1/orders`, `/customers/1/invoices`, `/customers/1/notes`. **2. Add the menu to the view page:** ```php use Wit3\FilamentRelationNavigator\Concerns\HasRelationNavigator; class ViewCustomer extends ViewRecord { use HasRelationNavigator; } ``` That's all. The relation pages have the menu already, and the tabs on the view page keep working as before. --- --- url: /filament-relation-navigator/guide/recipes.md --- # Recipes Short answers to common setups. Each one uses only the public API. ## A page for some relations only Leave the resource alone and opt in on the relation managers you want: ```php use Wit3\FilamentRelationNavigator\Concerns\InteractsWithRelationPage; class OrdersRelationManager extends RelationManager { use InteractsWithRelationPage; } ``` ## Pages instead of tabs Keep the relations on their own pages and drop the tabs from the view page. Old links to tabs (`?relation=orders`) land on the pages: ```php // ViewCustomer public function getRelationManagers(): array { return []; } ``` ```php // config/filament-relation-navigator.php 'redirect_relation_tabs' => true, ``` The menu, "Open as page" and global search keep listing the relation pages: they read the resource's `getRelations()`. ## The record's details above every relation Reuse the resource's infolist, or a piece of it: ```php // CustomerResource public static function relationPageHeader(Schema $schema): Schema { return static::infolist($schema); } ``` ## A resource without a view page Relation pages work with a list page only. Link them from the table: ```php Action::make('orders') ->url(fn (Customer $record): string => CustomerResource::getUrl('relations.orders', ['record' => $record])) ``` They need the record's `view` policy, since there is no view page to stand for. ## A view page under another key `'details' => ViewCustomer::route('/{record}')` is found by its class. With a relation page class of your own, you can also name it: `protected static ?string $contextPage = 'details';`. ## Link to a relation page from anywhere ```php CustomerResource::getUrl('relations.orders', ['record' => $customer]); ``` Inside a tenant, a cluster or a nested resource, Filament fills the missing parameters from the current request, as for any resource URL. ## A quiet menu The menu of 1.2: the breadcrumb opens a plain list, no search, no badges, no shortcut. ```php 'menu' => [ 'preset' => 'simple', 'searchable' => false, 'badges' => false, 'shortcut' => null, ], ``` ## Only for staff Hide a relation page per record, or for some users, on the resource: ```php public static function canAccessRelationPage(Model $record, string $slug): bool { return $slug !== 'audit-logs' || auth()->user()->isStaff(); } ``` ## Several panels or tenants Nothing to do: the routes are registered for every panel that has the resource, inside its tenant and cluster, and previous/next remember one list per panel, tenant and resource. --- --- url: /filament-relation-navigator/guide/relation-pages.md --- # Relation pages ### Opting in Opt in on the resource, for every relation manager, or only on the relation managers you want: ```php use Wit3\FilamentRelationNavigator\Concerns\InteractsWithRelationPage; class OrdersRelationManager extends RelationManager { use InteractsWithRelationPage; } ``` | Setup | Relations with a page | | ------------------------------------------- | ----------------------------------- | | `HasRelationPages` on the resource | all, minus the ones that opt out | | `InteractsWithRelationPage` on a manager | only the managers that opt in | | A page class you wrote (see below) | all, minus the ones that opt out | To leave some relations out: ```php // On the resource public static function hasRelationPage(string $slug): bool { return $slug !== 'notes'; } // On a relation manager, with InteractsWithRelationPage protected static bool $hasRelationPage = false; ``` A relation manager shared by two resources opts in for both: use the resource's `hasRelationPage()` to leave one of them out. ### URLs and slugs | `getRelations()` entry | URL | | ----------------------------------------------- | --------------------------- | | `'orders' => OrdersRelationManager::class` | `/customers/1/orders` | | `SupportTicketsRelationManager::class` (no key) | `/customers/1/support-tickets` | | `RelationGroup::make('Activity', [...])` | `/customers/1/activity` | A relation manager's own slug wins (`protected static ?string $relationPageSlug = 'tickets';`), then the key in `getRelations()`, then the kebab-cased relationship name (or the group label: give groups a key, since a translated label changes with the language). Slugs equal to one of the resource's page keys (`edit`, `view`...) are skipped, and so is a second relation with a slug already taken. Each page is a named route, `relations.{slug}`: ```php CustomerResource::getUrl('relations.orders', ['record' => $customer]); ``` ### Authorization and behaviour The relation manager receives the resource's **view** page as `$pageClass` (the edit page when there is no view page), so `isReadOnly()`, `canViewForRecord()`, `getBadge()` and every other check behave exactly as in the tab. The view page is found by its key (`view`, `edit`, or `$contextPage` on a page class you wrote) or by its class. A relation page needs what the view page needs (its `canAccess()` and the record's `view` policy; `update` when it stands for the edit page) and the manager's `canViewForRecord()`. Without a view or an edit page, the `view` policy applies. A policy that denies as not found gives a 404, an unknown slug too. The menu, global search and "Open as page" only link the pages the user can open. Relation pages do not run the view page's own code: checks in its `authorizeAccess()` or a `getRelationManagers()` filtered per user do not apply there. Put them in policies, in `canViewForRecord()`, or veto a relation page per record on the resource: ```php public static function canAccessRelationPage(Model $record, string $slug): bool { return $slug !== 'audit-logs' || auth()->user()->isAdmin(); } ``` --- --- url: /filament-relation-navigator/guide/the-breadcrumb-menu.md --- # The breadcrumb menu `HasRelationNavigator` needs a page with a record: `ViewRecord`, `EditRecord` and pages using `InteractsWithRecord` already have the two methods it declares, `getRecord()` and `hasRecord()`. On a page without a record PHP says so as soon as the class is loaded. A record page is in the menu if, and only if, it uses `HasRelationNavigator`: the view page, the edit page or any custom page of the record. On those pages the last breadcrumb opens the menu. The relation pages are always listed, after the record pages, with the relation managers' icons and badges, and only when the user can see them. If the page already builds its own breadcrumbs, pass them through `withRelationNavigator()`: ```php /** * @return array */ public function getBreadcrumbs(): array { return $this->withRelationNavigator([ CustomerResource::getUrl('index') => 'Customers', $this->getBreadcrumb(), ]); } ``` A custom page that uses `InteractsWithRecord` itself, instead of extending `ViewRecord` or `EditRecord`, has two `getBreadcrumbs()` methods. Unless it defines its own, tell PHP which one wins: ```php class CustomerActivity extends Page { use HasRelationNavigator, InteractsWithRecord { HasRelationNavigator::getBreadcrumbs insteadof InteractsWithRecord; InteractsWithRecord::getBreadcrumbs as getRecordBreadcrumbs; } } ``` The menu uses the page's `$navigationLabel` and `$navigationIcon`, and shows it only when `canAccess()` allows it for the record. --- --- url: /filament-relation-navigator/guide/troubleshooting.md --- # Troubleshooting ## The menu does not show * The page must use `HasRelationNavigator`. Relation pages always have it. * The menu needs at least two items: the page itself and one more. * A page that builds its own breadcrumbs must return `$this->withRelationNavigator([...])`. * Below 40rem Filament hides the breadcrumbs: the menu moves above the heading (`menu.mobile`). ## The menu looks wrong or the caret is misplaced Publish the plugin's stylesheet again, after every update: ```bash php artisan filament:assets ``` ## A relation page is a 404 * The relation manager has no page: the resource needs `HasRelationPages`, or the relation manager `InteractsWithRelationPage`, and it must not opt out. * Its slug equals a page key of the resource (`edit`, `view`...): such slugs are skipped. Pick another with `$relationPageSlug`. * With cached routes, cache them again after a deploy: `php artisan route:cache`. * The policy denies the record "as not found" (`Response::denyAsNotFound()`): that is a 404 on purpose. ## A relation page is a 403 A relation page needs the view page's `canAccess()`, the record's `view` policy (`update` for an edit page), the relation manager's `canViewForRecord()` and, if you defined it, the resource's `canAccessRelationPage()`. Check them in that order. ## The badges do not show * `menu.badges` is `false`, the page or resource turns them off, or the relation manager does (`hasRelationNavigatorBadge()`). * By default they load when the menu opens, with a spinner. If the spinner never stops, look at the browser console for a failed Livewire request. * Views published before 1.3 cannot load badges later: they get them with the page instead. ## The shortcut does nothing * It does nothing while you type in a field. * A shortcut of the panel's global search (`globalSearchKeyBindings()`) is never taken: choose another with `menu.shortcut`. * A browser extension or the operating system may use the same keys. ## "Open as page" is missing * `relation_manager_link` is `false`, or the resource or relation manager turns it off. * The relation manager has no page of its own, or you are already on it. * A table with a custom `->header()` view has no place for header actions. ## Previous and next are missing * They are off by default: `record_navigation`. * They hide when there is no other record (on a nested resource, no other record of the same parent). * To follow the list's order, the list must have been opened in this session, with record navigation on in the config or on the resource. ## "A directory that only this user can write" The storage is read-only, so the generated page classes go to the system temporary directory, and that directory belongs to someone else. Make `storage/framework/cache` writable, remove the directory named in the message, or choose one in a service provider: ```php GeneratedRelationPages::useCachePath(storage_path('app/relation-pages')); ``` ## Still stuck Ask in [GitHub Discussions](https://github.com/wit3/filament-relation-navigator/discussions), or open an [issue](https://github.com/wit3/filament-relation-navigator/issues) with your Filament version and a few lines that reproduce it. --- --- url: /filament-relation-navigator/reference/upgrade.md --- # Upgrade guide The package follows [semantic versioning](https://semver.org): minor and patch releases never break your code. This page lists what you may want to look at when you update. The [changelog](/reference/changelog) has every change. ```bash composer update wit3/filament-relation-navigator php artisan filament:assets ``` ## To 1.7 Nothing to change. When record navigation is on, **nested resources show previous and next** too, within the same parent record, in the order of the parent's relation manager when the nested resource is its related resource (`$relatedResource`). To hide them on a nested resource, return `false` from `hasRelationNavigatorRecordNavigation()` on its pages or on the resource. ## To 1.6 Nothing to change. * From 1.6.1, package plumbing is marked `@internal` (see the changelog): if you call `RelationNavigator::optsIn()`, `registerRoutes()` or similar helpers, move to what the [API reference](/reference/api) lists. * Filament 4.13 is the lowest version allowed from 1.6.1. * **Menu badges are loaded when the menu opens**, not with the page. For the old behaviour: `'badges' => true`. Menu views published before 1.3, and presets of your own, keep getting them with the page. * The "Open as page" action has new options (`relation_manager_action`) and hooks: see [Open as page](/guide/open-as-page). ## To 1.5 Nothing to change. Two behaviours are different: * **Previous and next follow the list you came from** (sort, filters, search, tab) instead of the key order, when record navigation is on. To keep the key order: `'record_navigation_follows_list' => false`. * **"Open as page"** opens a relation manager's own page before the page of a relation group it also belongs to. If you published the package views, publish `menu/partials/list.blade.php` again: relation managers with a lazy tab badge now load it in the menu too. ## To 1.4 Nothing to change. * The **"Open as page"** link is now an action in the header of the relation manager's table instead of a link above it. If you want it off somewhere, see [Open as page](/guide/open-as-page): config, resource or relation manager. * `RelationNavigator::renderRelationManagerLink()` is deprecated: the package no longer uses it. It still works for a render hook of your own, and will be removed in 2.0. * Every menu option can now be set on a resource too: see [Page, resource or config](/guide/menu-presets#page-resource-or-config). ## To 1.3 ::: danger Security fix Versions 1.0.0 to 1.2.1 did not apply the record's `view` policy on relation pages ([GHSA-v3mh-w7qp-37gc](https://github.com/wit3/filament-relation-navigator/security/advisories/GHSA-v3mh-w7qp-37gc)). If you use policies on your records, update. ::: * **The default menu is now the `github` preset with the search field.** If you published the config, you keep what you set. To keep the menu of 1.2: ```php // config/filament-relation-navigator.php 'menu' => [ 'preset' => 'simple', 'searchable' => false, ], ``` * The menu no longer lists the edit page to users who cannot edit the record. * New options, all with defaults in the code: a config published from 1.2 keeps working. Add them to your config when you want to change them: `relation_manager_link`, `record_navigation`, `redirect_relation_tabs`, and `'lazy'` for `menu.badges`. * If you published the package views and want `'badges' => 'lazy'`, publish `menu/partials/list.blade.php` again. ## To 1.2 * `HasRelationNavigator` now declares `getRecord()` and `hasRecord()`: a page without a record fails as soon as its class is loaded, instead of later. View, edit and pages using `InteractsWithRecord` already have them.