Navigation
Package docs status
Section titled “Package docs status”This page is generated from public package documentation in capell-4/packages and the package manifest checked into the source repository.
| Field | Value |
|---|---|
| Composer package | capell-app/navigation |
| Package slug | navigation |
| Product group | Capell Foundation |
| Tier | free |
| Bundle | foundation |
| Runtime contexts | admin, frontend, console |
| Capell version | ^4.0 |
| Source repository | capell-app/packages |
| Source path | packages/navigation |
| Docs source | packages/navigation/docs |
| Manifest | capell.json |
Navigation owns editor-managed menus and renders structured navigation data for Capell frontend themes.
At A Glance
Section titled “At A Glance”- Package:
capell-app/navigation - Namespace:
Capell\Navigation\ - Surfaces: Filament admin, console, database
- Service providers:
packages/navigation/src/Providers/NavigationServiceProvider.php - Capell dependencies:
capell-app/admin,capell-app/frontend
Why It Helps Your Capell Workflow
Section titled “Why It Helps Your Capell Workflow”- Adds site and language scoped navigation trees so editors can manage menus without editing theme code.
- Keeps page navigation fields, sync actions, and frontend loaders together for predictable theme rendering.
- Helps developers connect themes to editor-managed menus through package-owned loaders instead of direct page queries in Blade.
Best Used With
Section titled “Best Used With”What It Adds
Section titled “What It Adds”Navigation adds site and language scoped navigation trees, page navigation fields, sync actions, and frontend loading support.
- Navigation Filament resource.
- Navigation relation manager on sites.
- Page schema extender for navigation placement.
- Navigation item model resolution.
- Actions to add, remove, replicate, and resolve navigation entries.
- Navigation loader support for frontend rendering.
Why It Matters
Section titled “Why It Matters”For developers: Stores navigation items in structured data and uses adapters/registries to connect navigable models without hard-coding page logic everywhere.
For teams: Lets editors manage menus for each site and language while keeping page selection tied to Capell records.
Built With
Section titled “Built With”This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.
Capell packages used here
Open-source packages used here
- No extra third-party Composer package beyond the Capell package stack is required here.
Screens And Workflow
Section titled “Screens And Workflow”Screenshots are generated from docs/screenshots.json during package deployment.
- Navigation admin index.
- Create/edit navigation form.
- Site relation manager for navigations.
- Page form navigation tab.
- Frontend menu output.
Technical Shape
Section titled “Technical Shape”- NavigationServiceProvider registers the package.
- Migration creates navigations.
- Model: Navigation.
- Filament resource: NavigationResource.
- Policy: NavigationPolicy.
- Events/listeners handle creation and site replication.
Code Map
Section titled “Code Map”| Area | Path | Purpose |
|---|---|---|
| Actions | packages/navigation/src/Actions | Domain operations. Test these directly where possible. |
| Data | packages/navigation/src/Data | Structured payloads, form state, view models, and integration data. |
| Enums | packages/navigation/src/Enums | Persisted states and Filament option values. |
| Models | packages/navigation/src/Models | Eloquent records owned by the package. |
| Filament | packages/navigation/src/Filament | Admin resources, pages, widgets, and settings UI. |
| Providers | packages/navigation/src/Providers | Registration, extension hooks, routes, migrations, and resources. |
| Resources | packages/navigation/resources | Views, translations, assets, and package resources. |
| Database | packages/navigation/database | Migrations, seeders, and settings migrations. |
| Tests | packages/navigation/tests | Package-level Pest coverage. |
Admin Surface
Section titled “Admin Surface”- Resources:
NavigationResource. - Pages:
CreateNavigation,EditNavigation,ListNavigations.
Commands
Section titled “Commands”capell:navigation-demo {--sites=} {--languages=}(packages/navigation/src/Console/Commands/DemoCommand.php)capell:navigation-setup {--sites=}(packages/navigation/src/Console/Commands/SetupCommand.php)
Data And Persistence
Section titled “Data And Persistence”-
navigations stores key, type, site, language, items JSON, meta, and visibility windows.
-
Navigation items may reference pages and page URLs through JSON.
-
Navigations connect to sites, languages, and types.
-
Cache key enum indicates navigation cache behaviour.
-
Models:
Navigation. -
Migrations:
2026_05_10_190860_01_create_navigations_table.php. -
Data objects live in
src/Data/; use them for payloads, form state, and view models.
Extension Points
Section titled “Extension Points”- Contracts:
NavigationNamesResolver,NavigationPageSyncer. - Events:
NavigationCreating. - Listeners:
ReplicateSiteNavigationsListener. - Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.
Install Impact
Section titled “Install Impact”- Adds navigations table.
- Adds navigation admin resource and site relation manager.
- Extends page and site admin schemas.
- No explicit public route is registered by this package.
- Adds setup and demo commands.
Install And Setup
Section titled “Install And Setup”- Install with
composer require capell-app/navigationin the host Capell application. - Run migrations through the host application package install flow.
- In this repository, verify package changes with
vendor/bin/pest; do not usephp artisan.
Admin And Access
Section titled “Admin And Access”-
NavigationResource (packages/navigation/src/Filament/Resources/Navigations/NavigationResource.php)
-
CreateNavigation (packages/navigation/src/Filament/Resources/Navigations/Pages/CreateNavigation.php)
-
EditNavigation (packages/navigation/src/Filament/Resources/Navigations/Pages/EditNavigation.php)
-
ListNavigations (packages/navigation/src/Filament/Resources/Navigations/Pages/ListNavigations.php)
-
Policy: NavigationPolicy (packages/navigation/src/Policies/NavigationPolicy.php)
Common Pitfalls
Section titled “Common Pitfalls”- Create language/site records before creating scoped navigation.
- Resolve stale page references after deleting pages.
- Clear navigation cache after manual data changes.
Testing
Section titled “Testing”Run package tests from the repository root:
vendor/bin/pest packages/navigation/tests --configuration=phpunit.xmlMaintenance Notes
Section titled “Maintenance Notes”- Put behaviour changes in
src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic. - Use package
Dataclasses at boundaries instead of passing anonymous arrays between layers. - Use backed enums for persisted values and enum labels for Filament options.