https://github.com/benignware/wp-bootstrap-hooks
A collection of filters and actions for Bootstrap-based themes
https://github.com/benignware/wp-bootstrap-hooks
wordpress-plugin
Last synced: 11 months ago
JSON representation
A collection of filters and actions for Bootstrap-based themes
- Host: GitHub
- URL: https://github.com/benignware/wp-bootstrap-hooks
- Owner: benignware
- License: mit
- Created: 2015-01-22T18:33:29.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2025-06-23T15:26:19.000Z (about 1 year ago)
- Last Synced: 2025-06-23T16:37:56.328Z (about 1 year ago)
- Topics: wordpress-plugin
- Language: PHP
- Homepage:
- Size: 6.47 MB
- Stars: 7
- Watchers: 4
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# wp-bootstrap-hooks
A collection of filters and actions for bootstrap-based themes
When integrating [Bootstrap](http://getbootstrap.com/) 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](#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`:
```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](https://github.com/twbs/bootstrap/issues/20542) 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`:
```php
// Edit post link
wp_bootstrap_edit_post_link(
sprintf(
/* translators: %s: Name of current post */
__( 'Edit "%s"', 'textdomain' ),
get_the_title()
),
'',
''
) );
```
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](#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:
```php
// Show Font-Awesome search icon in Searchform
function my_bootstrap_options($options) {
return array_merge($options, array(
'search_submit_label' => ''
));
}
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:
```php
// 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:
```php
// 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](https://github.com/twittem/wp-bootstrap-navwalker) 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`:
```php
// Previous/next page navigation.
wp_bootstrap_posts_pagination( array(
'prev_text' => __( 'Previous page', 'textdomain' ),
'next_text' => __( 'Next page', 'textdomain' ),
'before_page_number' => ''
) );
```
Search your theme for occurrences of `the_post_navigation` and replace with `wp_bootstrap_post_navigation`:
```php
// Previous/next post navigation.
wp_bootstrap_post_navigation( array(
'next_text' => ' ' .
'' . __( 'Next post:', 'textdomain' ) . ' ' .
'%title',
'prev_text' => ' ' .
'' . __( 'Previous post:', 'textdomain' ) . ' ' .
'%title'
) );
```
### 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`:
```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:
```php
// 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:
```php
// 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' => ''
) ) );
// 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' => ' ' .
'' . __( 'Next post:', 'textdomain' ) . ' ' .
'%title',
'prev_text' => ' ' .
'' . __( 'Previous post:', 'textdomain' ) . ' ' .
'%title'
) ) );
// 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 "%s"', 'textdomain' ),
get_the_title()
),
'',
''
) );
```
### Bootstrap 3
If you're still working with [Bootstrap 3](http://getbootstrap.com/docs/3.3/), you need to override at least some options.
```php
// 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' => '',
'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](https://developer.wordpress.org/reference/functions/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](https://developer.wordpress.org/reference/functions/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](https://developer.wordpress.org/reference/functions/the_post_navigation/) for further details.
### Filters
##### bootstrap_options ( array $options = array() )
Inject custom options.
### Options
Name
Description
Default
field_class
Sets the field class used in forms
form-group
text_input_class
Sets the text input class used in forms
form-control
submit_class
Sets submit button css class
btn btn-primary
reply_link_class
Set reply link css class
btn btn-primary btn-xs
comment_label
Sets the comment label
Comment
img_class
Sets the general image class used in content and thumbnails
img-responsive
align_left_class
Aligns an image to left
pull-left
align_right_class
Aligns an image to right
pull-right
align_center_class
Center an image
mx-auto
img_caption_tag
Sets the tag for the img caption element
figure
img_caption_class
Sets the css class for the img caption element
figure
img_caption_text_tag
Sets the tag for the img caption text element
figcaption
img_caption_text_class
Sets the css class for the img caption text element
figure-caption
img_caption_img_class
Sets the css class for the image of the img element of the caption
figure-img
table_class
Sets the table css class
table
table_container_tag
Sets the table container tag
div
table_container_class
Sets the table container class
table-responsive
blockquote_class
Sets the blockquote css class
blockquote
blockquote_footer_tag
Sets the blockquote footer tag
footer
blockquote_footer_class
Sets the blockquote footer css class
blockquote-footer
edit_post_link_class
Sets the edit post link css class
btn btn-secondary
edit_post_link_container_class
Sets the edit post link container css class
form-group btn-group btn-group-sm
search_submit_label
Sets the searchfield's submit label
š
text_input_class
Sets the class of textfields used in search- and password-forms
form-control
submit_button_class
Sets the class of submit buttons used in search- and password-forms
btn btn-primary
gallery_thumbnail_size
Sets the default thumbnail size
thumbnail
gallery_thumbnail_class
Sets the default thumbnail size
gallery_thumbnail_img_class
Sets the default thumbnail size
gallery_zoom_size
Sets the image size for the carousel view
large
close_button_class
Sets the modal's close button class
btn btn-secondary
close_button_label
Sets the modal's close button label
__('Close')
carousel_item_class
Sets the carousel's item class
_item
menu_item_class
Sets the menu item class
nav-item
menu_item_link_class
Sets the menu item link class
nav-link
sub_menu_tag
Sets the sub menu tag
ul
sub_menu_class
Sets the sub menu class
dropdown-menu
sub_menu_header_class
Sets the sub menu class
dropdown-header
sub_menu_item_tag
Sets the sub menu item tag
li
sub_menu_item_class
Sets the sub menu item class
sub_menu_item_link_class
Sets the sub menu header class
dropdown-item
caret
Sets the menu item caret class (bs < 5)
<span class="caret"></span>
pagination_class
Sets the pagination class
pagination
page_item_class
Sets the page item class
page-item
page_item_active_class
Sets the page item active class
active
page_link_class
Sets the page link css class
page-link
post_nav_class
Sets the post navigation class
nav
post_nav_tag
Sets the post navigation tag
ul
post_nav_item_class
Sets the post navigation item class
nav-item
post_nav_item_tag
Sets the post navigation item tag
li
post_nav_link_class
Sets the post navigation link class
nav-link
paginated_class
Sets the paginated class
pagination pagination-sm
paginated_tag
Sets the paginated tag
ul
paginated_item_class
Sets the paginated item class
page-item
paginated_item_tag
Sets the paginated item tag
li
paginated_link_class
Sets the paginated link tag
page-link
next_posts_link_class
Specify next posts link class
btn btn-sm btn-secondary
previous_posts_link_class
Specify previous posts link class
btn btn-sm btn-secondary
widget_class
Sets the widget class
card
widget_modifier_class
Sets the widget modifier class
card-widget
widget_header_class
Sets the widget header class
card-header
widget_content_class
Sets the widget content class
card-body
## Development
Download [Docker CE](https://www.docker.com/get-docker) for your OS.
Download [NodeJS](https://nodejs.org) for your OS.
### WordPress
Run container. Point your browser to [http://localhost:8020](http://localhost:8020).
```shell
docker-compose up -d
```
Import test data. Activate wordpress-importer if needed.
```shell
docker compose run wp plugin activate wordpress-importer
docker compose run wp import vendor/wptrt/theme-unit-test --authors=skip
```
Update composer dependencies
```shell
docker-composeĀ runĀ composerĀ update
```
Stop all globally running docker containers
```shell
docker stop $(docker ps -a -q)
```
### Frontend
Install front-end dependencies
```shell
npm i
```
Watch front-end dependencies
```shell
npm run watch
```
Create a build for production
```shell
npm run build
```