You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A custom WordPress nav walker class to fully implement the Bootstrap 3.0+ navigation style in a custom theme using the WordPress built in menu manager. A working version of the walker for Bootstrap 4.0.0 can be found in the [`v4` branch](https://github.com/wp-bootstrap/wp-bootstrap-navwalker/tree/v4)
11
+
A custom WordPress Nav Walker Class to fully implement the Bootstrap 4 navigation style in a custom theme using the WordPress built in menu manager.
12
12
13
13
## NOTES
14
14
15
-
This is a utility class that is intended to format your WordPress theme menu with the correct syntax and classes to utilize the Bootstrap dropdown navigation. It does not include the required Bootstrap JS and CSS files. You will have to include those dependancies separately.
15
+
This is a utility class that is intended to format your WordPress theme menu with the correct syntax and CSS classes to utilize the Bootstrap dropdown navigation. It does not include the required Bootstrap JS and CSS files - you will have to include them manually.
16
16
17
-
### Bootstrap 4
17
+
### UPGRADE NOTES ###
18
18
19
-
Bootstrap 4.0.0 released January 2018 and is the default branch offered at the GitHub repo and on [GetBootstrap](https://getbootstrap.com).
19
+
Between version 3 and version 4 of the walker there have been significant changes to the codebase. Version 4 of the walker is built to work with Bootstrap 4 and has not been tested for backwards compatibility with Bootstrap 3. A separate branch for Bootstrap 3 is maintained here: https://github.com/wp-bootstrap/wp-bootstrap-navwalker/tree/v3-branch
20
+
21
+
Here is a list of the most notable changes:
22
+
23
+
- The filename has been changed and prefixed with `class-` to better fit PHP coding standards naming conventions.
24
+
- New Name: `class-wp-bootstrap-navwalker.php`
25
+
- Old Name: `wp-bootstrap-navwalker.php`
26
+
- Icon and link modifier handling is now done through the `CSS Classes` menu item input instead of the `Title` input.
27
+
- Icon only items are possible using icon classes in combination with the `sr-only` classname.
20
28
21
29
## Installation
22
30
23
-
Place **wp-bootstrap-navwalker.php** in your WordPress theme folder `/wp-content/your-theme/`
31
+
Place **class-wp-bootstrap-navwalker.php** in your WordPress theme folder `/wp-content/your-theme/`
24
32
25
-
Open your WordPress themes **functions.php** file `/wp-content/your-theme/functions.php` and add the following code:
33
+
Open your WordPress themes **functions.php** file -`/wp-content/your-theme/functions.php` - and add the following code:
If you encounter errors with the above code use a check like this to return clean errors to help diagnose the problem.
34
42
35
43
```php
36
44
<?php
37
-
if ( ! file_exists( get_template_directory() . '/wp-bootstrap-navwalker.php' ) ) {
45
+
if ( ! file_exists( get_template_directory() . '/class-wp-bootstrap-navwalker.php' ) ) {
38
46
// file does not exist... return an error.
39
-
return new WP_Error( 'wp-bootstrap-navwalker-missing', __( 'It appears the wp-bootstrap-navwalker.php file may be missing.', 'wp-bootstrap-navwalker' ) );
47
+
return new WP_Error( 'class-wp-bootstrap-navwalker-missing', __( 'It appears the class-wp-bootstrap-navwalker.php file may be missing.', 'wp-bootstrap-navwalker' ) );
You will also need to declare a new menu in your `functions.php` file if one doesn't already exist.
45
54
55
+
```php
56
+
register_nav_menus( array(
57
+
'primary' => __( 'Primary Menu', 'THEMENAME' ),
58
+
) );
59
+
```
46
60
## Usage
47
61
48
-
Update your `wp_nav_menu()`function in `header.php` to use the new walker by adding a "walker" item to the wp_nav_menu array.
62
+
Add or update any `wp_nav_menu()`functions in your theme (often found in `header.php`) to use the new walker by adding a `'walker'` item to the wp_nav_menu args array.
Your menu will now be formatted with the correct syntax and classes to implement Bootstrap dropdown navigation.
65
80
66
-
You will also want to declare your new menu in your `functions.php` file if one is not already defined.
81
+
Typically the menu is wrapped with additional markup, here is an example of a ` fixed-top` menu that collapse for responsive navigation at the md breakpoint.
67
82
68
83
```php
69
-
<?php
70
-
register_nav_menus( array(
71
-
'primary' => __( 'Primary Menu', 'THEMENAME' ),
72
-
) );
73
-
```
74
-
75
-
Typically the menu is wrapped with additional markup, here is an example of a ` navbar-fixed-top` menu that collapse for responsive navigation.
Simply updating the walker may not be enough to get menus working right, you may need to add wrappers or additional classes, you can do that via the above function as well.
131
130
132
-
### Extras
131
+
### Menu Caching
132
+
133
+
On some sites generating a large menu that rarely ever changes on every page request is an overhead that you may want to avoid. In those cases I can suggest you look at storing menu results in a transient.
134
+
135
+
The biggest drawback to caching nav menus with this method is that it cannot easily apply the `.current-menu-item` or the `.active` class to the currently active item as WP decides what is currently active on page load - and since the menu is cached it only knows the active page that it was cached on originally.
133
136
134
-
This script included the ability to add Bootstrap dividers, dropdown headers, glyphicons and disabled links to your menus through the WordPress menu UI.
137
+
You can decide yourself if you want to put up with those drawbacks for the benefit of removing the menu generation time on most page loads. You can follow this article by Dave Clements to see how we cached nav menus that were generated by this walker: https://www.doitwithwp.com/use-transients-speed-wordpress-menus/
135
138
136
-
#### Dividers
139
+
Be sure to set the `echo` argument to FALSE in `the wp_nav_menu()` call when doing this so that the results can be stored instead of echoed to the page.
137
140
138
-
Simply add a Link menu item with a **URL** of `#` and a **Link Text** or **Title Attribute** of `divider` (case-insensitive so ‘divider’ or ‘Divider’ will both work ) and the class will do the rest.
This script included the ability to use Bootstrap nav link mods in your menus through the WordPress menu UI. Disabled links, dropdown headers and dropdown dividers are supported. Additionally icon support is built-in for Glyphicons and Font Awesome (note: you will need to include the icon stylesheets or assets separately).
148
+
149
+
#### Icons
141
150
142
-
To add an Icon to your link simple place the Glyphicon class name in the links **Title Attribute** field and the class will do the rest. IE `glyphicon-bullhorn`
151
+
To add an Icon to your link simply enter Glypicons or Font Awesome class names in the links **CSS Classes** field in the Menu UI and the walker class will do the rest. IE `glyphicons glyphicons-bullhorn` or `fa fa-arrow-left` or `fas fa-arrow-left`.
143
152
144
-
#### Dropdown Headers
153
+
#### Icon-Only Items
145
154
146
-
Adding a dropdown header is very similar, add a new link with a **URL** of `#` and a **Title Attribute** of `dropdown-header` (it matches the Bootstrap CSS class so it's easy to remember). set the **Navigation Label** to your header text and the class will do the rest.
155
+
To make an item appear with the icon only apply the bootstrap screen reader class `sr-only` to the item alongside any icon classnames. This will then hide only the text that would appear as the link text.
147
156
148
157
#### Disabled Links
149
158
150
-
To set a disabled link simply set the **Title Attribute** to `disabled` and the class will do the rest.
159
+
To set a disabled link simply add `disabled` to the **CSS Classes** field in the Menu UI and the walker class will do the rest. _Note: In addition to adding the .disabled class this will change the link `href` to `#` as well so that it is not a followable link._
160
+
161
+
#### Dropdown Headers & Dropdown Dividers
162
+
163
+
Headers and dividers can be added within dropdowns by adding a Custom Link and adding either `dropdown-header` or `dropdown-divider` into the **CSS Classes** input. _Note: This will remove the `href` on the item and change it to either a `<span>` for headers or a `<div>` for dividers._
0 commit comments