Add-on Developers

Working on some custom functionality, or building out a new fieldtype? Bloqs was built with you in mind and comes packaged with some features to make your life as easy as possible.

Adding Fieldtype Support

Getting your field type working with Bloqs is a 3 step process, all of which are pretty straight forward.

Step 1 - Your Field Type must be compatible with Grid

You’re going to start out the process by first getting your field type to be compatible with Grid. If you haven’t done this before, EllisLab has put together some excellent documentation to help you out with the process which you can find here: https://docs.expressionengine.com/latest/development/fieldtypes.html#grid-fieldtype-development

Once your field type is compatible with Grid, you're just about there!

Step 1.b - Depending on the complexity of your fieldtype

If your fieldtype creates new HTML elements, similar to adding new rows in a table, and stores the new row HTML template in a <script> or <template> tag you might need to add a little extra JavaScript to the onDisplay() method in your grid.js file. Since the HTML is inside of a <script> or <template> tag, Bloqs can't perform these updates for you. For example, in the onDisplay handler you may need to ensure the form fields in your newly added markup have the correct block ID value. The following is an example to get you started:

var onDisplay = function(cell) {
    var isBloqs = cell.hasClass('blocksft-atom');

    if (isBloqs) {
        var $myFieldtype = $('.my-fieldtype');

        $myFieldtype.find('[name]').each(function() {
            var $field = $(this);
            var blockId = $field.closest('.blocksft-block').data('id');
            var eleName = $field.attr('name');

            $field.attr('name', eleName
                .replace(
                    /blocks_new_block_\d+/gm,
                    blockId
                ));
        });
    }
};

Step 2 - Opt in for Bloqs Support

The second step in the process is configuring your field to “opt in” to Bloqs support. This sounds tricky, but it’s really not. To do this, just modify the accepts_content_type method in your field type so that it also accepts content for “bloqs/1”.

Here’s a simple and straight forward example you can reference:

public function accepts_content_type( $name )
{
    return ($name == 'channel' || $name == 'grid' || $name == 'bloqs/1');
}

You may see some fieldtypes referencing "blocks/1" as the accepts content type, and that is perfectly valid. Bloqs version 4.4.0 made the nomenclature switch from "blocks" to "bloqs" in the documentation, UI, and references within it's own codebase.

Step 3 - Test

The third and final step in the process is to test everything out and make sure it's running smoothly.

That's all there is to it!

Hooks

blocks_discover_fieldtypes

The blocks_discover_fieldtypes hook is called when Bloqs needs to determine which fieldtypes support Bloqs. Extensions may add or remove fieldtypes from the list of valid fieldtypes.

blocks_discover_fieldtypes is called with a single PHP array of stdClass objects, and should return that same PHP array, potentially modified.

The format of the objects within the array is as follows:

• type – ExpressionEngine's identifier for the fieldtype. E.g. 'wygwam'.

• version – The version of the fieldtype. E.g., '1.2'.

• name – The human-readable name of the fieldtype. E.g. 'Wygwam'.

• adapter (optional) – An object that serves as an adapter to a fieldtype. If the adapter is set, before Bloqs calls a method on the fieldtype, it first checks if the adapter has the same method, and calls it instead. If the adapter has a setFieldtype method, it will be called with the actual fieldtype that is being shimmed.

blocks_post_save

The blocks_post_save hook is called after Bloqs has finished saving.

The parameters that are passed to the hook are as follows:

• blocks – The blocks that now belong to the field.

• context – The context of the field, as an array.

  • $context['site_id']

  • $context['entry_id']

  • $context['field_id']