When using the Drupal Media Library to browse for available Media entities to attach to your content, the interface that you see inside the modal window is created using Views. This means you can change it for your specific use-case. This is most useful when you want to expose filters for custom fields to allow users to more easily locate content in your library. As your library of media grows, you can create powerful application-specific ways for content authors to segment the list and find their assets.
In this tutorial we'll:
- Learn how to edit the Views used by the Drupal Media Library browser
- Add a new exposed filter for the custom tags field on some media entities
- Demonstrate how this change affects the user interface for locating and selecting media
By the end of this tutorial you should be able to customize the View used by the Media Library to add new filters and make other use-case specific changes.
Media Source plugins in Drupal have a powerful feature, called field mapping, that allows an administrator to configure a Media entity type to automatically populate the value of custom fields based on metadata retrieved from the source content. For example, you can add a creator field to the Remote Video Media type, which can use YouTube as a source. When a content author adds a new Remote Video entity they can provide a URL for the YouTube video. Then the source plugin can extract the creator's name from the YouTube API and use that data to populate a custom field. This saves the content author from having to do that work themselves.
In this tutorial we'll learn:
- How to discover what source metadata is available
- How to configure a Drupal Media type to automatically populate custom fields
By the end of this tutorial you should be able to add a custom field to a Media type on your Drupal site and automatically populate it with data retrieved from the source content.
One of the most powerful features of Drupal's Media Library is that it enables content authors to re-use media entities. Have a favorite image that you like to use with all blog posts about a specific topic? Or a default icon you want to use for a tutorial unless an alternative is provided? The Media Library can accommodate this without requiring you to keep a copy of the image locally and then attach it to every node where it's needed.
This can lead to a potential issue when an editor deletes an image, thinking they've also deleted all the content that used it. If they missed a post referencing the now deleted image, what happens when there is no image to show?
The contributed Entity Usage module provides a mechanism for tracking relationships between entities. This is essential functionality when working with a library of reusable media entities because it helps ensure that media entities attached to content are not deleted.
In this tutorial we'll:
- Discuss the use case for the Entity Usage module
- Learn how to configure Entity Usage to keep track of relationships between media entities and nodes that reference them
- Prevent media items from being deleted if they are in use somewhere on the site
By the end of this tutorial you should be able to explain what the Entity Usage module does, and how to use it to solve common problems related to deleting items from a large Media library.
A commonly asked question is, "How do you add images to the body of a content item in Drupal?" You can allow users to embed images, videos, or any other media into a field configured with a WYSIWYG editor, such as CKEditor. In this tutorial, we’ll show you how to enable Drupal’s Insert Media button for CKEditor, and configure the corresponding text format so that it can render embedded Media entities.
Content authors can then use the Media Library to select images (or other media) to embed into the page.
In this tutorial we'll:
- Learn how to enable the Insert Media button for CKEditor
- Demonstrate how to insert media into the body of a content item (or any other field configured to use CKEditor)
By the end of this tutorial you should know how to configure Drupal to allow content authors to embed images in content items.
Drupal's media management tools, the Media and Media Library modules, provide content authors with drag-and-drop media and asset handling, full WYSIWYG editor integration, and a library of reusable media assets. There's minimal configuration required to get started, but full control via Drupal's standard Entity and Field systems for those who need it.
In this tutorial we'll:
- Provide an introduction to the media system in Drupal and its use-cases
- Explain the Drupal core features that the Media system is built on
- Link to other tutorials that will go into much more depth on these topics
By the end of this tutorial you should know what role the Media and Media Library core modules fill and know whether or not you'll want to make use of them on your project.
Media entities are standard Drupal fieldable content entities. For the most part, they function, and are managed, in the same way as Nodes. So if you've previously created content in Drupal, much of working with Media entities should be familiar -- with some notable exceptions related to the connections between Media types and the media resources they represent.
In this tutorial we'll:
- Get an overview of Media entities, Media types, and Media fields in Drupal
- Point to other tutorials that go into more depth on individual topics
- Learn some basic terminology and concepts related to the Media system in Drupal
By the end of this tutorial you'll have an overview of the pieces that make up the Media system in Drupal core.
When you are implementing an HTTP API for a decoupled project, one of the critical, but often overlooked, aspects is the API documentation. Documenting your API will allow front-end developers (and you six months from now) to learn how to use that particular API.
In Drupal, there are several modules that can read your site configuration and generate documentation for you automatically.
In this tutorial we're going to:
- Learn about the importance of good documentation.
- Decide whether or not to use an existing specification for our API such as JSON:API or GraphQL.
- Review options for automatically generating documentation.
By the end of this tutorial you'll be able to decide whether or not using an existing documentation specification is a good fit for your project, and choose an option based on those available for use with Drupal.
JSON:API includes a way to request a list of entities of a given resource from the server. Collections are the best way to find content based on filters, and to build listings into the consumers. Moreover, collections can be combined with all the options you can apply to a single resource, like sparse fieldsets and includes.
In this tutorial we'll:
- Learn about what collections are in JSON:API
- Learn how to request, sort, and paginate lists of content
By the end of this tutorial you should know how to retrieve a list of resources from the JSON:API server, and how to optionally sort and paginate the items in the list.
Often, web services require the user to create content. Votes on content, ratings, comments, and user-submitted stories are good examples of this. The JSON:API module supports the creation of entities by sending data in POST requests.
In this tutorial we will:
- Add an appropriate set of HTTP headers to a request that generates a new entity
- Construct a JSON object for the entity we want to create
- Issue a POST request that creates a new article node in Drupal
By the end of this tutorial you should be able to create a POST request that creates a new entity of any type via the JSON:API.
Sometimes unexpected things happen and Drupal needs to generate an error. The JSON:API specification describes how the server should return those errors. Understanding what to expect allows consumers to plan for errors and react gracefully.
In this tutorial we will:
- Discuss how HTTP errors are used in conjunction with JSON:API
- Learn about how JSON:API embeds information about the error encountered into the response object
By the end of this tutorial, you should have a basic understanding of the types of errors you can expect to receive when making JSON:API requests and what you can do to handle them.
Collections are a very powerful feature because they allow us to access multiple items at the same time. However, in many situations we do not want to access all the entities of a given type, but only the ones that meet some specific criteria. In order to reduce the set of entities in the collection to the ones we care about, we use filters.
In this tutorial we will:
- Look at the
filter
query string parameter and how it can be used with JSON:API collections - Learn how to use filters in combination with the JSON:API module for Drupal to reduce the list of entities in a collection
By the end of this tutorial you should be able to request a list of entities in the form of a JSON:API collection and filter that list to include only the entities that match a specific set of requirements.
Embedding resources at the consumer's demand is one of the crucial features of a modern API. We mentioned in Modern Web Services with JSON:API and GraphQL that multiple round trips to the server is harmful for performance. This issue can be overcome by making a request that embeds any required related resources into the response for the resource we're retrieving.
In this tutorial, we'll learn how to use JSON:API's include
parameter to embed resources in a response.
By the end of this tutorial, you should be able to make a single request that retrieves multiple embeded resources in order to improve the performance of your application when interacting with a JSON:API server.
The JSON:API module is our recommended starting point for creating REST APIs with Drupal. JSON:API module is now part of Drupal core as of 8.7, so installing the module no longer requires a separate download step.
In this tutorial we'll:
- Walk through installing the JSON:API module for Drupal
- Look at what you get out of the box with the JSON:API module
By the end of this tutorial you should be able to install the JSON:API module, and know what tools it provides you with.
Includes and filters are really powerful features. When combined together you can achieve almost any query your consumer application needs. Fancy filters we mentioned in a previous tutorial allow us to filter a collection based on fields of related entities, in addition to the fields directly under that entity.
In this tutorial we will:
- Learn about filtering based on data in related resources
- Filter based on multiple conditions and multi-value fields
- Demonstrate how to filter a collection of articles based on author or tags
By the end of this tutorial you should be able to use nested filters in conjunction with relationships to further refine the list of content returned in a JSON:API collection.
Drupal allows for a rich data model where entity reference fields can be used to relate any number of different items together in different ways. The data models that you can build with Drupal are often prolific in relationships, which means we need a way to handle these in our API. While Drupal treats a field with a string, and a field with an entity reference the same, JSON:API distinguishes between attributes and relationships.
In this tutorial we'll:
- Look at how JSON:API represents relationships between two or more resources
- How to distinguish between an attribute and a relationship in a response object
- Learn about what information is available for each relationship and how we can use it
By the end of this tutorial, you should have a better understanding of how the JSON:API specification represents relationships modeled using Drupal entity reference fields.
Occasionally we need to remove entities from the backend using the API. REST APIs, and in particular JSON:API, use the HTTP DELETE method to accomplish this.
In this tutorial we'll create a request for deleting a single entity. By the end of this tutorial you should be able to issue requests that can delete any entity via JSON:API.
Being able to retrieve resources from an API is a fundamental first step.
In this tutorial we will learn how to:
- Issue an HTTP request to extract information about a node from the JSON:API server
- Examine the response from the server
By the end of this tutorial you should know how to use an HTTP Get request to return a resource from the JSON:API server, and know what the default response for the resource will contain.
When you enable the JSON:API module you're significantly increasing the attack surface of your application. So it's a good idea to make sure that you understand the implications of doing so, and how to mitigate potential security issues. In most cases it doesn't require much work to do, but it's worth taking the time to make sure you've done it right.
In this tutorial we'll learn:
- What JSON:API already does to keep you secure
- How to protect against common attacks
- How to limit access to resources exposed by JSON:API
By the end of this tutorial you should know what to look for when auditing your JSON:API configuration to help prevent against common attacks.
By default, the JSON:API returns all the available data for an object in its response. Using JSON:API sparse fieldsets you can increase the performance of your consumer application by reducing the fields in the returned response object to just those that you need.
In this tutorial, we will learn how to reduce the output to get exactly the information that we need from the API.
This is one of the most important features of modern APIs like JSON:API.
By the end of this tutorial, you'll know what sparse fieldsets are, the role they fulfill, and how to use them when requesting data from a JSON:API server.
Whenever we need our consumer application to change the contents of an entity we will need to issue a PATCH request. The JSON:API module will process that request and update the entity with the provided values.
In this tutorial, we'll:
- Define the appropriate HTTP headers for a PATCH request
- Construct the JSON object used to update an entity
- Issue a PATCH request that will update an entity in our Drupal backend
By the end of this tutorial, you should know how to update content via the JSON:API.