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

The following blocks are currently available:

• Container
• Grid (Row / Column)
• Button

• Documentation: https://github.com/liip/bootstrap-blocks-wordpress-plugin
• WordPress Plugin: https://wordpress.org/plugins/wp-bootstrap-blocks
• Changelog: https://github.com/liip/bootstrap-blocks-wordpress-plugin/releases
• Issue tracker: https://github.com/liip/bootstrap-blocks-wordpress-plugin/issues

Please be aware that this plugin does not include the Bootstrap library in your website. You need to do this for 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 function.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' );

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.

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

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

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

• $template_path (string) Template directory name in theme. (Default: 'wp-bootstrap-blocks/')

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

• $located (string) located file path.
• $template_name (string) template name which was requested.
• $template_path (string) path to template directory.
• $default_path (string) default template directory path.

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';
}

Possibility to overwrite the located template path.

• $template (string) located file path.
• $template_name (string) template name which was requested.
• $template_path (string) path to template directory.

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';
}

Change classes of row block.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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

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

Change classes of column block.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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

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

Change classes of the inner content of the column block.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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' ];
}

Change classes of container block.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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

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

Change classes of button block.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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

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

Change classes of button block wrapper.

• $classes (array) Classes which are added to the block template.
• $attributes (array) Attributes of the block.

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' ];
}

Modify default attributes of the row block.

• $default_attributes (array) Default attributes of row block.
  • template (string) Name of default template of row block (Default: '1-1')
  • noGutters (boolean) Defines if noGutters option should be selected or not (Default: false)
  • alignment (string) Default horizontal alignment of inner columns (Default: '')
  • verticalAlignment (string) Default vertical alignment of inner columns (Default: '')

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';
    return $default_attributes;
}

Modify default attributes of the column block.

• $default_attributes (array) Default attributes of column block.
  • sizeXl (int) Default xl column size (Default: 0)
  • sizeLg (int) Default lg column size (Default: 0)
  • sizeMd (int) Default md column size (Default: 0)
  • sizeSm (int) Default sm column size (Default: 0)
  • sizeXs (int) Default xs column size (Default: 12))
  • equalWidthXl (boolean) Defines if equal-width xl option should be selected or not (Default: false)
  • equalWidthLg (boolean) Defines if equal-width lg option should be selected or not (Default: false)
  • equalWidthMd (boolean) Defines if equal-width md option should be selected or not (Default: false)
  • equalWidthSm (boolean) Defines if equal-width sm option should be selected or not (Default: false)
  • equalWidthXs (boolean) Defines if equal-width xs option should be selected or not (Default: false)
  • bgColor (string) Background color of column (Default: '')
  • centerContent (boolean) Defines if center content inside column should be selected or not (Default: false)
  • padding (string) Padding inside column (Default: '')

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['centerContent'] = true;
    return $default_attributes;
}

Modify default attributes of the container block.

• $default_attributes (array) Default attributes of container block.
  • isFluid (boolean) Defines if container should be fluid or not (Default: false)
  • marginAfter (string) Default margin after container block (Default: 'mb-2')

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;
}

Modify default attributes of the button block.

• $default_attributes (array) Default attributes of button block.
  • url (string) Default url of the button (Default: '')
  • text (string) Default text of the button (Default: '')
  • style (string) Default style of the button (Default: '')
  • alignment (string) Default alignment of the button (Default: '')

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['text'] = 'Bootstrap';
    $default_attributes['style'] = 'secondary';
    $default_attributes['alignment'] = 'right';
    return $default_attributes;
}

Possibility to disable enqueuing block assets.

• $enqueue_block_assets (boolean) Defines if block assets should be enqueued. (Default: true)

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;
}

Modify available button styles.

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

• styleOptions (Array) Array with button style options.

Modify margin after options.

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

• marginAfterOptions (Array) Array margin options.

Define block templates.

function myRowTemplates( templates ) {
    templates.push( {
        name: '1-3',
        title: '2 Columns (1:3)',
        icon: <SVG />,
        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 );

• templates (array) List of template objects.

Each template has the following attributes:

• name (string) Unique identifier of the template
• title (string) Name of template
• icon (WPElement|string) An element or Dashicon slug to show as a visual approximation of the template.
• templateLock (string|false)
  • false: Columns can be added and removed
  • all: Columns can't be changed
• template (Array<Array>) see template documentation
  • Name of block. (Only wp-bootstrap-blocks/column supported!)
  • Attributes of column

Enable/Disable custom option in row templates.

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

• enableCustomTemplate (boolean) Return true if custom row template should be enabled. (Default: true)

Modify available background colors for column block.

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

• bgColorOptions (Array) Array of available background colors. Each element should be an object containing the name of the color and the color itself (see: https://github.com/WordPress/gutenberg/tree/master/packages/components/src/color-palette).

Modify available padding options for column block.

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

• paddingOptions (Array) Array of padding options.

• Node.js >= 10.x
• Docker

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
   

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

• npm start: Compiles the block in development mode. Watches for any changes and reports back any errors in your code.
• npm run lint: Lints JavaScript, CSS and package.json files.
• npm run build: Use to build production code for your block inside build folder.

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

$ curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
$ php wp-cli.phar i18n make-pot --exclude="wordpress" . languages/wp-bootstrap-blocks.pot

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

• scripts/install-wp.sh [wp-version]: Install local WordPress environment
• npm run env start: Starts the Docker containers.
• npm run env stop: Stops the Docker containers.

There are two types of tests for this plugin:

• PHPUnit Tests: Used to validate generated block output. Since this plugin uses dynamic blocks which are rendered on the server side we need to test them with PHPUnit tests.
• Puppeteer E2E Tests: Used to validate block behaviour in the editor.

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 env test-php

or the following command to run a specific test:

$ npm run env test-php -- --filter 'my_test'

The Puppeteer E2E Tests are stored in the e2e-tests directory.

To run the tests use the following command:

$ npm run test:e2e

or the following command to run a specific test:

$ npm run test:e2e -- -t 'my test'