Bootstrap Hooks WP Registry grade D+. High-severity findings · 3 findingsWP RegistryHigh-severity findings · 3 findingsOpen the reportD+

A collection of filters and actions for bootstrap-based themes

When integrating Bootstrap with Wordpress, it is not sufficient to just include assets and add some css-classes to templates. You will also need to inject bootstrap-compatible markup into programmatically generated sections, such as menus, widgets, comments etc. Bootstrap Hooks aims to cover most of these cases to make us immediately start implementing the individual application rather than getting hassled by markup incompatibilities.

Bootstrap Hooks consists of six separate modules for Navigation, Pagination, Forms, Widgets, Comments, Gallery and Blocks which can be used altogether or independently from each other. Every module is customizable by passing options to a central filter method.

Bootstrap Hooks has been optimized for Bootstrap 5, though it can be adjusted to also support older versions. See Recipes for more details on how to do this.

Install

Install preferrably as a must-use plugin. It should be enabled by themes programmatically and updated by theme developers who maintain Bootstrap inside a certain themes.

Initialize

Bootstrap Hooks is made aware that your theme actually supports Bootstrap by calling add_theme_support in your functions.php:

add_theme_support( 'bootstrap' );

Usage

With few exceptions, Bootstrap Hooks works out-of-the-box by injecting its magic via actions and filters. Read further to learn more about the distinct modules.

Content

The Content-Hook takes care of your post content primarily. It sets proper markup and classes to images, captions, blockquotes and tables. It also handles the post thumbnail to add the responsive image class.

In Bootstrap 4, the Tag-component may break Wordpress` default taxonomy styles. See here for reference. To avoid undesired effects, the tag class is replaced with post-tag in body_class- or post_class-methods and also when it's found in the content.

This module also provides a custom method to handle the edit-post-link. Search your theme for occurrences of edit_post_link and replace with wp_bootstrap_edit_post_link:

// Edit post link
wp_bootstrap_edit_post_link(
  sprintf(
    /* translators: %s: Name of current post */
    __( 'Edit<span class="screen-reader-text"> "%s"</span>', 'textdomain' ),
    get_the_title()
  ),
  '<span class="edit-link">',
  '</span>'
) );

When using Bootstrap Hooks as a plugin, you should definitely check if the method has been loaded by wrapping function call into a conditional function_exists-check. See the Recipes section for an example.

Forms

This module handles search- and password-forms.

A search-form is rendered as input-group. You can customize the button's icon by passing arguments from a filter. This example shows how to integrate font-awesome:

// Show Font-Awesome search icon in Searchform
function my_bootstrap_options($options) {
  return array_merge($options, array(
    'search_submit_label' => '<i class="fa fa-search"></i>'
  ));
}
add_filter( 'bootstrap_options', 'my_bootstrap_options' );

Gallery

The gallery hook uses a grid of thumbnails in combination with a carousel inside a modal for zoom view.

In typical Bootstrap-driven layout, column sizes may differ from Wordpress default thumbnail size. You may update thumbnail size to your needs in order to fit thumbnail images into at least three columns:

// Adjust thumbnail size
update_option( 'thumbnail_size_w', 230 );
update_option( 'thumbnail_size_h', 230 );
update_option( 'thumbnail_crop', 1 );

The implementation does not handle different zoom-image heights. An easy way to fix this, is to register a custom image size with cropping enabled and apply to the gallery hook:

// Register custom gallery image size
add_image_size( 'gallery-zoom', 900, 500, true );

// Apply custom image size to gallery zoom
function my_bootstrap_options($options) {
  return array_merge($options, array(
    'gallery_zoom_size' => 'gallery-zoom'
  ));
}
add_filter( 'bootstrap_options', 'my_bootstrap_options' );

Menu

Bootstrap Hooks provides a custom MenuWalker based on the work by Edward McIntyre which is injected into menus per default. For the menus being in primary or top location, the navbar-nav-class will automatically be added.

Bootstrap Hooks also adds a script that handles links on dropdown-toggles which are prevented by default from Bootstrap.

Pagination

Since there's no existing hook for posts-pagination as well as for post-navigation, we need to call custom methods from our templates:

Search your theme for occurrences of the_posts_pagination and replace with wp_bootstrap_posts_pagination:

// Previous/next page navigation.
wp_bootstrap_posts_pagination( array(
  'prev_text'          => __( 'Previous page', 'textdomain' ),
  'next_text'          => __( 'Next page', 'textdomain' ),
  'before_page_number' => '<span class="meta-nav screen-reader-text">' . __( 'Page', 'textdomain' ) . ' </span>'
) );

Search your theme for occurrences of the_post_navigation and replace with wp_bootstrap_post_navigation:

// Previous/next post navigation.
wp_bootstrap_post_navigation( array(
  'next_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Next', 'textdomain' ) . '</span> ' .
    '<span class="screen-reader-text">' . __( 'Next post:', 'textdomain' ) . '</span> ' .
    '<span class="post-title">%title</span>',
  'prev_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Previous', 'textdomain' ) . '</span> ' .
    '<span class="screen-reader-text">' . __( 'Previous post:', 'textdomain' ) . '</span> ' .
    '<span class="post-title">%title</span>'
) );

Widgets

Widgets are rendered as cards. Some manipulations take care of content that's common to widgets, such as applying list-groups to unordered lists. Make sure that you registered any widget areas in your functions.php:

// Register widget area.
register_sidebar( array(
  'name'          => __( 'Widget Area', 'textdomain' ),
  'id'            => 'sidebar-1',
  'description'   => __( 'Add widgets here to appear in your sidebar.', 'textdomain' )
) );

Comments

Comments are rendered as nested media-objects.

You can customize the label 'Comment' by making use of the bootstrap_options-filter:

// Customize Comment Label
function my_bootstrap_options($args) {
  return array_merge($args, array(
    'comment_label' => ('Comment' , 'textdomain');
  ));
}
add_filter( 'bootstrap_options', 'my_bootstrap_options' );

Recipes

Use as Plugin

When intended to use as plugin or must-use plugin, you should also take care of the situation where the plugin is unistalled and check if any of the functions exist first:

// Previous/next page navigation.
call_user_func_array(function_exists('wp_bootstrap_posts_pagination') ? 'wp_bootstrap_posts_pagination' : 'the_posts_pagination', array( array(
  'prev_text'          => __( 'Previous page', 'textdomain' ),
  'next_text'          => __( 'Next page', 'textdomain' ),
  'before_page_number' => '<span class="meta-nav screen-reader-text">' . __( 'Page', 'textdomain' ) . ' </span>'
) ) );

// Previous/next post navigation.
call_user_func_array(function_exists('wp_bootstrap_post_navigation') ? 'wp_bootstrap_post_navigation' : 'the_post_navigation', array( array(
  'next_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Next', 'textdomain' ) . '</span> ' .
    '<span class="screen-reader-text">' . __( 'Next post:', 'textdomain' ) . '</span> ' .
    '<span class="post-title">%title</span>',
  'prev_text' => '<span class="meta-nav" aria-hidden="true">' . __( 'Previous', 'textdomain' ) . '</span> ' .
    '<span class="screen-reader-text">' . __( 'Previous post:', 'textdomain' ) . '</span> ' .
    '<span class="post-title">%title</span>'
) ) );

// Edit post link
call_user_func_array(function_exists('wp_bootstrap_edit_post_link') ? 'wp_bootstrap_edit_post_link' : 'edit_post_link', array(
  sprintf(
    /* translators: %s: Name of current post */
    __( 'Edit<span class="screen-reader-text"> "%s"</span>', 'textdomain' ),
    get_the_title()
  ),
  '<span class="edit-link">',
  '</span>'
) );

Bootstrap 3

If you're still working with Bootstrap 3, you need to override at least some options.

// Bootstrap 3 Options
function my_bootstrap_options($options) {
  return array_merge($options, array(
    'img_class' => 'img-responsive',
    'align_center_class' => 'center-block',
    'edit_post_link_class' => 'btn btn-default btn-xs',
    'search_submit_label' => '<i class="glyphicon glyphicon-search"></i>',
    'gallery_thumbnail_class' => '',
    'gallery_thumbnail_img_class' => 'img-thumbnail',
    'close_button_class' => 'btn btn-default',
    'carousel_item_class' => 'item',
    'widget_class' => 'panel',
    'widget_modifier_class' => 'panel-default',
    'widget_header_class' => 'panel-heading',
    'widget_content_class' => 'panel-block'
  ));
}
add_filter( 'bootstrap_options', 'my_bootstrap_options', 1 );

API

Bootstrap Hooks is highly customizable. That's mostly required because of managing different Bootstrap versions without splitting up the codebase. Normally there should be no need to change a lot.

Methods

edit_post_link( string $text = null, string $before = '', string $after = '', int $id, string $class = 'post-edit-link' )

Displays the edit post link for post. See edit_post_link for further details.

wp_bootstrap_posts_pagination ( array $args = array() )

Displays a paginated navigation to next/previous set of posts, when applicable. See the_posts_pagination for further details.

wp_bootstrap_post_navigation ( array $args = array() )

Displays the navigation to next/previous post, when applicable. See the_post_navigation for further details.

Filters

bootstrap_options ( array $options = array() )

Inject custom options.

Options

Development

Download Docker CE for your OS. Download NodeJS for your OS.

WordPress

Run container. Point your browser to http://localhost:8020.

docker-compose up -d

Import test data. Activate wordpress-importer if needed.

docker compose run wp plugin activate wordpress-importer
docker compose run wp import vendor/wptrt/theme-unit-test --authors=skip

Update composer dependencies

docker-compose run composer update

Stop all globally running docker containers

docker stop $(docker ps -a -q)

Frontend

Install front-end dependencies

npm i

Watch front-end dependencies

npm run watch

Create a build for production

npm run build