Common Pitfalls When Configuring Entity Browser in Drupal 8

One of Drupal’s biggest strengths is its flexibility and extensibility, allowing developers to create, for example, custom-tailored editorial workflows. In this article, we will examine Entity Browser, a powerful component of Drupal’s contributed ecosystem of modules for managing digital media assets.

To make it easier to follow along with the article, let’s consider two fictional characters: Bob, who works as a copy editor for a big news website, and Sylvia, the Drupal developer in charge of the website Bob uses to do his job.

Bob is not very happy with the current solutions he has when editing an article, because:

• When uploading an image, he is unable to re-use an image uploaded in another article.
• When uploading an image to a gallery field, he has to upload them individually, and he wishes he could bulk-upload several images at once.
• When Bob needs to relate articles, he uses an auto-complete field which only accepts the title, forcing him open a new tab to search for articles by author, category or date, because he doesn't remember all past articles' titles by heart.
• Sometimes Bob wants to relate an article to a “quote” content type that doesn't exist yet, but he is going to create. Now he needs to stop his work, open a new tab, create the quote content, come back to the article, and then reference the quote. It bothers him a little bit having to switch so often between tabs and contexts.
• Other things (Bob always wants more).

Sylvia knows how to solve all those needs, but she is not satisfied because the solutions she previously used in Drupal 7 were not standardized, sometimes “overkill," and often difficult to maintain and extend. However, she heard that the Entity Browser module solves all these needs (and more) in a generic and powerful way.

Sylvia already discovered that this module was deliberately created with a very abstract, flexible and “pluggable” architecture. While this allows for powerful tools and workflows to be implemented, the price is often an increased learning curve about how to properly configure it for the different user needs.

This article is intended to help Sylvia (and you) discover Entity Browser. Here you will find:

• A brief description of the architecture of the module and the central concepts with which you need to be familiar.
• A list of “browser” examples that can help you understand what is possible.
• A step-by-step tutorial for configuring a browser from scratch, identifying common pitfalls that often occur in that process.

The basics

If this is your first contact with the Entity Browser module or if you are still wrapping your head around its configuration, there are some key concepts that you should start familiarizing yourself with, indicated below.

Note: The following description uses concepts and terminology not very easy to understand at first sight. It’s OK if not everything is 100% clear after the first read. The configuration steps below will certainly help you confront this challenge. In any case, I would highly recommend you take the time to go over the documentation indicated in each of the links below and check the examples there. It's always easier to grasp the concepts with some images and real examples.

The “browser” is a configuration entity that can be created through the UI by the site-builder, or imported from a configuration YAML file. This config entity will base its behavior on the settings defined by the following four plugins:

• The Display plugin, which is responsible for presenting the entity browser to the end user (editor), in different contexts. Examples of this are “iFrame” or “Modal.”
• The Widget plugin, which is the tool the editor will use to effectively browse/search/select or create the piece of content they are looking for. Examples of this plugin that ship with the module is “File Upload” or “Views.”
• The Widget Selector plugin, which as the name suggests, is responsible for providing a mechanism for the end user to select a specific widget, among a set of available ones. Selector examples could be “Tabs” or “Dropdown.”
• The Selection Display plugin, which allows a “temporary storage area,” where the editor will be able to have visual feedback about the entities they've selected. 

Once all these are plugins, other contributed modules (and also your custom code!) can easily provide new ones. So don’t be surprised if at some point you encounter more options than the ones listed above.

Check some existing examples…

Many modules and distributions showcase what is possible to build using Entity Browser. The following video is based on the File Entity Browser module, which provides a pre-configured browser, along with some nice front-end adjustments.

This is an excellent way to become familiar with the module and the different use cases. These are some of the existing examples you can explore:

Modules that provide pre-configured browsers:

• File Entity Browser (for managing files and images)
• Content Browser (for managing nodes)
• Media Entity Browser (for managing media entities, when using the Media Entity module)
• Entity Browser Enhance(d|r) (improves the styling of the views being used as widgets)
• Slick Browser (uses the slick library to provide some nice UX improvements on certain browser plugins. Compatible with several entity types: files, images, media entities, etc.).

Full-featured Drupal distributions that showcase entity browsers:

• Thunder (which you can test drive here)
• Lightning (which you can test drive here) 

…or create your own brand new Entity Browser!

Even if you are using one of the pre-packaged solutions mentioned above, it’s always good to understand how things work behind the scenes. For that, there’s no substitute for creating an entity browser from scratch and seeing for yourself all of the details involved. Doing this will help you discern whether a packaged solution or a custom browser will best address the particular use case involved in your project.

To create a browser from scratch, the first thing to do, after enabling the module, is to navigate to:

Configuration -> Content authoring -> Entity browsers

or go directly to the URL /admin/config/content/entity_browser and click “Add Entity browser”

Common pitfall 

The module does not depend on the Ctools module to work. However, the multi-step wizard that helps you create and edit entity browsers using the UI does. This means that in order to create a browser as shown here you need to have Ctools enabled on your site. It’s not necessary to leave it enabled afterward though.  Once your browser is finished, and no modifications are foreseen, if you don’t need Ctools you can safely disable it in your production environment.

The wizard will walk you through five steps, each of them intended to define the configuration options for the different plugins we saw before.

Step 1 - General browser configuration

In this step, you define the basic configuration of your browser, and depending on what you choose here, some of the subsequent steps may not need any configuration or will ask for different information.

If you are in doubt on what to choose here, the default values suggested may be just fine for many use cases. In our case, to make the most of the example, we will select:

• Modal display
• Tabs selector
• Multi-step selection display

Common pitfall 

If you plan to use this browser as part of an embedding workflow using the Entity Embed module, you must choose the iFrame display plugin.

Step 2 - Display configuration

This step will ask you for some information that refers to the display type you selected in the first step.

In our case, we are asked to indicate the width and height of the modal window, the label of the link/button to launch the browser, and an option to automatically open the browser, when possible (not always recommended).

For our example, we will leave the defaults.

Step 3 - Widget selector configuration

Because we are using the “Tabs” widget selector type, there's no additional configuration needed.

Common pitfall 

Note that when using the multi-step wizard, the config values won’t be effectively saved until you go to the last step and click “Finish”. Even if some steps have no configuration, or you just want to edit the configuration of a single step, for now, you always need to go to the last one and click “Finish”. You can refer to this issue if you want to help to improve this.

Step 4 - Selection display configuration

Because we selected “Multi-step” in a previous step, we have some configuration to do.

In our case, we will define that we'll be working with “File” entities (images), and this “work-in-progress zone” for the entities selected (the Selection display) should show the images as Thumbnails, using the “Thumbnail (100 x 100)” image style.

Step 5 - Widgets configuration

This is the final and most important step to configure our browser. Here we will add as many widgets as we want to expose to the user when they are using the browser.

In our example above, we have added two widgets:

• Upload: which will allow the user to upload a new image to the site
• View: allowing the editor to select a pre-existing image from a gallery (which is a view you can customize as well)

Common pitfall 

When using a view as a widget, not all views can be selected here. You must have created beforehand a view with the following characteristics:

- It shows entities of the type being selected by this browser

- It has a display of type “entity_browser"

- It has at least one field of type “Entity browser bulk select form.” This is what will make the checkboxes appear and allow the entities to be selectable.

As long as these traits are present, the view can do any additional filtering and show any information you want to make the selection process easier.

Common pitfall 

View widgets have an additional setting “Automatically submit selection” intended to save the user one click when sending the entities to the “work-in-progress selection area.” Note though that this option should only be used when the Selection Display is set to “Multi-Step.” Failing to do so may produce an error on your site such as:

Drupal\Core\Config\ConfigException: Used entity browser selection display cannot work in combination with settings defined for used selection widget. in Drupal\entity_browser\Form\EntityBrowserForm->isFunctionalForm()

You can refer to this issue if you want more information or are interested in helping the site-builder experience here.

Browser created. Now what?

Now you can use it! As mentioned before, there is a lot of abstraction involved so that the browser can be used in many different contexts. Maybe one of the most common scenarios is to use the browser as a field widget to populate entity field values, but the same browser could also be used to support embedding workflows, in a custom form that you build yourself, or other scenarios you can think of.

Moving on with our example, let’s consider we have a node content type (let’s say the “Article” content type) with an image field where we want to stop using the default core upload widget and start using our brand-new browser instead. All we need to do is head over to:

Structure -> Content types -> Article -> Manage form display

or go directly to /admin/structure/types/manage/article/form-display to change the field widget settings.

Click on the dropdown, select “Entity browser” and then click on the cog on the right to open the browser widget options.

Different browsers may have different options here. In any case, the most important operation you want to perform here is to select from the dropdown list the entity browser you want to use.

Once done, your node creation form should have been updated to use the new field widget!

When you click on “Select entities”, your browser will open:

Note that, as expected, we have two widgets (labeled here “upload” and “view”), displayed as Tabs, presented to the user in a Modal window.

Common pitfall

As seen above, the browser is a “piece” you configure and then plug into other parts of your site. Once it is very abstract, sometimes you can still plug it into some places, but it won’t work if the configuration you created for the browser is incompatible with the context you want to use it in. The following are two examples of this:

Misconfiguration scenario 1

Widgets don’t enforce entity types based on the context they are used in. This means that you could potentially use a widget to select an entity of a type incompatible with the field where that widget is being used, resulting in an error such as “The entity must be of type <type>”. You can refer to this issue for more information on this situation.

Misconfiguration scenario 2

Field widgets have a setting that allows you to define how the selection should be handled during the update process. This is called “Selection mode” and you can choose between the options “Append to selection,” “Prepend selection,” and “Edit selection”. As somewhat expected, if you choose an option like “Edit selection,” your browser must have been configured to have a “selection” available, which currently is only possible with the “Multi-step Selection Display” plugin. For example, if you choose the “No selection” plugin in the browser configuration while leaving this “Edit selection” setting on the field widget, you will end up with an error such as “Used entity browser selection display does not support pre-selection.” You can refer to this issue for more information on this.

As you can imagine by now, there are many opportunities to add variations to the process and to the final result. Your view can have other filters, show the elements in a grid instead of a table, etc. The definite best way to understand all capabilities of this tool is to play around with it yourself and explore some examples provided by others.

There are however two ingredients you can add to the mix that are worth mentioning here: the integration with DropzoneJS and Inline Entity Form.

Enhance your upload widgets with DropzoneJS

DropzoneJS is a very nice open-source library that improves the user-experience for file uploading. You can replace the standard Drupal upload widget…

... with a more user-friendly drop zone area:

At the moment of this writing, the module DropzoneJS only provides the widget shown above to be used inside entity browsers or other module integrations. After this issue is solved, you’ll be able to use it stand-alone in normal Drupal fields too, if you don’t want to have an entity browser around.

Did you know that…

In Drupal 8 the standard file upload widget can handle multiple files and drag-and-drop out of the box?

Create entities “on the fly” with the integration with Inline Entity Form

One very powerful integration of the Entity Browser module is with the Inline Entity Form contributed solution. This will allow you to use the very same entity creation form as a widget in your browser.

Please refer to the documentation for more details on how to configure the two ways in which this integration can be implemented on your site. The important thing to keep in mind here is that this can open the door for creating related content without having to leave the main context!

Conclusion

I hope this article helped you (and Sylvia!) in identifying the possibilities behind Entity Browser, and some of the most common issues when configuring it.

Do you have anything else you wish you knew when you first tried it out? Join the conversation! Please leave a comment below and let’s reduce the learning curve together.

Acknowledgements

Thanks to Seth Brown, David Burns and Juampy NR for their help with this article.

Other articles in this series

• Ways to help the D8 Media initiative
• How to Embed Just About Anything in Drupal 8 WYSIWYG with Entity Embed and URL Embed

Hero Photo by Barn Images