This article describes the compatibility of WordPress File Upload plugin with Gutenberg, the new editor of WordPress and provides instructions for migrating from the old classic to the new one.

Gutenberg is an entirely new editor, developed by WordPress, which relies on blocks, like some existing page builders. Its purpose is to make page and post writing experience faster, more flexible and more amusing.

Gutenberg editor was introduced in WordPress version 4.9.8 as an optional plugin, so that administrators can test and “play” with it. It will be incorporated in WordPress core and become the default editor in the next major release (version 5).

In this respect, themes and plugins need to make sure that they are compatible with the new editor.

Compatibility

WordPress File Upload works with shortcodes, which are placed inside pages or posts. In addition, some times custom code is required to be added inside pages or posts in order to implement advanced requests by users. The following paragraphs describe compatibility of both shortcodes and code.

Shortcodes

The plugin uses [wordpress_file_upload] shortcode to display the upload form as well as [wordpress_file_upload_browser] shortcode to display the front-end file viewer.

It also includes a shortcode visual editor, which admins can use to configure the shortcodes easily and quickly.

Gutenberg has a separate Shortcode block for adding shortcodes inside pages and posts.

This is the recommended way to do it. However, shortcodes can also be added in Custom HTML blocks, Classic blocks and maybe some others.

WordPress File Upload shortcodes are fully compatible with Gutenberg, regardless of how they will be added.

Furthermore, the plugin’s shortcode visual editor is also fully compatible with Gutenberg. Updates to the shortcodes performed through the visual editor will be seamlessly reflected into the page or post, as opposed to several existing page builders who exhibit compatibility problems.

Custom Code

In the old classic editor custom Javascript code could be added using the HTML view and wrapping the code in <script> tags, though there were limitations and sometimes problems.

In Gutenberg, custom Javascript or CSS code can be reliably added using Custom HTML block. Again Javascript code needs to be wrapped in <script> tags and CSS code needs to be wrapped in <style> tags.

Writing custom code in Gutenberg is much easier. It offers several code editor functionalities, such as line numbering, syntax highlighting and word auto-completion.

Migration

This section describes how to migrate pages containing the plugin’s shortcodes and/or relevant custom code from the old classic editor to Gutenberg.

Below is an example of the contents of a page, in HTML view, that contains the plugin’s upload form, a file viewer and some custom Javascript code that fills the upload form’s ID field with a random string:

The page looks like this when opened in a browser:

The upload form and file viewer are rendered correctly and ID field is filled with a random string, as expected.

When Gutenberg is enabled and the above page is opened for editing, the page contents are initially shown inside a Classic block like this:

The two plugin’s shortcodes are right in place as before. However, if we take a look to the underlying HTML code of the page, by switching to “Edit in HTML” mode from  menu, we see some differences:

The two shortcodes and the script have been automatically wrapped in paragraph (<p>) tags, which do not affect their appearance.

However, Gutenberg has also added newline HTML elements (<br />) inside the script code, which makes it invalid, so the script will not work.

Furthermore, this is what happens if we try to convert the Classic block to normal Gutenberg blocks by pressing “Convert to Blocks” item from  menu:

The two shortcodes have been successfully converted into Shortcode blocks, however the script has been converted into a Paragraph block and it is completely meshed up. If we update the page, this is what it looks like when opened in the browser:

The script’s code is exposed on the browser and of course it doesn’t work (ID field is not filled with any random string).

So, here are instructions for correctly migrating to Gutenberg.

Migrating the Shortcodes

The correct way to migrate the plugin’s shortcodes to Gutenberg, is to convert them to Shortcode blocks.

The easiest way to do it is to press “Convert to Blocks” item from  menu and they will be straight converted into Shortcode blocks. No further action is required.

An alternative way is to manually add Shortcode blocks inside the page and then fill their contents with the plugin’s shortcode text.

Migrating the Custom Code

If the page contains custom script code, like the one in the previous example, then we need to manually add a Custom HTML block in the page and copy the code in there, like this:

Before putting the code in the block, we need to make sure that it does not contain and <br /> elements which will break its operation.

Now if we save the page and open it in the browser we will see that everything works perfectly, both the shortcodes and the scripts.

Future Considerations

Future versions of WordPress File Upload plugin will include dedicated Gutenberg blocks for adding upload forms and file viewers inside pages and posts very easily, without requiring any knowledge about shortcodes.

For any questions or problems related to WordPress File Upload and Gutenberg, do not hesitate to contact us.

The Iptanus Team