One of the key advantages of custom search is to do more than provide a single, global search box. Filtering allows you to divide results to a subset.
In this tutorial, we'll:
- Describe how to configure filtering through use of a taxonomy field
- Explain the disadvantages of this approach, including how it relies on Views to reduce results rather than Solr
Filtering results allows us to divide up the result set along one or more dimensions. It’s built in to Search API, but often we need a slightly different approach. Drill-down search or faceted searching allows us to constrain (rather than divide) our result set to one or more dimensions. The contributed Facets module provides this functionality.
In this tutorial, we'll:
- Describe how facets constrains results to preconfigured dimensions
- Demonstrate how use of a facet also constrains the possible selections for other facets
- List the steps for installing Facets module
- Describe the field types best used for creating facets
By the end of this tutorial you should be able to explain what facets are and how they work in the context of searching a Drupal site's content.
Creating a facet in Drupal is rather different from using Facets API in Drupal 7. In the new module, we first create a search view, and then configure facets against target fields in the index. Once created, we must configure the facet UI to appear on target pages using the Blocks UI.
In this tutorial, we'll:
- List the steps necessary to create a facet using a non-reference field (i.e. boolean, or text list)
- Explain why facets are displayed using blocks
- Describe the various facet display modes and uses for each
By the end of this tutorial you should be able to add a facet based on a text list field and allow users to filter search results using the values in the list field.
A powerful facet combination is to create a search Facet on a taxonomy field. This brings several advantages to how your search can be configured and displayed.
In this tutorial, we'll:
- Describe the additional complexities for using a reference field for a facet
- Show how to use taxonomy weights to control facet option order
By the end of this tutorial you should be able to add a facet that allows users to filter search result based on taxonomy terms.
In this gentle introduction to testing, we'll walk through what testing is and why it's important to your project. Then we'll define some terms you'll be likely to see while working with tests so that we're all on the same page. After reading through this tutorial you'll understand enough of the basic vocabulary to get started running (and eventually writing) tests for your Drupal site.
When running tests with PHPUnit we need to specify a phpunit.xml file that contains the configuration that we want to use. Often times (and in much of the existing documentation) the recommendation is to copy the core/phpunit.xml.dist file to core/phpunit.xml and make your changes there. And this works fine, until something like a composer install or composer update ends up deleting your modified file. Instead, you should copy the file to a different location in your project and commit it to your version control repository.
In this tutorial we'll:
- Learn how to move, and modify, the phpunit.xml.dist file provided by Drupal core
- Understand the benefits of doing so
- Demonstrate how to run
phpunitwith an alternative configuration file
By the end of this tutorial you should be able to commit your phpunit.xml configuration file to your project's Git repository and ensure it doesn't get accidentally deleted.
This tutorial will clarify some basic ideas about software testing. We'll give some strategies for testing and illustrate types of tests and when and why you'd use them. This document is written with Drupal in mind, but the concepts apply for other development environments you'll encounter as well. The tools will be different, but the ideas apply universally. By the end of this tutorial, you should understand what testing is for and how different types of tests support different purposes and outcomes.
Drupal Console
FreeThe Drupal Console is a suite of tools run from a command line interface (CLI) to generate boilerplate code and interact with a Drupal installation.
Note: This project is no longer actively maintained. See the Drush topic for alternative solutions.
To follow along with our Drupal Views tutorials, set up a Drupal site loaded with our 4 custom views and baseball stats content that will make querying in Views a bit more interesting and meaningful.
By the end of this tutorial, you should choose a solution and follow the instructions for creating a Drupal site loaded with our starting point content and views.
In a monolithic architecture (non-decoupled) there is an implicit proof that the user in the frontend is the same one in the backend. This empowers the frontend to offload all the authentication and authorization to the backend, typically using a session cookie. In a decoupled architecture, there will be multiple consumers, and some of them will not support using cookies. There are several alternatives to session cookies to authenticate our requests in a decoupled project.
In this tutorial we will:
- Learn about authorization versus authentication
- The impact on a decoupled project of having logged-in users
- Learn about the available options for authentication when using a Drupal backend.
By the end of this tutorial, you should be able to explain the difference between authentication and authorization and know how to get started implementing both in a Drupal-backed web services API.
JavaScript applications are the most common type of consumers. They are commonly used to create a website that runs in a web browser. Running decoupled applications in the browser will involve Cross-Origin Resource Sharing (CORS), which requires some setup on the Drupal side in order to work.
In this tutorial we'll:
- Learn about what CORS is and when/why we need to care about it
- Configure Drupal to return an appropriate CORS header, enabling browser-based consumers access to our API
By the end of this tutorial you will have a better understanding of CORS, and how to configure Drupal to serve an API that works with CORS.
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
filterquery 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.