| Drupal

How to Embed Drupal Entities with the Entity Browser Module

In this blog post, I'm going to show you to enable Drupal users to select entities using the "Entity Browser" module.

This tutorial was requested by an OSTraining customer who is building a book review site. The customer wanted to use Entity Browser so that they can create this feature:

  • The site has two content types: Books and Book Reviews.
  • When users create a new Book Review, they can use a view to search for and select the book they're reviewing. For example, if they're reviewing "War and Peace", they can search for the exisiting "War and Peace" node.
  • When the book review is published, the selected node will be embedded inside the book review.

This customer request can be achieved with the help of the Entity Browser module. This module provides a browser that Drupal users can use to embed nodes into other parts of their site.

This tutorial will take you through the site-building exercise and show you how to use the Entity Browser module.


Step #1. Install the required modules

In order to use Entity Browser, you have to install the following modules: Entity Browser and Chaos Tools.

Use your preferred method to download and install these modules. I’m using Composer:

composer install drupal/entity_browser
composer install drupal/ctools

Allow Your Users to Choose Drupal Entities with the Entity Browser Module

This will place the modules in your Drupal installation. After that click Extend, search for both modules, enable them and click Install.


Step #2. Create the Taxonomy terms

In this example, books are categorized by their genre, so we will need a vocabulary called "Book genre".

  • Click Structure > Taxonomy > Add vocabulary.
  • Give the vocabulary a proper name and description.
  • Click Save.

  • On the List tab, click Add term.

Add the following terms:

  • Adventure
  • Cookbook
  • Drama
  • Fantasy
  • Horror


Step #3. Create the Book content type

Next we'll create the content type for our books. We'll use the Book Genre taxonomy that we created in the previous step.

  • Click Structure > Content types > Add content type.
  • Create a content type called Book and add these fields with their default settings:

table

  • Click Add field once again.
  • In the dropdown list under Reference, select Taxonomy term and give it a proper label.
  • Click Save and continue.

  • Leave the Allowed number of values at 1 and click Save field settings
  • Scroll down to the bottom of the Edit screen and choose the vocabulary you want to reference in your content type. In this case: Book Genre
  • Click Save settings

  • Click the Manage form display tab.
  • Look for the Book genre field and change its widget to Check boxes / radio buttons.
  • Click Save.


Step #4. Create the Book content

Now it’s time to create 5 to 10 books and assign each one of them to a particular genre.

  • Click Content > Add content > Book.


Step #5. Create a View

After creating some sample content, you are ready now to create the view. This view will be displayed on the entity browser so you can pick a book while you are creating a book review.

  • Click Structure > Views > Add view.
  • Create a view with the title Available Books.
  • Show content of type Book.
  • Leave the Page and Block settings unchecked.
  • Click Save and edit.

  • Click the Add button under the DISPLAYS section.
  • Select Entity Browser.

  • Click Rearrange besides the SORT criteria and remove the Content: authored on desc criterion.
  • Click Apply.
  • Click ADD besides the FILTER criteria and select the Book genre field.
  • Click Add and configure filter criteria.

  • Make sure the Book genre Vocabulary is selected.
  • Change the Selection type to Dropdown.
  • Click Apply and continue.

  • Check Expose this filter to visitors, to allow them to change it.
  • Make sure the Operator is selected as Is one of.
  • Click Apply.

  • Add the Title field to the SORT criteria.
  • Leave the default configuration Sort ascending and click Apply.

This will present the books in the view in alphabetical order. You have to insert some more fields to be displayed on the view. At the moment, there is only the node title available.

  • Click the Add button on the Fields Section.
  • Look for the book cover field and click Add and configure fields.

  • Select Image style (Thumbnail 100x100) and click Apply.
  • Click Add once again in order to add the Entity browser bulk select form field.
  • Click Add and configure fields.

  • Click Apply.

The use of this field is mandatory if you want to use Entity Browser, so pay special attention to this.

  • Change the format of the view, for example to Grid.
  • Click Apply twice.

The configuration of the view in Views UI should look like the image below. Click Save in order to save the View.


Step #6. Configure the Entity Browser module

In this step, we'll choose the setting the key module in this tutorial: Entity Browser.

  • Click Configuration > Entity browsers

  • Click Add Entity browser.
  • Give it a proper label, for example, Book browser.
  • As display plugin select iFrame.
  • Click Next.

  • Check Auto open Entity browser and click Next.

  • Click Next two more times until you land at the Widgets configuration page.
  • Click the dropdown list in order to select the View widget plugin.
  • Change the label of the widget, for example: “Choose a book”.
  • Select the view you configured in the Step #5.
  • Click Finish.


Step #7. Create the Book review content type

Our site is nearly complete. Before we finish, we do need to create the content type that book reviewers can use:

  • Click Structure > Content types > Add content type.
  • Name this content type Book review.
  • Add a new field, from the Reference section choose Content.
  • Give this field a proper label, for example, The book.
  • Click Save and continue.
  • In the Type of item to reference option select Content.
  • Click Save field settings.

  • Click Save settings.
  • Click the Manage form display tab for this content type.
  • Locate the reference field and change its widget to Entity browser.
  • Click the cogwheel on the right and select Book browser (or whatever you called the browser you just created in Step #6.
  • Click Update.
  • Click Save.

Notice that you also have the option to display only the Entity label or the Full rendered entity. You could use view modes (e.g. Teaser) to present the entity on this new Book review content type.


Step #8. Create the book reviews

Now our site is nearly ready to use. Let's create a book review and see if everything is working correctly.

  • Click Content > Add content > Book review.
  • Give this node a proper title and body texts.
  • Scroll further down and you will find a collapsed section called THE BOOK (that is the name of the field).
  • Click this field and you will see the Entity Browser where you can select the Book you are referencing in this Book review.
  • Furthermore, there is an exposed filter on top so you can select books only pertaining to one genre.
  • Select a genre and click Apply.

The browser will show you only books within this genre.

  • Select a book and click Select entities.

  • After embedding the entity click Save and you will see the referenced Book entity on the Book review node.

Final result

This tutorial has demonstrated the power of the "Entity Browser" module for Drupal 8. I hope you liked it. Thanks for reading!


About the author

Jorge lived in Ecuador and Germany. Now he is back to his homeland Colombia. He spends his time translating from English and German to Spanish. He enjoys playing with Drupal and other Open Source Content Management Systems and technologies.