basics__components.md

Components

OffbeatWP is a component driven framework for Wordpress. Components are blocks that can be rendered into your view. Components are really flexible and can be mapped to widgets, page builder elements, shortcodes and later even Gutenberg blocks.

A component can have its own class that contains all the information, settings and logic to render the component.

Creating a component

A component can easily be generated by OffbeatWP through the CLI:

wp offbeatwp make-component {name}

If you want to create a component for a module you can do this by adding --module={module_name} to the command line:

wp offbeatwp make-component {name} --module="{module}"

The command also accepts an argument --supports="" containing a comma-separated list of interfaces the components support

Rendering a component

Without supporting other interfaces the only way to render you component within a view is by calling the component within a twig template: {{ component('COMPONENT_NAME', {}) }}

When the component is in your /components/ folder the name will be equal to the folder of your component. The first character will be lowercased automatically. So component Jumbotron will get the name Jumbotron.

If the component is in one of your modules the name will be prefixed with the name of your module (the first character will be lowercased here as well). So a component "List" in the module "Downloads" will get the name "download.list".

Supporting Interfaces

Currently, there are 3 supported interfaces

1. widget
2. shortcode
3. page builder

To add support of one of the interface to your component you only have to add it to the supports attribute in the settings method, like:

    public static function settings()
    {
        return [
            'name'       => 'Pino',
            'slug'       => 'pino',
            'supports'   => ['widget', 'shortcode', 'pagebuilder'],
        ];
    }

A fourth interface will be added soon: 'editor' for Gutenberg

Page builder

OffbeatWP has implemented a really flexibele page builder into Wordpress. It's integration with Advanced Custom Fields. It provides you with a drag-and-drop editor the build your pages. The awesome thing about this builder is that you have 100% control over the output of the editor.

Check out more information about the ACF Page Builder implementation for OffbeatWP

Form

You can define a form to a component so it's easy to insert data from a page builder, widget or any other implementation.

To do so you have to define a form in the settings method like:

public static function settings()
{
    return [
        'name'       => 'Button',
        'slug'       => 'button',
        'supports'   => ['pagebuilder', 'editor', 'shortcode'],
        'form'       => self::form(),
    ];
}

The attribute should be an instance of \OffbeatWP\Form\Form:class. Below an example of the form() method that should be included inside the component class:

public static function form()
{
    $form = new Form();

    $form
        ->addTab('general', 'General')
            ->addSection('general', 'General')
                ->addField(new \OffbeatWP\Form\Fields\Text('title', 'Title'))
                ->addField(new \OffbeatWP\Form\Fields\Text('title1', 'Title 1'))
                ->addField(new \OffbeatWP\Form\Fields\Text('title2', 'Title 2'))
        ->addTab('general2', 'General')
            ->addSection('general2', 'General')
                ->addField(new \OffbeatWP\Form\Fields\Text('title2', 'Title'))
                ->addField(new \OffbeatWP\Form\Fields\Text('title21', 'Title 1'))
                ->addField(new \OffbeatWP\Form\Fields\Text('title22', 'Title 2'));

    return $form;
}

More about the Form functionality you'll find at Forms