 Good afternoon, everyone. Welcome to the session about the entity browser module. I hope that's the topic you are here to hear about. I expect that by the end of the session, you are able to understand a little bit more about what the module does, and what's the good scenarios you can use it in, and how you can apply it to your Drupal project. Before starting, a little bit about who I am. My name is Marcos. I live in Barcelona in Spain. My day job is to do Drupal backend development. And I am, since a year ago, more or less, more involved with the media initiative. So I'm helping out with everything related to media handling in Drupal 8, mostly. If you want to contact me, I am always on IRC. I think that's probably the best channel. But you can also find me on Drupal.org or tweet me. By the way, these slides of the session are uploaded to the Drupal.com web page. If you want to follow along, just you can just go there and find these slides. And I also wanted, before proceeding, if you don't mind, have a little bit of understanding about the expectations you had for the session, so we can pace the presentation a little better. So if you don't mind raising your hands, if you have built a site in Drupal 7 so far, great. Have you built a site in Drupal 8? Great. Anyone knows what a field widget is and how to configure it? Good. Anyone tried the entity browser before? OK. Anyone has an entity browser in production? OK. Great. Thank you very much. Knowing more or less what you expect and what you've done so far allows me to go faster or slower in some situations. With this presentation today, I wanted to mainly cover three big ideas. The first one is let you know what the module is and what situations the module is good at solving. So you can decide when to use it or not. If you decide to use it, when you try to configure it, you are going to be asking a bunch of questions. And so I wanted to go a little bit deep on how the module is built so you understand what concepts are there and what you are configuring exactly. And at the end, we're going to do a demo and configure it together so you will see all the process of creating an entity browser from scratch. So apparently, we all have built sites. And we know that we, as developers or site builders, we tend to like when the content is structured because we know then what's going to happen. We don't like big chunks of HTML that appear on the page. We want to be able to have our fields, our formators, and our relationship within our content pieces to be as structured as possible. However, people who are going to use the CMS, they don't really care about how the architecture of the site is. They want something that looks good. They want something that allows them to create content in an easy way. And Drupal, out of the box, when we are creating structured content, the experience for the editor is not always the best one. And that's what we try to solve with entity browser. We try to meet common editorial needs your users have, making their lives easier. For example, I have listed here some examples of situations the editors face that Drupal, out of the box, doesn't provide a good solution for. For example, people want to upload images in bulk, all at once instead of uploading images one by one. People tend to, or no, they really want to be able to reuse an image that exists on the server. Out of the box, Drupal forces you to upload an image again and again if you are creating a different content with the same image. If we are reusing an image, we probably want to have a place where we can browse what's already on the server and look for something that we are interested in. We want that place to potentially be separate, depending if I am looking for my content or all content that is on the server. We want to relate content in a more intuitive way. You probably know already that if you are creating an entity reference field to relate to pieces of content, out of the box, Drupal needs the users to use an autocomplete field to search for the title of the node or for the label of the entity. And users don't necessarily know all the titles of all the nodes in the system. So that's a poor system to the editor. And editors may also want to be able to create the content that is being related on the fly. If you are creating a related article from the node page, you want to pick some articles that are referenced from this node. Maybe you realize that you want to create a new one on the fly and you don't want to go to another page, create a node, save, and then go back to the form and select it from the autocomplete widget. So these are just examples of some very common needs. And all of them can be solved with entity browser. I'm just going to show you some examples here. So this is the first example is a very basic usage of let's allow the user to upload several images at once in a more intuitive way if internet works. Yes. So I have a node form. And this is an image field, a multi-valued image field. And I am just selecting a bunch of images and dragging them. And I'm able to reorder them before passing them to the field. And when I click use selected, all these images are passed to the standard Drupal image field. Another example we can find is the same. But why not allow the users to be able to also select an image that is already present on the server? So we have exactly the same as we had before. We can select a bunch of images. But we can also allow the user to go to a media library, for example, and see what images are present on the server and allow them to select some of them in the same process. And then I can do this in a multi-step operation, meaning that I can upload again in the same selection process as many images as I want. And then when I click use selected, all these images are passed to the standard Drupal field. Another example I wanted to show you is that use case I just mentioned before. I have an article, a node type, that has references to other articles. In a standard entity reference field, and I don't want to use an autocomplete. So let's use a view for that. For example, this allows the user to browse for the node they are looking for. They can use an exposed filter in the view. And then they can select the content they are looking for. And then these two nodes are referenced from my entity reference field. Going a little bit further, let's do the same, but let's also allow the user to create a new node right there on the fly while they are still looking for the related content. So I select one from the library, and I can also open the node form right here and create a new node that doesn't exist. So when I save the node, now I have two nodes selected. I can even come back to my listing and select another one. And then all three nodes are referenced from my entity reference field. So these are very basic usages, but they are addressed very common needs. A more not so common need is why not go a little bit crazy and have the users pick the entities from a map. So in this case, I have an entity reference field, and the user is able to click on markers on the map. They are selecting the content that's going to be referenced from this entity reference field. So all this is powered by entity browser. These are examples of applications that we can build with entity browser. This is available right now. There is one catch. There's always a but. Entity browser itself, the module itself, is not something that you just install and it builds all this out of the box. It's not plug and play, let's say. There is a good reason for that. It's true that if you are configuring the entity browser from scratch, you are going to be asking a bunch of questions. Some of them are not very clear. If you are not familiar with the terminology. But that happens because the entity browser module doesn't assume your use case. Doesn't take any assumptions on what you are doing with entity browser. It can work with any entity in Drupal. You can use it for users, for comments, for taxonomy terms, for nodes, for media entities. You can use it in any context. We have just seen some examples of browsers being used in field widgets, meaning that in entity fields, I will use the entity browser to get the values for those fields. But that's not the only context where the browser can be used. The same browser can be used to embed an entity into another piece of content inside a WYSIWYG area, for example. You could use the same browser in your own custom form. There's a form element that is created that will render the browser for you. So it's very abstract. It makes it very flexible and very powerful because of that. But of course, it has some concept that you need to understand in order to configure it from scratch. It's also true that some usability issues on the entity browser UI have already been identified. Some labels are being improved and some processes are being improved. There are issues in the issue queue for many of them. If you find some new ones, please file an issue on the issue queue. That it will mean that it's just a matter of resources and time for someone to get on them at them and finally get them fixed. But the good news is that you don't really need to create your entity browser from scratch. There are some country modules that do assume a specific use case and you can just use them as an example or just as your final solution. For example, the first two videos I showed uploading images, they are based on file entity browser, which is a module that ships with some default configuration for the entity browser. And you probably want to use it if you only want to use and work with images or files in your system. This is a browser configured to work with files. Similarly, there is a browser configured to work with nodes. If you only want to provide a way of selecting and manipulating nodes, then you can use the content browser module. And similarly, the media entity browser module, which is thought to be working with media entities. Those two following ones, entity browser enhanced and this leak browser, they are examples of how we can enhance the usability of the browsers with CSS and JavaScript. They don't provide browsers by default, but they do improve the user experience. And if you also want to try Thunder and Lightning, you'll probably know them, but if you don't, they are full Drupal distributions, they are not modules, but they do use a lot entity browser in their way of work. So you can also try them to see entity browser in action without having to configure it yourself. But if you do want to configure one, and I think it's a good knowledge to have, it's, I think it's interesting, it's important to understand the architecture, the concepts there are on the base of the entity browser, and that's why I wanted to go a little bit deep in some of them. The terminology sometimes can get a little bit abstract and a little bit, what is this related to? So let's set some ground rules here. So the module, the country module entity browser is, we could see it as a framework that will allow you to create a tool for the end user, and this tool, we're gonna call it the browser to be a little bit simpler. This tool, this browser, then will allow the end user to select, to browse, to create, and relate any Drupal entity in different contexts. The browser itself is a config entity, I don't know if you're familiar with this concept, you could see it as a view, for example, a view is also a config entity, meaning that there is a UI that allows you to create a view, but you don't really need the view's UI to use a view. So in the same sense, the entity browser is a configuration entity that lives in your Drupal site in order to create it, you can either use the UI for that, or you can import it from a YAML file or from any other module that provides the browser for you. If you go over the UI, and if you try to configure it yourself, as I said, you're gonna be asked a bunch of questions. Some of these questions, or most of these questions will relate to one of these four concepts here, which are the four main components of the entity browser. And let's examine a little bit in detail, each of them, just for us to understand what's going to happen next when we go to the demo. When we speak about the widget, we are speaking about the main action that's taking place inside the browser. In this case, I have a bulk upload type of widget. In this other case, I have a view widget. So the widget is the piece of the browser that deals with the main operation of selecting entities. The entity browser itself just comes just with the two widget types, widget plugins, a file upload and a view, but the entity browser module integrates with many other country-controlled modules, mainly from the media initiative, but not necessarily. Actually, all these concepts are plugins. If you are familiar with the concept of plugins, it means that you can easily extend and override any of these components, just providing a new plugin. And other modules do provide new widgets for the browser. If you use the Dropsun.js module, you will have then available a bulk upload area as we saw in the video. If you use the media entity image module, then it will have available a new widget which will create a media entity for each image uploaded. And if you will install the inline entity form module, then you also have a new widget that will allow you to create what we saw in the video, the entity form as one of the widgets inside the browser. We're gonna see that in a minute. The second concept you're gonna be presented is the widget selector. As we saw, we can have multiple widgets in the same browser. If you have multiple widgets, you have to decide how these widgets are going to be presented to your user. And the widget selector plugin is the configuration part of the browser that's responsible for that. In this picture, we see that two widgets can be selected using a tabs layout of links. The entity browser module comes with three types of widget selectors. Single widget, you will use when you want to have just one widget, obviously. The tabs selector is the one we saw just saw in the picture. And the dropdown is when you want to have the different widgets in a dropdown element. The third concept, which is probably the most important and a little bit tricky to get, is what's called the selection display plugin. You're gonna be asked a bunch of questions about what your selection display going to look like. And you can think of it like this temporary zone where you're providing visual feedback for the user while the operation is still in place. So we saw in the video that the user could switch between tabs and keep selecting or creating. And as the process continues, you'll see what's been selected in this temporary area over here, that's the selection display because it displays your ongoing selection. Out of the box, the entity browser provides you with three options for the selection display plugin. No display means I don't want to provide visual feedback during the selection process. Multi-step is the one we just saw. It's the most common one. And it means that the selection is a multi-step operation and I want to provide this temporary zone in all the steps. And you could also use a view to be used as a temporary zone for your selection. It's true that it's a little bit rough on the edges and the configuration of this selection display if you use a view has some guts. But if you're in doubt here, you probably want to use the multi-step selection which is the most common and the most obvious option here. And the last one is probably the easiest one. You are going to present your browser either in a model window or embedded into the main content in an iFrame. So the display plugin decides how the browser is going to be presented to the user and it comes with iFrame, display, model, display, and also there's a third option, a standalone. That's not really used in any real world scenario. It exists to allow custom integration where you probably want to have the entity browser with a custom URL to be attacked from an external system. For example, that's the hypothetical case where you would want to use the standalone. It's not really used a lot. Okay, so that's about the theory. I wanted to show you. Let's go over some configuration steps to replicate what we saw on some of the videos from the beginning. The first scenario we want to replicate is the one for the first video, the simplest one. I just want a browser that will allow bulk uploading of images for an image field. Let's assume some things at the beginning. So let's create a browser that will be shown inside the node form. I will use it in a field widget, in an image field. I don't want it to be a pop-up, a model window, so I want it to be embedded, so I want to select the iFrame display. I only want the upload widget, so I will use the single widget. I want the user to be able to do multiple uploads if they want, so I will select the multi-step selection display, and I will also use the dropson.js, big square drop zone because it's more user-friendly. So the first thing we need to do is to install these modules, entity browser. In our case, we want this dropson zone, so we want the dropson.js country module as well, the sub module that provides the integration between the two, and C tools. C tools is not really a requirement for entity browser to work, but if you want to create your entity browser and configure it using the UI, the UI depends on C tools, so you will need to install it. Let's go over the configuration and see what we have after doing all that. So this is my Drupal site. I have only installed the modules I showed before. As soon as we install entity browser, we have a new option under configuration, content authoring entity browsers. This is the place where all my browsers will live, and as you can imagine, the first thing to do is click on create entity browser. In our case, the browser is going to be used to bulk upload images, so I will call it bulk upload, for example. As I mentioned earlier, you have to decide the main plugins you are going to use. In our case, we are going to use the iframe display plugin. We don't want multiple widgets, so we are going to select the single widget, and we want to select the multi-step selection display. This, if you haven't used this form before, this is a multi-step form, meaning that whatever you decide here on this first page will define the settings for the other steps, so the questions that this UI is going to ask me is going to depend on what I chose before, for example. Here it's asking me about the, some questions about the iframe, because I selected the iframe display in the first step. For now, the defaults are okay. Some plugins may not have any configuration settings, so you just have to click next. In our case, we're gonna deal with images, so our selection display plugin needs to know what type of entity it's supposed to show, so I am going to say it's a file entity, and in that temporary zone, I want to have thumbnails of those images. And here's the last step, that's the most important part. It's where we have to tell the browser which widgets we are going to use. In our case, the one we want is the drops on JS. Bulk uploader, can tweak a little bit, some labels, and we click finish. So as soon as I finish all the steps of this multi-step form, I have a browser created. This is the name of my browser. Right now it doesn't do anything, because I'm not using it anywhere. It's like a view, I just created a view. Now I just created a browser, so I have to use it somewhere. Let's use it in our article content type that has an image field. So here I have a standard image field with multiple values. Most of you said you are familiar with widgets, so you probably know that I want to change the widget for this field and I don't want to use the standard image one. I want to use our own entity browser. So for this field, I am going to change and instead of using the image upload, I'm going to use the entity browser. Here in the configuration options, I have to choose which browser I want to use in this widget. I only have one created, so I only have one option here. I'm going to leave all the defaults selected just for us to see what it gives us out of the box. And that's it. Now I have my node type, the article node type with an image field that uses the entity browser as a widget. Let's see what that gives us. So here I have my image field. Here I have the link to open the browser. If I click here, then I have what we saw on the other examples. Again, this is the same as we saw before. Can select some of them. I can select the images. And when I am happy with the selection, I could do the operation again because it's a multi-step one, but in our case, let's just send what we selected to the field. You may have noticed that there are a lot of clicks here involved. I had to click here to open the field set. I had to click here to open the browser. Inside the browser, I had to click, select, I don't know, a couple of times. Let's try to improve that and make the process a little bit easier. There are some configuration options in the browser that define that. So I can come here, edit my browser. For example, the display, which is going to show the iframe, we may want to have it open by default. I don't really need that link that says, select entities and then shows the iframe. That's really redundant. So I want to auto open the browser. Let's also say that for this widget, it has an option of automatically submitting the selection to the browser. So this is the widget and this is the browser. I don't really need an intermediate step between them. So I am going to, whatever is dropped to that zone, I am going to pass to the browser automatically. So that's going to skip us one click. And also, we can go to the field widget and say that I want it open by default. For the field set itself, I don't want it collapsed. I want it open. So that's what this setting is for. So the first field set in the node form that deals with this field, I want it open by default. I'm sorry, it's a lot of terminology. I hope you're getting it. But it's easier when we see what's happening here. So that's our node form. I just reloaded. And as you see, this is open by default. The widget's here. And when I drag some images, they are already passed to the browser. And I just have to click once and they are passed to the field. So that's much better and that improves a lot the user experience. I also wanted to show you a second example, which addresses that use case we mentioned before when we have an article that relates to other articles and we don't want to use an autocomplete field for that. Let's see how we can improve that. I want to exactly create what I showed on the, I don't know, second or third video where we saw a possibility of having a view and also a form to create a node on the fly. In our case, I am going to select a model because now I think it makes more sense to have it in a model window just for the sake of the example. As I said, I want two operations to be possible. I want to be able to select from a view and I want to be able to create a new node on the fly. And I want these two options to be available as links inside a tab. So let's go and do that. Again, configuration, content authoring, entity browsers. Create an entity browser. Let's call this one node selector. I am going to leave the model display. I am going to leave the tabs and I just want to change here to multi-step. I don't want to auto open right now because it would be kind of weird to have the model opening by default. Again, the selection display needs to understand what type of entity is going to show. In this case, it's okay, it's a node. Here, I am going to select the entity label for this temporary zone. But in a real world, you probably want to use a view mode. I assume we are all more or less familiar with the concept of view mode. So we define a view mode and then you can select here that you want to render the entity using that view mode. It will probably look nicer or better than just a label. In this case, let's just go with the label. And here is the place where we have to choose which widget we want to use. And we just realized then that the thing we want to use here is not created yet. We want, we said we want to use a view here and we can select a view here, but it will not let me proceed because I don't have any view created yet for this specific need. And let's go and do that, let's go and create a view that I can use here. Actually, I'm going to use a view that's existing here just to go quicker. But we are probably all familiar with views. You can use any view in this context. There is just, well, there are two main fundamental configuration options you have to do in your view for it to be used inside the browser, otherwise it won't work. So in order for the view to work inside the browser, it has to have an entity browser display and it has to have this field. So the display is just as you have the block or the page display types, you have an entity browser display type. So you have to set it to use the entity browser display type and you can have as many fields as you want, you can have it a table, you can have it as a grid, as we saw, you can have it as a map as well. But the important thing is that one of the fields of your view needs to be this, you can search for bulk, it needs to be this entity browser bulk select form. In our case, we already have it here. So this is the field that's going to include the check box for each result of the view. So if you don't have a check box, you're not going to be able to select it. All the rest is just a normal view. I have here some exposed filters and some sorting criteria or something like that. But all the rest is pretty much standard. Once we have the view created, then we can come back here and say, hey, let's use a view as a widget. And I am going to label this browse nodes or something like that. And you see that I only have one view in my system with entity browser display. So that's why I only have one option here. And I am going to, no, I'm not going to select this because I want to show what this changes. But we said we want two operations to be possible. One is selecting from a view. And the second one is to create an entity on the fly. And for that, we want to use the entity form widget. We can call this create new nodes. In order to show the form here, we need to define what type of entity we are going to create. In our case, it is a content. And I am going to restrict for the bundle, for the article bundle, which is what my related article is going to use. And that's it. So I have a new browser, the node selector one. Let's use it in our field. So I am going to change the form display of the article node type. Again, it's the same operation we did before. Before, we changed the image field. Now I am going to change a field called related articles, which is just a standard entity reference field. As you see, the standard widget is an autocomplete field. And I don't want to use that. I want to use the entity browser widget. Now we have two browsers. We're going to select the correct one. And all the rest is OK as it is. And that's it. These were the only two or three steps needed to configure that widget. If we create an article now, we see here our field. And we see here our empty view, because I don't have any content on my site. Let's create some content. I'm just bulk generating some content with the develop generate module. This is not part of the demo, but that's just to have something to show in the view. OK, so we should have now. OK, so now we have nodes here that appear. And I can filter. I don't know. I can use the exposed filters. Then I can create a node, use selected. So in my related articles field, I now have two nodes that were selected in a more user friendly way than just an autocomplete field. And it didn't really take us too long to configure that. So as you can see, the possibilities are really, really big. You can extend and improve that. This basic solution we just built can be extended in a very, very powerful way. Just wanted to give you a little bit of overview. If you want to really get more information about the entity browser, there are some links here on the slides. You can check on the session page. There is an article about it, and there is a handbook page that goes into some of the details we saw here. The entity browser is part of the media handling effort in Drupal 8. There is an initiative page where you can find some more information about all the other modules that are part of that initiative. As always with Drupal, if something's not working, just ask for help, create an issue in the issue queue, or come and help. There is a specific channel for media in IRC, Drupal-media. And once a week, we try to be there together at the same time at 2 PM UTC to talk about media and the roadmap and where things head to. If you want to participate, you are more than welcome. Tomorrow is the, you are probably sick of hearing this, but that tomorrow is the contribution day. Don't miss it. There are opportunities for every level of contribution. And don't forget, go into the session page and evaluate in the session. That's a really valuable feedback from the attendees. And thank you for coming. We do have some minutes for questions. I don't know if anyone wants to comment on something specific or ask for a specific. First of all, very good session. Thank you. I was just wondering if you could say a bit about using the entity browser for inline media and like vis-a-vis using CK to direct images and so on. Yeah, so as I said before, the entity browser is one piece of an ecosystem of modules that we call the media ecosystem in Drupal 8. For those of you who are familiar with Drupal 7, what was in Drupal 7 media module now has been split into several different modules in Drupal 8, another module that is part of the same initiative and works very well together with entity browser. It's called entity embed. So the entity embed module is meant to embed entities in WYSIWYG areas. So it works, again, is very abstract. It works with any entity. And it's fully compatible with entity browser. So for example, what we just created here, you could use in your WYSIWYG to embed nodes, to create nodes, and then embed them, or images, or any entity. So it's fully compatible. Anything else? OK, then. So enjoy your break and see you at the closing session. Thank you. It's probably easier if you don't mind.