Janez Urevc (@slashrsm)

• senior engineer and team lead at MD Systems
• Active member of Drupal community since 2009
• Lead of the D8 media initiative
• ex Examiner.com

Among top contributors

Have you ever...

...wanted to upload multiple images at once?

...wanted to select images from a media library?

...thought about combining both?

...tried to search for related content?

...needed to create a related entity without leaving the context?

We've got you covered!

What is entity browser?

General entity browsing, selecting and creating tool. Works with any entity type. Can work with fields, WYSIWYG, custom forms, ...

Architecture

Powerful, flexible, pluggable* and extensible.

Widget

Widget (cont'd)

Part that decides which entities are "selected" on a given step. Can be:

• a view - listing of entities*
• file uploader (HTML5*, DropzoneJS*, ...)
• remote resource browser (YouTube, Flickr, Getty images, ...)
• entity form*
• ...

Widget (cont'd)

interface WidgetInterface {

  public function getForm(array &$original_form, FormStateInterface $form_state, array $aditional_widget_parameters);

  public function validate(array &$form, FormStateInterface $form_state);

  // Call WidgetBase::selectEntities() to propagate selection to the other parts
  // of the entity browser (event).
  public function submit(array &$element, array &$form, FormStateInterface $form_state);

}
      

Widget selector

Widget selector (cont'd)

Part that defines how switching between widgets work. Can be:

• single widget - only one widget is used, no need to allow selection*
• dropdown*
• buttons*
• tabs*
• ...

Widget selector (cont'd)

interface WidgetSelectorInterface {

  public function getForm(array &$form, FormStateInterface &$form_state);

  public function setDefaultWidget($widget);

  public function validate(array &$form, FormStateInterface $form_state);

  // Return UUID of the selected widget.
  public function submit(array &$form, FormStateInterface $form_state);

}
      

Selection display

Selection display (cont'd)

Part that displays entities that are currently selected. Can be:

• no display - only one step of selection is possible, entities are propagated immediately*
• view display*
• rendered entity display*
• entity label*
• ...

Selection display (cont'd)

interface SelectionDisplayInterface {

  public function getForm(array &$original_form, FormStateInterface $form_state);

  public function validate(array &$form, FormStateInterface $form_state);

  // Call SelectionDisplayBase::selectionDone() to finish "session" and return
  // selected entities (event).
  public function submit(array &$form, FormStateInterface $form_state);

}
      

Display

Defines how entity browser appears in the broader context. Can be:

• iFrame*
• modal*
• standalone*
• ...

Display (cont'd)

interface DisplayInterface {

  // Some members ommitted for simplification ...
  public function displayEntityBrowser(FormStateInterface $form_state);

  public function selectionCompleted(array $entities);
  // ...

}
      

Where can I use Entity browser today?

As an entity reference field widget

As a file/image field widget

In Entity embed

In a custom form

// There is a form element. See \Drupal\entity_browser\Element\EntityBrowserElement
// for more info.
$form['entity_ids'] = [
  '#type' => 'entity_browser',
  '#entity_browser' => 'my_test_entity_browser',
  '#cardinality' => 5,
];
      

Example: referencing related content

Example: upload images and select from library

Inline entity form integration

Powerful entity reference widget, that allows creation/edit of referenced entities inline.

You can use Entity browser with its "Use existing" feature.