Theme Layers Fluent API

Introduction
Usage
Settings Reference

Introduction

A Fluent API is a design pattern that simplifies complex operations by chaining method calls in a readable, step-by-step sequence. It allows developers to build and configure objects or execute commands in a more natural, procedural flow.

Usage

To use the Fluent Theme Layer API, instantiate a new Theme_Layer_Builder within functions.php, plugin, or mu-plugin file, and finish by calling register(). The underlying Framework will connect all the dots and enable all the features the Theme Layer needs.

For instance, a Theme Layer implementing every single possible engine is condensed to fewer than 20 lines of code (not counting the code that creates the variables we pass to the methods):

$layer = new Theme_Layer_Builder();
$layer->set_name( 'conversational_forms' )
      ->set_short_title( 'Conversational Forms' )
      ->set_icon( 'gform-icon--user' )
      ->set_settings_fields( $settings_fields() )
      ->set_block_settings( $block_settings() )
      ->set_overidden_fields( $overriden_fields() )
      ->set_form_css_properties( $css_properties )
      ->set_styles( $styles )
      ->set_scripts( $scripts )
      ->register();

Settings Reference

Setting		Description
set_name()	string	Sets the name.
set_short_title()	string	It is used to define the human-readable name of the Theme Layer. This is used throughout the system, from the title of the Settings page for the Theme Layer, to displaying in a list of active Theme Layers.
set_icon()	string	is used to define the icon to display in the Form Settings navigation. Should be one of our registered Gravity Forms icons.
set_settings_fields()	array	Takes an array, the structure of which should follow the typical pattern for registering Form Settings fields. The array should be an array of Settings Groups, each of which has an element for description (the title of the Settings Group), as well as fields, which should be an array of Field Definition arrays, as outlined in our Settings Framework.
set_block_settings()	array	takes an array argument. The array should be a series of key/value pairs, where the key is the machine-readable name of the settings field, and the value is an array representing the attributes of this field. Since these wind up being mapped to React components, the attributes passed need to match the props the component uses.
set_overidden_fields()	array	Takes an Array argument. The array should be a series of key/value pairs, where the key is the field or form being overridden, and the value is the classname of the View class (more on that later) that handles the overriding.
set_form_css_properties()	callable	Takes a callable argument. This is because the CSS Properties (generally) need access to the saved Settings or Block Settings fields, which are passed to the callable argument passed to the method. This allows Theme Layers to output CSS Properties based on the settings a user has defined on the Theme Layer’s Form Settings page, allowing for Theme Layers which site owners can adapt without having to write any code.
set_styles()	callable	Takes a callable argument. This is because often different things will need to be enqueued based on various settings the user has defined. By using a callable argument, the defined callback receives the form object, settings, and block settings as arguments, allowing the developer to act on these values when returning the styles to enqueue.
set_scripts()	callable	Works exactly like set_styles(), but enqueues JS files instead of CSS.
register()	none	is the final method that should be called when using the Fluent API. When it is called, the system compiles all of the information passed to the Fluent Layer and activates it as an active Theme Layer on the site. Calling any methods after this one will not have an effect.

Examples

`set_settings_fields()`

// An example of registering some settings fields.
array(
    array(
        // translators: %1 is an opening <a> tag, and %2 is a closing </a> tag.
        'description' => 'Conversational Forms',
        'fields'      => array(
            array(
                'name'  => 'enable',
                'label' => 'Enable Conversational Forms',
                'type'  => 'toggle',
            ),
        array(
                'name'         => 'form_full_screen_slug',
                'label'        => 'Conversational Forms Permalink',
                'type'         => 'text',
                'input_prefix' => site_url(),
            ),
        ),
    ),
);

`set_block_settings()`

We currently only support the built-in WordPress components.

// An example of registering a Block Settings text input.
array(
    'input_border_radius' => array(
        'type'        => 'string',
        'default'     => '',
        'section'     => 'advanced',
        'label'       => 'Input Border Radius',
        'controlType' => 'text',
    )
);

`set_overridden()`

// An example of registering an override to the entire Form, as well as any Text inputs
array(
    'form' => Form_View::class,
    'text' => Text_View::class,
);

`set_form_css_properties()`

// An example of a callback used to parse the form and block settings and return the CSS properties to display.
public function form_css_properties( $form_id, $settings, $block_settings ) {
    $border_radius = null;
    if ( isset( $settings['input_border_radius'] ) ) {
        $border_radius = $settings['input_border_radius'];
    }
    if ( isset( $block_settings['input_border_radius'] ) ) {
        $border_radius = $block_settings['input_border_radius'];
    }
    return array(
        'gf-color-primary' => isset( $settings['primary_color'] ) ? $settings['primary_color'] : null,
        'gf-ctrl-border-radius' => $border_radius,
    );
}

This will result in the following CSS block being output for the form:

gform_form_{form_id} {
    --gf-color-primary: #ccc, // the value from $settings['primary_color']
    --gf-ctrl-border-radius: 20px, // the value from $border_radius
}

`set_styles()`

The final array returned should be a series of arrays, each of which provides the various arguments passed to wp_enqueue_script().

// An example of enqueueing some stylesheets based on whether the 'enable' setting is active.
public function get_styles( $form, $ajax, $settings ) {
    if ( ! isset( $settings['enable'] ) || ! $settings['enable'] ) {
        return array();
    }
    $base_url = \GFCommon::get_base_url();
    return array(
        array(
            'gravity_forms_theme_reset',
            "$base_url/assets/css/dist/gravity-forms-theme-reset.css",
        ),
        array(
            'gravity_forms_skeleton_theme',
            "$base_url/assets/css/dist/gravity-forms-skeleton-theme.css",
        ),
        array(
            'gravity_forms_orbital_theme',
            "$base_url/assets/css/dist/gravity-forms-orbital-theme.css",
        ),
        array(
            'gravity_forms_conversational_theme',
            plugin_dir_url( __FILE__ ) . '../../../assets/css/dist/theme.css',
        ),
    );
}