Usage

A specific goal was to make usage of the Definitely plugins as simple as possible. It should be so simple that even someone who has just started developing things should be able to manage it.

Default method

The only things you need to know to work with any of the plugins is:

• how to hook into a WordPress action
• how to call a single class function
• how to handle an array

For all of the plugins, the steps you need to perform as a developer are the same: You hook into the plugin's initialization action. The hooked-in function will receive the plugin's main class as a parameter. You call the add_components() method of this class and specify a (probably huge) array of all the components and their data as the first parameter and a scope name (any unique identifier for your plugin, theme or whatever you are creating the components for) as the second parameter.

Example

Let's say there would be a Definitely plugin which contains three components: Foo, Bar (subtype of Foo) and Foobar (subtype of Bar). Let's imagine each of the components would have the properties 'title', 'description' and 'position', and in addition, Bar would have 'size' and Foobar would have 'type'. And finally, let's say the initialization action of the plugin would be called wpfb.

Then the code you would need to write to add something could look like the following:

function myplugin_add_fb_components( $wpfb ) {
    $wpfb->add_components( array(
        'my-custom-foo'        => array(
            'title'                => 'My Custom Foo',
            'description'          => 'This is a custom Foo instance.',
            'bars'                 => array(
                'my-custom-bar'        => array(
                    'title'                => 'My Custom Bar',
                    'description'          => 'This is a custom Bar instance which is a child of My Custom Foo.',
                    'size'                 => 50,
                    'foobars'              => array(
                        'my-custom-foobar'     => array(
                            'title'                => 'My Custom Foobar',
                            'description'          => 'This is a custom Foobar instance which is a child of My Custom Bar.',
                            'type'                 => 'some-type',
                        ),
                        'my-other-foobar'      => array(
                            'title'                => 'My Other Foobar',
                            'description'          => 'This is a second custom Foobar instance which is a child of My Custom Bar.',
                            'type'                 => 'another-type',
                        ),
                    ),
                ),
            ),
        ),
    ), 'myplugin' );
}
add_action( 'wpfb', 'myplugin_add_fb_components', 10, 1 );

Well, obviously the above plugin does not exist. :( But the above code should show you how all of them generally work. If not, you will also find a more specific documentation for each plugin itself in its own GitHub Wiki. There you will also find detailed information on all the available components for that plugin and which properties they support.

Advanced method

Generally, you should use the above techniques to work with the Definitely plugins. However, maybe you don't like to have a super-huge array or you like object-oriented development or you are just curious what the other method is. If you're not familiar with the below techniques or if you don't like them, you can simply use the default method without any drawbacks.

In short, the advanced method does not really give you any functionality benefits over the default method. It does not change anything regarding the internal behavior of the components either. It is just a matter of preference. The main difference is that the advanced method allows you to add components individually. You still provide the component data as an array, however it is only a simple array of data for a single component. You no longer combine arrays for multiple components into one. Instead you call the add() method (of either the main plugin class or of a component) to add a new component. This method accepts a component object and will then return the newly added object if successful (or a WP_Error object if not successful). When instantiating a component, it must be provided a slug (in the default method the array key will be used as the slug) and an array of properties Note that you should also set the scope, as explained above, which you can do by calling the main plugin's set_scope() method.

Example

The following code example relies on the same imagined plugin like the example for the default method above. It will also produce exactly the same components, the only difference is that this code uses the advanced method to achieve it. How you handle the errors is up to you of course - in the default method they are taken care of automatically.

Here it is:

function myplugin_add_fb_components( $wpfb ) {
    $wpfb->set_scope( 'myplugin' );
    
    $my_custom_foo = $wpfb->add( new Foo( 'my-custom-foo', array(
        'title'                => 'My Custom Foo',
        'description'          => 'This is a custom Foo instance.',
    ) ) );
    if ( is_wp_error( $my_custom_foo ) ) {
        return;
    }
    
    $my_custom_bar = $my_custom_foo->add( new Bar( 'my-custom-bar', array(
        'title'                => 'My Custom Bar',
        'description'          => 'This is a custom Bar instance which is a child of My Custom Foo.',
        'size'                 => 50,
    ) ) );
    if ( is_wp_error( $my_custom_bar ) ) {
        return;
    }
    
    $my_custom_foobar = $my_custom_bar->add( new Foobar( 'my-custom-foobar', array(
        'title'                => 'My Custom Foobar',
        'description'          => 'This is a custom Foobar instance which is a child of My Custom Bar.',
        'type'                 => 'some-type',
    ) ) );
    if ( is_wp_error( $my_custom_foobar ) ) {
        return;
    }
    
    $my_other_foobar = $my_custom_bar->add( new Foobar( 'my-other-foobar', array(
        'title'                => 'My Other Foobar',
        'description'          => 'This is a second custom Foobar instance which is a child of My Custom Bar.',
        'type'                 => 'another-type',
    ) ) );
    if ( is_wp_error( $my_other_foobar ) ) {
        return;
    }
}
add_action( 'wpfb', 'myplugin_add_fb_components', 10, 1 );

Which method should I use?

While the advanced method might be easier to read (especially if your array of components is really huge), it is a bit more complex to handle, and it is definitely more code to write. Simply decide what you prefer - both methods are fully compatible with each other.