Skip to content

Commit

Permalink
Merge pull request #339 from wp-bootstrap/v4
Browse files Browse the repository at this point in the history 
Make v4 branch the new master
  • Loading branch information
@pattonwebz
pattonwebz authored Feb 10, 2018
2 parents 88959a7 + 1773f72 commit 8ddb536
Show file tree
Hide file tree
Showing 8 changed files with 872 additions and 298 deletions.
22 changes: 22 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,27 @@
#CHANGELOG

## [4.0.0]
- Added a prefix on @since tags to highlight when they refer to WP core instead of this class.
- Rework of `start_lvl()` and `start_el()` based on latest `Walker_Nav_Menu` Class from WP core.
- Whitespace preservation method improvements.
- Added `nav_menu_item_args` filter and `nav_menu_item_title` brought in at WP 4.4.0
- Use `the_title` filter prior to `nav_menu_item_title`.
- Added a labelled-by attribute to dropdowns for accessibility.
- Links inside dropdown have `.dropdown-item` instead of `.nav-link`.
- Remove `<span class="carat">` after parent dropdown items.
- Support `echo` arg in fallback menu. props: @toddlevy
- Add `.active` to parent when a child is current page. props: @zyberspace
- Fix to correct output of dropdown atts and styles when depth passed to wp_nav_menu is <= 1. props: @chrisgeary92
- Move icon output to a local var instead of modifying and clearing a global object.
- Reassign filtered classes back to $classes array so that updated classes can be accessed later if needed. props: @lf-jeremy
- Update to work with Bootstrap v4.
- Added `.nav-item` and `.nav-link` to `<li>` and `<a>` respectively.
- Dropped support for using title attribute to add link modifiers and icons.
- Added support for link modifiers and icons through WP Menu Builder 'classes' input.
- Icon support is for Font Awesome 4/5 and Glyphicons icons.
- Added unit tests for the `fallback` method.
- Added code to handle icon-only menus.

## [3.0.0]

- Fix untranslated string in fallback.
Expand Down
121 changes: 67 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,87 +8,86 @@
[![Code Coverage](https://scrutinizer-ci.com/g/wp-bootstrap/wp-bootstrap-navwalker/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/wp-bootstrap/wp-bootstrap-navwalker/?branch=master)
[![Build Status](https://scrutinizer-ci.com/g/wp-bootstrap/wp-bootstrap-navwalker/badges/build.png?b=master)](https://scrutinizer-ci.com/g/wp-bootstrap/wp-bootstrap-navwalker/build-status/master)

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)
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.

## NOTES

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.
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.

### Bootstrap 4
### UPGRADE NOTES ###

Bootstrap 4.0.0 released January 2018 and is the default branch offered at the GitHub repo and on [GetBootstrap](https://getbootstrap.com).
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

Here is a list of the most notable changes:

- The filename has been changed and prefixed with `class-` to better fit PHP coding standards naming conventions.
- New Name: `class-wp-bootstrap-navwalker.php`
- Old Name: `wp-bootstrap-navwalker.php`
- Icon and link modifier handling is now done through the `CSS Classes` menu item input instead of the `Title` input.
- Icon only items are possible using icon classes in combination with the `sr-only` classname.

## Installation

Place **wp-bootstrap-navwalker.php** in your WordPress theme folder `/wp-content/your-theme/`
Place **class-wp-bootstrap-navwalker.php** in your WordPress theme folder `/wp-content/your-theme/`

Open your WordPress themes **functions.php** file `/wp-content/your-theme/functions.php` and add the following code:
Open your WordPress themes **functions.php** file - `/wp-content/your-theme/functions.php` - and add the following code:

```php
<?php
// Register Custom Navigation Walker
require_once get_template_directory() . '/wp-bootstrap-navwalker.php';
require_once get_template_directory() . '/class-wp-bootstrap-navwalker.php';
```

If you encounter errors with the above code use a check like this to return clean errors to help diagnose the problem.

```php
<?php
if ( ! file_exists( get_template_directory() . '/wp-bootstrap-navwalker.php' ) ) {
if ( ! file_exists( get_template_directory() . '/class-wp-bootstrap-navwalker.php' ) ) {
// file does not exist... return an error.
return new WP_Error( 'wp-bootstrap-navwalker-missing', __( 'It appears the wp-bootstrap-navwalker.php file may be missing.', 'wp-bootstrap-navwalker' ) );
return new WP_Error( 'class-wp-bootstrap-navwalker-missing', __( 'It appears the class-wp-bootstrap-navwalker.php file may be missing.', 'wp-bootstrap-navwalker' ) );
} else {
// file exists... require it.
require_once get_template_directory() . '/wp-bootstrap-navwalker.php';
require_once get_template_directory . '/class-wp-bootstrap-navwalker.php';
}
```
You will also need to declare a new menu in your `functions.php` file if one doesn't already exist.

```php
register_nav_menus( array(
'primary' => __( 'Primary Menu', 'THEMENAME' ),
) );
```
## Usage

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.
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.

```php
<?php
wp_nav_menu( array(
'theme_location' => 'primary',
'depth' => 2,
'container' => 'div',
'container_class' => 'collapse navbar-collapse',
'container_id' => 'bs-example-navbar-collapse-1',
'menu_class' => 'nav navbar-nav',
'fallback_cb' => 'WP_Bootstrap_Navwalker::fallback',
'walker' => new WP_Bootstrap_Navwalker(),
'theme_location' => 'primary',
'depth' => 1, // 1 = with dropdowns, 0 = no dropdowns.
'container' => 'div',
'container_class' => 'collapse navbar-collapse',
'container_id' => 'bs-example-navbar-collapse-1',
'menu_class' => 'navbar-nav mr-auto',
'fallback_cb' => 'WP_Bootstrap_Navwalker::fallback',
'walker' => new WP_Bootstrap_Navwalker()
) );
?>
```

Your menu will now be formatted with the correct syntax and classes to implement Bootstrap dropdown navigation.

You will also want to declare your new menu in your `functions.php` file if one is not already defined.
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.

```php
<?php
register_nav_menus( array(
'primary' => __( 'Primary Menu', 'THEMENAME' ),
) );
```

Typically the menu is wrapped with additional markup, here is an example of a ` navbar-fixed-top` menu that collapse for responsive navigation.

```php
<nav class="navbar navbar-default" role="navigation">
<div class="container-fluid">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="<?php echo home_url(); ?>">
<?php bloginfo('name'); ?>
</a>
</div>
<nav class="navbar navbar-expand-md navbar-light bg-light" role="navigation">
<div class="container">
<!-- Brand and toggle get grouped for better mobile display -->
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-controls="bs-example-navbar-collapse-1" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<a class="navbar-brand" href="#">Navbar</a>
<?php
wp_nav_menu( array(
'theme_location' => 'primary',
Expand All @@ -98,8 +97,8 @@ Typically the menu is wrapped with additional markup, here is an example of a `
'container_id' => 'bs-example-navbar-collapse-1',
'menu_class' => 'nav navbar-nav',
'fallback_cb' => 'WP_Bootstrap_Navwalker::fallback',
'walker' => new WP_Bootstrap_Navwalker())
);
'walker' => new WP_Bootstrap_Navwalker()
) );
?>
</div>
</nav>
Expand Down Expand Up @@ -129,25 +128,39 @@ add_filter( 'wp_nav_menu_args', 'prefix_modify_nav_menu_args' );
```
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.

### Extras
### Menu Caching

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.

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.

This script included the ability to add Bootstrap dividers, dropdown headers, glyphicons and disabled links to your menus through the WordPress menu UI.
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/

#### Dividers
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.

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.
See also:
- https://generatewp.com/how-to-use-transients-to-speed-up-wordpress-menus/
- https://vip-svn.wordpress.com/plugins/cache-nav-menu/cache-nav-menu.php

#### Glyphicons
### Extras

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).

#### Icons

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`
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`.

#### Dropdown Headers
#### Icon-Only Items

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.
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.

#### Disabled Links

To set a disabled link simply set the **Title Attribute** to `disabled` and the class will do the rest.
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._

#### Dropdown Headers & Dropdown Dividers

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._

## Changelog

Expand Down
Loading

0 comments on commit 8ddb536

Please sign in to comment.