ACF Custom Blocks

The fuxt stack is setup to work well with ACF Custom Blocks. Here is how you get them working.

The Missing Pieces frontend and backend is a good reference to look at for this.

1. Enable custom blocks

At the bottom of the /blocks/register-blocks.php fill uncomment this line:

// add_action('acf/init', 'fuxt_custom_blocks');

2. Register Block

You can do that in fuxt-backend (/blocks/register-blocks.php). You'll see some examples in there already.

Be sure to set a good icon, you use the name from WordPress dashicon set.

This is a must read.

3. Create ACF field group

In WordPress, create a field group. We recommend calling it "Block - {block name}. Then set the location as Block = {block name}. Be sure to select "Show in GraphQL". You don't need to set the GraphQL types manually. The default works.

4. Refresh Block cache

In WordPress, go to the Gutenberg settings and click the "Update block registry" button.

5. Create backend PHP template and styles

This step is how you create the visual editor that will be used to add your custom component in the backend, ie how images will be added to a component that uses images, or how specific text fields will be required. If you don't need control over this, you can add 'mode' => 'edit' to where you are registering your block and it will be the default experience. Read on to make a more custom experience.

In the fuxt-backend theme, you should create a new folder in /blocks/{block-name}/ and add a block.php and block.css file. See the examples on what these can be built to do. The "credit" block is a good one to start with as it's simple.

Note the way the class is always added to the template.

This is a helpful read.

6. Add GQL to frontend

You'll want to add the GQL fields to your /gql/fragments/GutenbergBlocks.gql file. It will be similar to this.

# Custom Blocks
fragment CreditBlock on Block {
    ... on AcfCreditBlock { # AcfCreditBlock is always like `Acf${BlockName}Block`
        attributes {
            wpClasses: className
        }
        fields: blockCredit { # blockCredit is the ACF field group name 
            name
            title
        }
    }
}

Note the fields alias is important, this will ensure your fields get mapped to the component props automatically.

At the top of the GutenbergBlocks.gql file you'll then want to use your fragment, like this:

fragment GutenbergBlocks on BlockEditorContentNode {
    blocks {
        name

        ...FreeformBlock
        ...ParagraphBlock
        # There will be a lot more here

       # Custom blocks
       ...CreditBlock
    }
}

If you want your block to be used in the Columns blocks, then be sure to add your fragment to the fragment ColumnBlock you'll find in the GutenbergBlocks.gql file as well.

Import new component

In the /components/WpGutenberg.vue file you'll want to important your new template for the frontend component. Like this:

components: {
    GutenbergYourBlockName: () => import("~/components/gutenberg/YourBlockName")
}

7. Build your Vue template

Build your template as you normally would. The ACF fields will be props.