search

liip / bootstrap-blocks-wordpress-plugin

Bootstrap Gutenberg Blocks for WordPress
https://wordpress.org/plugins/wp-bootstrap-blocks/
280 stars 60 forks source link
bootstrap bootstrap4 bootstrap5 gutenberg gutenberg-blocks wordpress wordpress-editor wordpress-plugin

readme

Bootstrap Gutenberg Blocks for WordPress

Build Status

Bootstrap Gutenberg Blocks for WordPress. This plugin adds Bootstrap components and layout options as Gutenberg blocks.

Features

Available blocks

Container

Options

Row

Options

Column

Options

Button

Options

Further Information

Supported Bootstrap versions

This plugin supports Bootstrap v4 and v5.

The version can be selected in the plugin settings (Settings > Bootstrap Blocks) or by defining the WP_BOOTSTRAP_BLOCKS_BOOTSTRAP_VERSION constant in the wp-config.php file:

Possible values right now are '4' or '5'. By default Bootstrap version 5 is selected.

CSS Grid

The CSS grid (supported with Bootstrap >= 5.1.0) can be enabled in the plugin settings (Settings > Bootstrap Blocks) or by defining the WP_BOOTSTRAP_BLOCKS_ENABLE_CSS_GRID constant in the wp-config.php file:

eg. define( 'WP_BOOTSTRAP_BLOCKS_ENABLE_CSS_GRID', true );

When the CSS grid is enabled the row and the column blocks will use custom templates for the rendering process:

The support is still experimental since it's also marked as experimental in the Bootstarp library. Please read the official Bootstrap documentation to get more information on how to use it.

Bootstrap library

Please be aware that this plugin does not include the Bootstrap library in your website. You need to do this by yourself. We decided not to include the library so that you can modify Bootstrap to your own needs before loading it.

The easiest way to do this is to add the following to your theme's functions.php:

function mytheme_load_bootstrap() {
    if ( is_admin() ) {
        return;
    }

    wp_enqueue_style( 'bootstrap', 'https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css', array(), '4.3.1' );
    wp_deregister_script( 'jquery' ); // Remove WP jQuery version
    wp_enqueue_script( 'jquery', 'https://code.jquery.com/jquery-3.3.1.slim.min.js', array(), '3.3.1', true );
    wp_enqueue_script( 'popper.js', 'https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js', array(), '1.14.7', true );
    wp_enqueue_script( 'bootstrap', 'https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js', array(), '4.3.1', true );
}
add_action( 'wp_enqueue_scripts', 'mytheme_load_bootstrap' );

Templates

All blocks are implemented as dynamic blocks. This makes it possible to overwrite the template of a block in your theme.

To overwrite a block template create a folder called wp-bootstrap-blocks/ in your theme directory. You can copy the original template from wp-bootstrap-blocks/src/templates/<blockname>.php as a starting point and adjust it to your needs.

PHP Filters

The plugin provides the following PHP filters. Please visit the following page to get more information about PHP filters: https://developer.wordpress.org/reference/functions/add_filter/.

wp_bootstrap_blocks_template_path

Changes the default theme directory name (wp-bootstrap-blocks/).

Usage

add_filter( 'wp_bootstrap_blocks_template_path', 'my_template_path', 10, 1 );

function my_template_path( $template_path ) {
    return 'block-templates/';
}

Parameters

wp_bootstrap_blocks_get_template

Possibility to overwrite the located template path before it gets loaded.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_get_template', 'my_located_template', 10, 4 );

function my_located_template( $located, $template_name, $template_path, $default_path ) {
    return 'mytheme/special-templates/block.php';
}

wp_bootstrap_blocks_locate_template

Possibility to overwrite the located template path.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_locate_template', 'my_template_locater', 10, 3 );

function my_template_locater( $template, $template_name, $template_path ) {
    return 'mytheme/special-templates/block.php';
}

wp_bootstrap_blocks_row_classes

Change classes of row block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_row_classes', 'my_custom_row_classes', 10, 2 );

function my_custom_row_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_row_css_grid_classes

Change classes of row block when CSS grid is enabled.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_row_css_grid_classes', 'my_custom_row_css_grid_classes', 10, 2 );

function my_custom_row_css_grid_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_row_css_grid_styles

Change inline styles of row block when CSS grid is enabled.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_row_css_grid_styles', 'my_custom_row_css_grid_styles', 10, 2 );

function my_custom_row_css_grid_styles( $styles, $attributes ) {
    return '--bs-gap: 3rem;';
}

wp_bootstrap_blocks_column_classes

Change classes of column block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_column_classes', 'my_custom_column_classes', 10, 2 );

function my_custom_column_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_column_css_grid_classes

Change classes of column block when CSS grid is enabled.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_column_css_grid_classes', 'my_custom_column_css_grid_classes', 10, 2 );

function my_custom_column_css_grid_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_column_content_classes

Change classes of the inner content of the column block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_column_content_classes', 'my_custom_column_content_classes', 10, 2 );

function my_custom_column_content_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_column_css_grid_content_classes

Change classes of the inner content of the column block when CSS grid is enabled.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_column_css_grid_content_classes', 'my_custom_column_css_grid_content_classes', 10, 2 );

function my_custom_column_css_grid_content_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_container_classes

Change classes of container block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_container_classes', 'my_custom_container_classes', 10, 2 );

function my_custom_container_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_button_classes

Change classes of button block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_button_classes', 'my_custom_button_classes', 10, 2 );

function my_custom_button_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_button_wrapper_classes

Change classes of button block wrapper.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_button_wrapper_classes', 'my_custom_button_wrapper_classes', 10, 2 );

function my_custom_button_wrapper_classes( $classes, $attributes ) {
    return [ 'my', 'custom', 'classes' ];
}

wp_bootstrap_blocks_row_default_attributes

Modify default attributes of the row block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_row_default_attributes', 'my_row_default_attributes', 10, 1 );

function my_row_default_attributes( $default_attributes ) {
    $default_attributes['template'] = '1-2';
    $default_attributes['noGutters'] = true;
    $default_attributes['alignment'] = 'right';
    $default_attributes['verticalAlignment'] = 'bottom';
    $default_attributes['editorStackColumns'] = true;
    $default_attributes['horizontalGutters'] = 'gx-5';
    $default_attributes['verticalGutters'] = 'gy-3';
    return $default_attributes;
}

wp_bootstrap_blocks_column_default_attributes

Modify default attributes of the column block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_column_default_attributes', 'my_column_default_attributes', 10, 1 );

function my_column_default_attributes( $default_attributes ) {
    $default_attributes['sizeLg'] = 4;
    $default_attributes['sizeMd'] = 6;
    $default_attributes['equalWidthXl'] = true;
    $default_attributes['bgColor'] = 'primary';
    $default_attributes['padding'] = 'p-3';
    $default_attributes['contentVerticalAlignment'] = 'bottom';
    return $default_attributes;
}

wp_bootstrap_blocks_container_default_attributes

Modify default attributes of the container block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_container_default_attributes', 'my_container_default_attributes', 10, 1 );

function my_container_default_attributes( $default_attributes ) {
    $default_attributes['isFluid'] = true;
    $default_attributes['fluidBreakpoint'] = 'md';
    $default_attributes['marginAfter'] = 'mb-3';
    return $default_attributes;
}

wp_bootstrap_blocks_button_default_attributes

Modify default attributes of the button block.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_button_default_attributes', 'my_button_default_attributes', 10, 1 );

function my_button_default_attributes( $default_attributes ) {
    $default_attributes['url'] = 'https://getbootstrap.com/';
    $default_attributes['linkTarget'] = '_blank';
    $default_attributes['rel'] = 'noreferrer noopener';
    $default_attributes['text'] = 'Bootstrap';
    $default_attributes['style'] = 'secondary';
    $default_attributes['alignment'] = 'right';
    return $default_attributes;
}

wp_bootstrap_blocks_enqueue_block_assets

Possibility to disable enqueuing block assets.

Parameters

Usage

add_filter( 'wp_bootstrap_blocks_enqueue_block_assets', 'disable_enqueue_block_assets', 10, 1 );

function disable_enqueue_block_assets( $enqueue_block_assets ) {
    // Disable enqueuing block assets
    return false;
}

PHP Actions

wp-bootstrap-blocks_updated

Fires when a new version of the plugin is used for the first time.

Parameters

Usage

add_action( 'wp-bootstrap-blocks_updated', 'my_after_plugin_update', 10, 2 );

function my_after_plugin_update( $new_version, $old_version ) {
    echo "wp-bootstrap-blocks got updated from v" . $old_version . " to v" . $new_version;
}

JavaScript Filters

The plugin provides the following JavaScript filters. They can be used by enqueuing a custom JavaScript file which implements those filters.

Example:

If you have a script called block-filters.js inside your theme root you can enqueue it by adding the following code to your functions.php file.

function mytheme_enqueue_block_editor_assets() {
    wp_enqueue_script( 'block-filters', get_stylesheet_directory_uri() . '/block-filters.js', array( 'wp-hooks' ), '1.0.0', true );
}
add_action( 'enqueue_block_editor_assets', 'mytheme_enqueue_block_editor_assets' );

Please visit the following page to get further instructions on how to use JavaScript filters: https://developer.wordpress.org/block-editor/developers/filters/block-filters/.

wpBootstrapBlocks.button.styleOptions

Modify available button styles.

Usage

function myButtonStyleOptions( styleOptions ) {
    styleOptions.push( {
        label: 'My Option',
        value: 'my-option',
        bgColor: '#ff0000',
        textColor: '#ffffff',
    } );
    return styleOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.button.styleOptions',
    'myplugin/wp-bootstrap-blocks/button/styleOptions',
    myButtonStyleOptions
);

Parameters

Each styleOption object should have the following attributes:

wpBootstrapBlocks.container.marginAfterOptions

Modify margin after options.

Usage

function myMarginAfterOptions( marginAfterOptions ) {
    marginAfterOptions.push( { label: 'Huge', value: 'mb-8' } );
    return marginAfterOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.container.marginAfterOptions',
    'myplugin/wp-bootstrap-blocks/container/marginAfterOptions',
    myMarginAfterOptions
);

Parameters

Each marginAfterOption object should have the following attributes:

wpBootstrapBlocks.row.templates

Define block templates.

Usage

function myRowTemplates( templates ) {
    templates.push( {
        name: '1-3',
        title: '2 Columns (1:3)',
        icon: 'layout',
        templateLock: 'all',
        template: [
            [
                'wp-bootstrap-blocks/column',
                {
                    sizeMd: 3,
                },
            ],
            [
                'wp-bootstrap-blocks/column',
                {
                    sizeMd: 9,
                },
            ],
        ],
    } );
    return templates;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.row.templates',
    'myplugin/wp-bootstrap-blocks/row/templates',
    myRowTemplates
);

Parameters

Each template object should have the following attributes:

wpBootstrapBlocks.row.enableCustomTemplate

Enable/Disable custom option in row templates.

Usage

// Disable custom row template
wp.hooks.addFilter(
    'wpBootstrapBlocks.row.enableCustomTemplate',
    'myplugin/wp-bootstrap-blocks/row/enableCustomTemplate',
    () => false
);

Parameters

wpBootstrapBlocks.row.horizontalGuttersOptions

Modify available horizontal gutters options for row block.

Usage

function myRowHorizontalGuttersOptions( horizontalGuttersOptions ) {
    horizontalGuttersOptions.push( { label: 'Medium', value: 'gx-4' } );
    return horizontalGuttersOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.row.horizontalGuttersOptions',
    'myplugin/wp-bootstrap-blocks/row/horizontalGuttersOptions',
    myRowHorizontalGuttersOptions
);

Parameters

wpBootstrapBlocks.row.verticalGuttersOptions

Modify available vertical gutters options for row block.

Usage

function myRowVerticalGuttersOptions( verticalGuttersOptions ) {
    verticalGuttersOptions.push( { label: 'Medium', value: 'gy-4' } );
    return verticalGuttersOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.row.verticalGuttersOptions',
    'myplugin/wp-bootstrap-blocks/row/verticalGuttersOptions',
    myRowVerticalGuttersOptions
);

Parameters

wpBootstrapBlocks.row.cssGridGuttersOptions

Modify available CSS grid gutters options for row block.

Usage

function myRowCssGridGuttersOptions( cssGridGuttersOptions ) {
    cssGridGuttersOptions.push( { label: 'Medium', value: '1.5rem' } );
    return cssGridGuttersOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.row.cssGridGuttersOptions',
    'myplugin/wp-bootstrap-blocks/row/cssGridGuttersOptions',
    myRowCssGridGuttersOptions
);

Parameters

wpBootstrapBlocks.column.bgColors

Modify available background colors for column block.

Usage

function myColumnBgColorOptions( bgColorOptions ) {
    bgColorOptions.push( {
        name: 'brand',
        color: '#6EA644',
    } );
    return bgColorOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.column.bgColorOptions',
    'myplugin/wp-bootstrap-blocks/column/bgColorOptions',
    myColumnBgColorOptions
);

Parameters

wpBootstrapBlocks.column.paddingOptions

Modify available padding options for column block.

Usage

function myColumnPaddingOptions( paddingOptions ) {
    paddingOptions.push( { label: 'Huge', value: 'p-8' } );
    return paddingOptions;
}
wp.hooks.addFilter(
    'wpBootstrapBlocks.column.paddingOptions',
    'myplugin/wp-bootstrap-blocks/column/paddingOptions',
    myColumnPaddingOptions
);

Parameters

Developer information

Requirements

Installation

  1. Clone this repository

  2. Install composer dependencies

    curl -s https://getcomposer.org/installer | php
php composer.phar install

  3. Install Node dependencies

    npm install

Compile assets

The build process is based on the official @wordpress/scripts package.

Generate translation files

  1. To extract the labels and generate the languages/wp-bootstrap-blocks.pot file run the following command:

    ./scripts/translations/extract-messages.sh

  2. To update the translation files (*.po) run the following command:

    ./scripts/translations/update-translation-files.sh

  3. To generate the *.mo and *.json translation files run the following command:

    ./scripts/translations/compile-translation-files.sh

Setup local dev environment

The following commands can be used to set up a local dev environment. See the official documentation of @wordpress/env for a complete list of commands.

Testing

There are two types of tests for this plugin:

PHPUnitTests

The PHPUnit tests are stored in the phpunit/ directory. They use fixtures to validate the block output. Each block variant which should be tested needs a manually created file called blockname__variant.html. This file contains the block presentation in the editor (a.k.a. the HTML comment presentation) and needs to be stored in the following folder:

phpunit/blockname/fixtures/blockname_variant.html

The second fixture of each variant is the blockname_variant.output.html file. This file gets automatically generated if the test runs for the first time and the environment variable WP_BOOTSTRAP_BLOCKS_RECORD in the phpunit.xml.dist file is set to true.

To run the tests use the following command:

npm run test:unit:php

or the following command to run a specific test:

npm run test:unit:php -- --filter 'my_test'

Playwright E2E Tests

The Playwright E2E Tests are stored in the playwright directory.

To run the tests use the following command:

npm run test:e2e