editor.twig

One of our goals is to maintain parity between what a user sees when their editing a page in WordPress and how it looks on the front end. Our setup generally accomplishes this well without much help. However, there are some exceptions to this. When a block requires some extra attention to achieve this parity we would create an editor.twig file.

By adding an editor.twig file in the blocks folder you can customize what's shown in the editor. This is useful for adding a preview image/description of the block if its appearance when rendered from the index.twig file looks different than it does once rendered on the front end. It can also be useful for making functional improvements in the editor, for example, disabling javascript or other interactive elements (i.e. anchors) that interfere with the editor experience.

The example below shows a link in the index.twig being replaced by a div so that if the user clicks it while editing it will not redirect them to a different page and allow them to edit the content within the button.

<!-- index.twig -->

<div>
    <a href="#">
        <!-- Normally would put our InnerBlocks here but if the user tried to click on the inner blocks to edit them in the editor, it would end up linking tem to a separate page. -->
        <a href={{ fields.link }}>
            {{ content }}
        </a>
    </a>
</div>

<!-- editor.twig -->

<div>
    <!-- To work around this we make an editor.twig file, remove the <a> tag so the person editing the page doesn't have link even though one is rendered on the front end, use our InnerBlocks here, and then edit our index.twig to just display the content of our InnerBlocks. -->
    <div>
        <InnerBlocks template="{{ get_pattern('icon')|e}}" />
    </div>
</div>

Note: InnerBlocks is a placeholder for WordPress to allow editable actions in gutenberg. The contents of InnerBlocks is saved in the block posts content attribute, hence why we can use {{ content }} in the index.twig file.

Another example scenario of where this has been used is with a block to inject content into the header on a website. The index.twig file only contained the content which would then be absolutely positioned into the header that was already generated on the page via the header template, however, in order to maintain parity, the editor.twig was adjusted to show a fake version of the header with the content injected into it so that the user editing the page could see approximately how it would look when rendered on the front end.

Drawbacks

When making an editor.twig file you are adding another thing that needs to be checked if changes need to be made to a block. This should try to be avoided if at all possible so it doesn't get forgotted and we still maintain parity between the back end appearance and the front end appearance. If the differnces between what is needed on the back end and front end are big, and editor.twig is probably the solution, however if the needed differences are small, a more elegant solution may be adding an is_admin() conditional in the index.twig, so that if the block needs to be edited, it only needs to be edited in the one file.