itineris/sage-flbuilder

• Minimum Requirements
• Installation
• Rules
• Caveats
  • Module Names
• Customizing PostGrid
  • Templates
  • Subclass
• Usage - Minimum
  • Step 1 - Define helper class
  • Step 2
• Usage - Custom PHP Module
  • Step 1 - Define module class
  • Step 2 - Frontend Template
  • Step 3 - Add custom module into SageFLBuilder
• Usage - Custom Blade Module
  • Step 1 - Inherit from AbstractBladeModule.
  • Step 2 - Frontend Template
  • Step 3
• Usage - Custom Settings
  • Step 1 - Define Setting Class
  • Step 2
• Usage - Extra Settings
• Usage - Exclude Default Modules / Settings
• Migrating from Fabric

Minimum Requirements

• PHP v7.1
• Sage v9.0.0-beta.4
• illuminate/support v5.4
• Advanced Custom Fields PRO v5.6.9
• Beaver Builder Plugin (Pro Version) v2.1.1.1
• Beaver Themer v1.1.1
• Gravity Forms v2.2.6.5

You must ensure these 3 required plugins installed via Bedrock's composer.json.

Installation

➜ composer require itineris/sage-flbuilder

Rules

• Follow PSR-4
• Follow PSR-1
• Do not copy and paste from default modules - huge technical debt in this package
• Do not use God class - it is pure technical debt

Caveats

Module Names

Beaver Builder can't accept 2 modules with the same file name even they follow PSR-4.

For example, these 3 modules conflict each other:

• vendor/itineris/sage-flbuilder/src/Modules/Button/Button.php
• app/Plugins/FLBuilder/Modules/BrainHouse/Button/Button.php
• app/Plugins/FLBuilder/Modules/Trinity/Button/Button.php

Solution - Use unique class names:

• vendor/itineris/sage-flbuilder/src/Modules/Button/Button.php
• app/Plugins/FLBuilder/Modules/BrainHouseButton/BrainHouseButton.php
• app/Plugins/FLBuilder/Modules/TrinityButton/TrinityButton.php

Customizing PostGrid

Templates

Deprecated: Prior to v0.5.0, PostGrid::DIR is used to locate template directory. This is replaced with AbstractHelper::getPostGridTemplateDir.

Filter bar and post theme templates are customizable in projects, both Blade and normal .php are supported.

For example:

➜ tree web/app/themes/greenwich/app/Plugins/FLBuilder
web/app/themes/greenwich/app/Plugins/FLBuilder
├── Helper.php
└── post-grid
    ├── filter-bar-event.blade.php
    ├── filter-bar.php
    ├── post-theme-event.blade.php
    ├── post-theme-product.php
    └── post-theme.blade.php

class Helper extends AbstractHelper
{
    /**
     * Full path to PostGrid template directory.
     *
     * @return string
     */
    public function getPostGridTemplateDir(): string
    {
        return __DIR__ . '/post-grid';
    }
}

Subclass

Important: Overriding PostGrid is not recommended. Tweak your project to fit in default PostGrid whenever possible.

If you must override PostGrid with a subclass as a last resort, you have to put it into Sage's container after SageFLBuilder::init:

use App\Plugins\FLBuilder\Settings\PostGrid;
use Itineris\SageFLBuilder\Settings\PostGrid as SageFLBuilderPostGrid;

$sageFLBuilder->add(PostGrid::class)
              ->remove(SageFLBuilderPostGrid::class)
              ->init();

sage()->bind(SageFLBuilderPostGrid::class, PostGrid::class);

Usage - Minimum

Step 1 - Define helper class

namespace App\Plugins\FLBuilder;

use Itineris\SageFLBuilder\AbstractHelper;

class Helper extends AbstractHelper
{
    // Implement all abstract methods.
}

Step 2

Within app/setup.php / app/farbic.php:

use App\Plugins\FLBuilder\Helper;
use Itineris\SageFLBuilder\SageFLBuilder;

$sageFLBuilder = new SageFLBuilder(
    new Helper()
);

$sageFLBuilder->init();

Tips: Put these lines into a class method.

Usage - Custom PHP Module

Step 1 - Define module class

See: https://kb.wpbeaverbuilder.com/article/124-custom-module-developer-guide

namespace App\Plugins\FLBuilder\Modules\RunnerBlock;

use Itineris\SageFLBuilder\AbstractModule;
use Itineris\SageFLBuilder\AbstractHelper;

class RunnerBlock extends AbstractModule
{
    /**
     * Register the module and its form settings.
     * If needed, register a settings form to use in the "form" field type.
     */
    public static function register(): void
    {
        // Invoke `\FLBuilder::register_module` here
        // Invoke `\FLBuilder::register_settings_form` here
    }

    public function __construct()
    {
        /** @var AbstractHelper $helper */
        $helper = sage(AbstractHelper::class);

        parent::__construct([
            'name' => __('Runner block', 'fabric'),
            'description' => __('Runner block widget', 'fabric'),
            'category' => 'Basic',
            'group' => $helper->getModuleGroup(),
            'dir' => __DIR__,
            'url' => $helper->assetPath(__DIR__),
            'icon' => 'layout.svg',
        ]);
    }
}

Step 2 - Frontend Template

Create includes/frontend.php:

<sage>/app/Plugins/FLBuilder/Modules
└── RunnerBlock
   ├── RunnerBlock.php
   └── includes
       └── frontend.php

Step 3 - Add custom module into SageFLBuilder

use App\Plugins\FLBuilder\Helper;
use App\Plugins\FLBuilder\Modules\RunnerBlock\RunnerBlock;
use Itineris\SageFLBuilder\SageFLBuilder;

$sageFLBuilder = new SageFLBuilder(
    new Helper()
);

$sageFLBuilder->add(RunnerBlock::class)
              ->init();

Usage - Custom Blade Module

Similar to custom PHP module.

Step 1 - Inherit from AbstractBladeModule.

namespace App\Plugins\FLBuilder\Modules\BladeRunnerBlock;

use Itineris\SageFLBuilder\AbstractBladeModule;

class BladeRunnerBlock extends AbstractBladeModule
{
    // Similar to custom PHP module
}

Step 2 - Frontend Template

Create includes/frontend.blade.php:

<sage>/app/Plugins/FLBuilder/Modules
└── BladeRunnerBlock
   ├── BladeRunnerBlock.php
   └── includes
       └── frontend.blade.php

Step 3

$sageFLBuilder->add(RunnerBlock::class, BladeRunnerBlock::class)
              ->init();

Usage - Custom Settings

Step 1 - Define Setting Class

namespace App\Plugins\FLBuilder\Settings;

use Itineris\SageFLBuilder\InitializableInterface;

class MySetting implements InitializableInterface
{
    // Implement all required methods.
}

Step 2

$sageFLBuilder->add(RunnerBlock::class, BladeRunnerBlock::class, MySetting::class)
              ->init();

Usage - Extra Settings

The following settings are disabled by default:

• ProductsArchive
• FourOFourThemeLayout
• SearchThemeLayout
• WooCommerceThemeLayout

To enable them:

// Example: Enabling `FourOFourThemeLayout`
$sageFLBuilder->add(FourOFourThemeLayout::class)
              ->init();

Usage - Exclude Default Modules / Settings

$sageFLBuilder->add(RunnerBlock::class, BladeRunnerBlock::class, MySetting::class)
              ->remove(FilterBar::class, EventsArchive::class)
              ->init();

Migrating from Fabric

Since sage-flbuilder uses PSR-4 while Fabric doesn't, module names are changed. When migrating from Fabric, you have to search and replace all module name saved in database:

$ wp search-replace 'OLD_NAME' 'NEW_NAME'
$ wp search-replace 'fab_accordion' 'Accordion'

This is a bash script for sage-flbuilder's default modules:

#!/bin/bash

declare -A modules

# Base Modules
modules[fab_accordion]=Accordion
modules[fab_alert]=Alert
modules[fab_breadcrumbs]=Breadcrumbs
modules[fab_button]=Button
modules[fab_content_image]=ContentImage
modules[fab_filter_bar]=FilterBar
modules[fab_gallery]=Gallery
modules[fab_gravity_form]=GravityForm
modules[fab_page_heading]=PageHeading
modules[fab_page_slider]=PageSlider
modules[fab_secondary_nav]=SecondaryNav
modules[fab_table]=Table
modules[fab_testimonial]=Testimonial
modules[fab_video]=Video

# Add project-specific modules here, for example:
# modules[gh_welcome_section]=WelcomeSection

for i in "${!modules[@]}"
do
    echo "$i -> ${modules[$i]}"
    command="wp search-replace '$i' '${modules[$i]}' --dry-run"
    echo "Running $command"
    result=$(eval "${command} 2> /dev/null")
    if [ $? -eq 0 ];then
        echo "${result##*$'\n'}"
        printf "\n------------\n\n"
    else
        echo "Failed!"
        echo $(result | tail -n 1)
        break
    fi

done