Extending Configurations - makeitworkpress/waterfall GitHub Wiki

Basically, all the configurations of Waterfall describe the post types being registered, the scripts being enqueued and the custom fields being added. This is stored in one large multidimensional object.

Because Waterfall uses this single configuration class to store its configurations, you can very easily perform adaptations in these settings and register new post types, enqueue new scripts or add new custom fields.

Accessing the Waterfall Instance

By accessing the Waterfall Instance, you can modify most of the configurations for Waterfall. This can be done in the following way:

$waterfall = Waterfall::instance();

Subsequently, you can execute the add method on this instance to add new configurations. If you add data which match the existing array of configurations, those two are merged in a multidimensional way.

$waterfall->config->add( string $key, array $configurations );

The add method supports the following keys to add custom content:

Key	Description
'elementor'	Accepts an array with Custom Elementor Widget Class names.
'enqueue'	Accepts an array with custom scripts or styles.
'options'	Accepts an array to add custom fields to option pages, posts, users, terms or the customizer.
'register'	Accepts an array with configuration for the registration of custom post types, taxonomies, image sizes, sidebars and widgets,
'routes'	Adds an array of custom rewrite rules with matching templates, to set-up custom template routing.

To see how these arrays are set up, examples from the Waterfall Reviews plugin are given below.

Registering new Post Types, Taxonomies, Sidebars or Widgets

This example registers the reviews custom post type and the reviewsCategory custom taxonomy.

$waterfall->config->add( 'register', [
        'postTypes' => [
            [
                'name'      => 'reviews',
                'plural'    => __( 'Reviews', 'wfr' ),
                'singular'  => __( 'Review', 'wfr' ),
                'slug'      => _x('reviews', 'Reviews Slug', 'wfr')
            ],
        ],
        'taxonomies' => [
            [
                'name'      => 'reviewsCategory',
                'object'    => 'reviews',
                'plural'    => __( 'Categories', 'wfr' ),
                'singular'  => __( 'Category', 'wfr' ),              
            ],
        ]
] );

For the specific details on the build-up of this configuration array, including how to register custom sidebars, widgets and image sizes, the WP Register repository may be checked.

Adding new Options or Option Pages, Customizer Fields or Custom Fields

This example adds a custom field to the reviews post type, and add extra option fields to the existing option page of the Waterfall theme.

$waterfall->config->add( 'options', [
        'reviewMeta'    => [
            'frame'     => 'meta',
            'fields'    => [
                'class'     => 'tabs-left',
                'context'   => 'normal',
                'id'        => 'wfr_review_meta',
                'priority'  => 'high',
                'screen'    => ['reviews'],
                'single'    => true,
                'title'     => __('Review Settings', 'wfr'),
                'type'      => 'post',
                'sections'  => [
                    [
                        'icon'      => 'build',
                        'id'        => 'general',
                        'title'     => __('General', 'wfr'),
                        'fields'    => [
                            [
                                'columns'       => 'half',
                                'id'            => 'reviewed_item',
                                'title'         => __('Product Reviewed', 'wfr'),
                                'description'   => __('Name of the Product that is reviewed.', 'wfr'),
                                'type'          => 'input'                     
                            ], 
                        ]
                    ]
               ]
          ]
      ],
      'options' => [ // Because the original options array also uses the same key, we merge these arrays.
            'frame'     => 'options',
            'fields'    => [
               'sections'      => [
                    [
                        'icon'      => 'star',
                        'id'        => 'review_general',
                        'title'     => __('Review Settings', 'wfr'),
                        'fields'    => [
                            [
                                'columns'       => 'fourth',
                                'id'            => 'rating_style',
                                'title'         => __('Rating Style', 'wfr'),
                                'type'          => 'select',   
                                'options'       => [
                                    'stars'         => __('Stars', 'wfr'),
                                    'bars'          => __('Bars', 'wfr'),
                                ]                         
                            ],
                        ]
                    ]
                ]
            ]
        ] 
    ] 
] );

For the specific details on the build-up of this configuration array, the WP Custom Fields repository may be checked.

Enqueuing new scripts or styles

This example adds a couple of new styles and scripts to the theme.

$waterfall->config->add( 'enqueue', [
        ['handle' => 'wfr-style', 'src' => WFR_URI . 'assets/css/waterfall-reviews.min.css'], 
        [
            'handle'    => 'wfr-scripts', 
            'localize'  => [
                'ajaxUrl'       => admin_url( 'admin-ajax.php' ),              
            ], 
            'name'      => 'wfr',
            'src'       => WFR_URI . 'assets/js/waterfall-reviews.js', 
        ]
] );

For the specific details on the build-up of this configuration array, the WP Enqueue repository may be checked.

Registering new Elementor Widgets

This example registers the Elementor Widget with the namespaced class (or folder location) described in the array values. It expects that this class is an extension of Elementor\Widget_Base.

$waterfall->config->add( 'elementor', [
    'Waterfall_Reviews\Views\Elementor\Filter',
    'Waterfall_Reviews\Views\Elementor\Reviews',
] );

Registering new Template Routes

This example matches the /custom/ permalink with the /templates/custom.php template.

$waterfall->config->add( 'routes', [
        'custom'    => ['route' => custom/, 'title' => __('Custom Template Title')],
],  );

For the specific details on the build-up of this configuration array, the WP Routerrepository may be checked.

Global Configurations

There is also a global filter available to change any of the configurations load by the Waterfall Theme, namely 'waterfall_configurations'. Please note that this filter is executed on two separate points, namely within the after_setup_theme hook with a priority of 10 and directly.