Menu System
Introduction
Botble CMS provides a powerful menu management system that allows you to create and organize navigation menus for your website. The menu system supports hierarchical structures, custom links, and integration with various content types.
Menu Architecture
The menu system consists of several key components:
- Menu: The main container for a set of menu items
- Menu Nodes: Individual menu items that can be organized hierarchically
- Menu Locations: Predefined areas in your theme where menus can be displayed
Default menu locations
platform/packages/menu/config/general.php
'locations' => [
'header-menu' => 'Header Navigation',
'main-menu' => 'Main Navigation',
'footer-menu' => 'Footer Navigation',
],
Render menu by location
{!!
Menu::renderMenuLocation('main-menu', [
'options' => [],
'theme' => true,
])
!!}
main-menu
is the menu location key
'options' is attributes of ul
tag. Ex: 'options' => ['id' => 'menu-header-main-menu', 'class' => 'menu']
Add new menu location
Menu::addMenuLocation('menu-location-key', 'Description here');
Remove a menu location
Menu::removeMenuLocation('menu-location-key');
Customize menu views
To customize view to display menu. You can create a file in /public/themes/your-theme/partials
.
Ex: /platform/themes/your-theme/partials/custom-menu.blade.php
<ul {!! $options !!}>
@foreach ($menu_nodes as $key => $row)
<li class="{{ $row->css_class }} @if ($row->url == Request::url()) current @endif">
<a href="{{ $row->url }}" target="{{ $row->target }}">
<i class='{{ trim($row->icon_font) }}'></i> <span>{{ $row->name }}</span>
</a>
@if ($row->has_child)
{!! Menu::generateMenu([
'slug' => $menu->slug,
'parent_id' => $row->id
]) !!}
@endif
</li>
@endforeach
</ul>
Default code to display menu is located in platform/core/menu/resources/views/partials/default.blade.php
And to show menu with custom view, using below code:
{!!
Menu::renderMenuLocation('main-menu', [
'options' => [],
'theme' => true,
'view' => 'custom-menu',
])
!!}
Menu in the location 'main-menu' will be generated using custom view in /platform/themes/your-theme/partials/custom-menu.blade.php
Advanced Features
Menu Caching
Botble CMS supports caching menus for improved performance. To enable menu caching:
- Go to Admin → Settings → Cache
- Enable the "Cache front menu" option
To manually clear the menu cache, you can use the following command:
php artisan cms:menu:clear-cache
Menu Item Icons
You can add icons to menu items in two ways:
- Icon Font: Use the "Icon" field to specify a CSS class for an icon (e.g.,
ti ti-home
for Tabler Icons) - Icon Image: Upload an image to use as an icon
To enable icon images for menu items, add this code to your theme's service provider:
Menu::useMenuItemIconImage();
Menu Item Badges
You can add badges to menu items (e.g., "New", "Hot", etc.). To enable this feature, add this code to your theme's service provider:
Menu::useMenuItemBadge();
This will add badge text and color fields to the menu item editor.
Menu API
Botble CMS provides a comprehensive API for working with menus programmatically:
Check if a Menu Exists
if (Menu::hasMenu('main-menu')) {
// Menu exists
}
Check if a Location Has a Menu
if (Menu::isLocationHasMenu('header-menu')) {
// Location has a menu assigned
}
Generate Menu Programmatically
$menuHtml = Menu::generateMenu([
'slug' => 'main-menu',
'theme' => true,
'view' => 'custom-menu',
]);
Register Menu Options for Content Types
To add your custom content type to the menu builder, use:
Menu::registerMenuOptions(YourModel::class, 'Your Model Name');
Best Practices
- Use Descriptive Names: Give your menus clear, descriptive names that indicate their purpose
- Organize Hierarchically: Use parent-child relationships to create dropdown menus
- Limit Menu Depth: Keep menu hierarchies to 2-3 levels for better usability
- Use Icons Sparingly: Icons can enhance usability but use them consistently
- Enable Caching: For production sites, enable menu caching for better performance
- Custom Views: Create custom menu views for different sections of your site
Menu Structure and Implementation
Database Structure
The menu system uses three main database tables:
menus: Stores the main menu containers
id
: Primary keyname
: The name of the menuslug
: A unique slug for the menustatus
: The menu status (published/draft)
menu_nodes: Stores individual menu items
id
: Primary keymenu_id
: Foreign key to the menus tableparent_id
: Parent menu node ID for hierarchical structurereference_id
: ID of the referenced content (if applicable)reference_type
: Type of the referenced content (e.g., Botble\Page\Models\Page)title
: The menu item titleurl
: The menu item URLicon_font
: CSS class for the iconcss_class
: Additional CSS classestarget
: Link target (_self, _blank, etc.)has_child
: Whether the item has childrenposition
: The item's position in the menu
menu_locations: Maps menus to theme locations
id
: Primary keymenu_id
: Foreign key to the menus tablelocation
: The theme location key
Menu Node Metadata
Menu nodes can have additional metadata stored in the meta_boxes
table, such as:
icon_image
: Path to an uploaded icon imagebadge_text
: Text for a badge displayed with the menu itembadge_color
: Color for the badge
Rendering Process
When a menu is rendered, the following process occurs:
- The system checks if the requested menu exists in the specified location
- If caching is enabled, it checks for a cached version of the menu
- If no cache exists, it retrieves the menu and its nodes from the database
- It builds the menu structure, organizing nodes hierarchically
- It applies any custom view or theme-specific formatting
- It returns the rendered HTML
Events
The menu system fires several events that you can listen for:
RenderingMenuOptions
: Fired when rendering menu options in the admin panelCreatedContentEvent
: Fired when a menu or menu location is created
Troubleshooting
Menu Not Displaying
If your menu is not displaying correctly, check the following:
- Ensure the menu is published in the admin panel
- Verify that the menu is assigned to the correct location
- Check that you're using the correct location key in your theme
- Clear the menu cache using
php artisan cms:menu:clear-cache
- Inspect the HTML output to see if the menu is being rendered but hidden by CSS
Menu Items Not Linking Correctly
If menu items are not linking to the correct pages:
- Check the URLs in the menu editor
- For content-referenced menu items, ensure the content exists and is published
- Verify that your custom menu view is correctly generating URLs