Entity Browser in Drupal 8: How to Create Your Own Custom Browser 

Entity Browser in Drupal 8: How to Create Your Own Custom Browser 

A browser “wearing your signature”! One “loaded” with tailor-made features serving the browsing/selecting “needs” of that custom editorial workflow that you're implementing! One that would ease your content editors' lives! Now it's time to stop fantasizing about the possibility of creating your own browser and to... actually do it. To get yourself familiarized with Entity Browser in Drupal 8! Here's why and how to harness its “power:

But first, let me try and give an all-encompassing definition of what the Entity Browser module is and does:

  1. it's a component of the Drupal 8 Media ecosystem of modules
     
  2. it provides you with an ideally generic and (therefore) flexible entity browser/selector!

As a Drupal site builder you get to build your own entity browser from scratch, right in the provided UI! 

Note: the singular mode isn't 100% properly used though; when we refer to the Entity Browser in Drupal 8 we're actually referring to a whole “infrastructure” of modules that make for the solid base for you to build your browser on.

A custom-made browser to use whenever you're dealing with a “multiple entities to choose from and to use” type of scenario.
 

Content Editors Will Love It/You For Leveraging Its Power 

And this flexible tool for handling entities is yet just another “surprise gift” from Drupal 8 to its editor end-users, which adds up to the whole list of editorial experience-enhancing tools and features.

And here's what will make you, the Drupal developer, a “rockstar” in their eyes once you've successfully configured this entity browser. Once you've supercharged their entity handling workflow with efficiency-boosting tools:

  • they'll be able to bulk-upload images to a gallery field at once
     
  • they'll get to re-upload images that they will have already uploaded in previous articles
     
  • they'll get to easily search for related content by entering various criteria (besides the standard “title” criteria, the only one accepted up to now) in the auto-complete field
     
  • they'll get to reorder and to easily remove entities
     
  • they'll get to easily add quotes to their articles without the need to open a separate tab for creating the quote content itself: they'll be able to do it right there, in the same tab
     
  • they'll get to embed entities of their liking into WYSIWYG

Are these 6 reasons strong enough to answer your legitimate question: “Why should I bother enabling and configuring Entity Browser in Drupal 8?
 

A Pluggable Architecture: The 4 Key Plugins Powering It Up

The module's tempting flexibility lies in its very own abstract, pluggable structure. And speaking of its plugins, here are the 4 ones that its relies on:

  1. the Widget Selector: it provides the editor with a widget option set to browse through and to select from
     
  2. the Widget Plugin: the tool that the content editor will get to use for browsing/selecting/creating entities
     
  3. the Selection Display: the end user (the editor again!) gets a preview of the way the entities that he will have selected get displayed
     
  4. the Display Plugin: displays the entity browser to the editor in various contexts (e.g. “Modal” or “iFrame”)

And there's more! More plugins, that other contributed modules (or custom code) can provide and which you can “pile up” into your custom entity browser!
 

And This Is How You Configure Your Entity Browser in Drupal 8

But before I go on detailing you the steps, I feel I should “warn” you though: do expect a steep learning curve

The module's incredible flexibility, which enables you to implement a custom-fit entity workflow, does come with a cost. And with a risk for you to fall into some of the most common pitfalls when configuring your browser.

Stay reassured: I'll do point out a few as I'll take you through the steps required.

Now first things first: before you're up to your elbow in configuration, make sure you first enable your module (obviously!), then navigate to Configuration> Content authoring> Entity browsers> next hit the “Add Entity Browser” button.

Warning: you'll need to enable the Ctools module, too, when creating and editing your new browser. However, your custom entity browser doesn't need Ctools to work. So if you don't anticipate any modifications, feel free to disable it once you have your new browser up and running!

Step 1: Define Your Browser's Basic Features 

And you'll be defining the general configuration of your browser by selecting all the plugins needed for it to work:

  • the available widgets: horizontal tabs or a drop-down menu or a single widget
     
  • the selection display option (how the entity selection will get displayed to your editors): your editors could visualize it as a view, as a multi-step selection display or as a no selection display 
     
  • your entity browser's display type: it could be an iFrame container, a standalone form, a modal window

As you'll go on selecting your new browser's basic features, you'll see that not all the steps required involve configuration. 

Also, when the “paradox of choice” gets to you, rely on the default values you have there. They might prove to be perfect fits in multiple use cases.

Entity Browser in Drupal 8: define your browser's basic features

Warning: do keep in mind to select the iFrame container as your display type if your new browser will be part of an embedding workflow (supported by the Entity Embed module)

Step 2: Configure Your Display 

From a basic features defining phase you'll now level up to a more detailed one as you configure your Entity Browser in Drupal 8!

It's during this step that you'll get to select the size, auto-opening, style etc. of the display that you've just configured at step 1.

Good news: not all the features presented to you for selection require configuration!

Entity Browser in Drupal 8: configure your display

Step 3: Configure Your Widget Selector

Warning: do keep in mind that none of the configuration values that you'll select, as you'll go through all the required steps, will get effectively saved unless you hit the “Finish” button. Remember to always go all the way to the very last step (and click “Finish”), even if your selected features don't require configuration or if you're configuring one step only!

Step 4: Add the Widgets to Your Entity Browser

Meaning: here is where you supercharge your content editors with lots of powers!

Do remember that this is, by far, the most important step to take as you configure your Entity Browser in Drupal 8! 

And here are the widget plugins that you get to pick from and add to your browser:

  • Upload: it will enable the editor to upload new images to the Drupal website
     
  • View: it will allow the end user to choose an image already included in another gallery (which is an entity listing view, in fact, that you get to customize)
     
  • Entity form
     
  • Upload images

Entity Browser in Drupal 8: add the widgets to your browser

Warning: do be prepared to accept the fact that you can't select from all the available views here, in case you plan to use View as your widget. You need to create a view featuring specific characteristics (to show the type of entities that your new custom browser will be selecting etc.) beforehand. Then you get to use it as a widget!
 

Pre-Configured Browsers to Choose From 

Although no pre-packeged solution could fit perfectly your into your own team's idea of a custom editorial workflow, you should know that there are plenty of pre-configured browsers out there to pick from! They all leverage the power of the Entity Browser in Drupal 8.

Let me me list a few:

Entity Browser in Drupal 8 + Inline Entity Form: A Match Made in Heaven!

With their forces combined, these two modules can instantly... brighten up any content editor's day!

Entity Browser easily integrates with Inline Entity Form, a “content editing” super tool which allows editors to easily manage content in the very same form.

Just think about it: entities will be twice as easy to create and twice as convenient to browse through! 
 

Wrap Up

I do value your time, though! And since this module's capabilities are almost endless I've only “overflown” them in my post here. Take it as a teaser or some sort of incentive for you to keep digging out the rest of its functionalities!

What I'd still love to add now is that 2 of a custom entity browser's most common use cases are:

  1. the one where it's used as a field widget, that would add on entity field values
     
  2. the one where it supports embedding editorial workflows

And now: how about putting what you've learned here into practice and creating your very first custom entity browser in Drupal 8?