Views field handler plugins handle retrieving and displaying data within a view. The Drupal core Views module provides field plugins for all the core field types, and these work well for many situations where you need to describe custom data sets to Views. For situations where an existing plugin doesn't match your requirements, you can define a custom field handler plugin and alter both the query that gets executed and the rendered output of the data.
This is common for contributed modules that define new field types, or any module using hook_views_data()
to define a dataset to Views where the data contained in a database column may need special handling in order to be displayed as part of a view.
In this tutorial we'll:
- Implement a custom Views field handler plugin
- Extend the default date field plugin and modify the way that it displays a timestamp so that instead of a specific date we get a relative value
By the end of this tutorial you should know how to define a custom field handler plugin and use it in a view.
The Drupal core Views module architecture is built on top of the Drupal Plugin API. This allows site administrators to pick and choose from a list of options (plugins) to handle all the different parts of a view -- including what to display, what style to display it in, how to order the results, who has access, and more. In the Views UI, any time you're presented with the option to choose something from a list of options you're likely dealing with some type of plugin.
The advantage of a plugin-based design is that all functional parts of the Views module are provided in an extensible object-oriented way. The Views module defines the basic framework, and provides interfaces for other modules to implement, extend, and customize via plugins. Customizations to filters, fields, area handlers, sorts, and relationship handlers start with plugins.
In this tutorial we'll:
- Learn about Views plugins and the role they play
- Explore the different plugin types and their underlying classes
- Get a high level overview of the steps for creating a custom Views plugin
By the end of this tutorial you'll have a solid understanding of the different Views plugin types, what they are used for, and where to start if you'd like to define your own.
By default, the Views module can display data contained in any field attached to an entity that is exposed in Views, and the content of any database column exposed to Views via an implementation of hook_views_data()
. It's also possible to create pseudo fields. These appear in the Views UI like any other field, but don't map directly to the data stored in a database column and instead allow the data to be preprocessed. This could be performing a calculation, combining multiple fields into one, and much more.
A common example in core is the fields that allow you to perform edit or delete operations on a node. These don't correspond to a specific database column. And they can't be hard-coded because they require dynamic content specific to the node in question. Instead, they are the result of taking the entity ID and combining it with knowledge about the appropriate route for someone to edit the entity and outputting that as a link.
Another example: Imagine a cooking website where you collect cook time and preparation time (prep time) for recipes and want to also display the full time to prepare. In this case cook time and prep time could be fields on the recipe content type and total time could be handled as a calculated output of both fields, added together and converted into hours and minutes. To achieve this, you can create a custom Views pseudo field and specify the calculation and processing logic in the render function.
In this tutorial we'll:
- Learn how to define a custom Views field plugin for a pseudo field
- Attach the created field to node entities, and expose it to display in a view
By the end of this tutorial you should know how to define a Views pseudo field plugin, attach it to the node entity type via hook_views_data_alter()
, and display it in a view.
Style plugins are responsible for determining how to output a set of rows. Individual rows are rendered by row plugins. Drupal core provides style plugins that include grid, HTML list, table, and unordered list styles. If you need to render the results in a different way, for example as tabs or accordions, or have special markup based on your project requirements, you may want to write a custom style plugin for Views. The advantage of this approach versus overriding the templates in a theme is that you may reuse this plugin in different views throughout the site, or even on different sites.
In this tutorial we'll:
- Learn how to create a custom Views style plugin and render output in the form of an accordion using the HTML5
<details>
element. - Demonstrate how to use a custom style plugin when building a view.
By the end of this tutorial you should know how to declare custom Views style plugins.
Identifing the fields in your data model that contain presentation data is an important part of documenting and planning your API. Examining your existing data model will help put you in the correct mindset when creating or changing it. It is important to reflect on the implications of each field for each hypothetical consumer (even consumers your API is not serving). This process will improve your content model and your API.
In this tutorial we will:
- Go through the article content type's data model
- Locate any fields that contain presentation data
The article model is created out of the box by Drupal when using the standard installation profile.
By the end of this tutorial you'll know how to do these checks, and identify presentation data in your content model, on any content type in your project.
In a monolithic architecture (non-decoupled) there is an implicit proof that the user in the front-end is the same one in the back-end. This empowers the front-end to offload all the authentication and authorization to the back-end, 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 back-end.
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.
It is important to have good up-to-date documentation about your web services. Doing so will boost developer productivity in a decoupled project. Drupal offers several tools that help maintain your API documentation with minimal effort.
In this tutorial we'll:
- Learn about the JSON schema format for describing data structures
- Generate schemas for our fake articles REST resource
- Visualize those schemas in a human-readable format
By the end of this tutorial you should be able to generate documentation for your REST resources that is kept up-to-date automatically by Drupal.
Traditional Drupal development using the render pipeline allows you to ignore the pitfalls of mixing content and presentation logic in your data model. In a scenario with multiple distribution channels, this separation becomes of critical importance.
In this tutorial we will learn how to:
- Understand the importance of presentation and content separation (delivering clean content, not caring about how to show that content)
- Develop strategies to avoid these presentational problems with minimal damage to the content API
By the end of this tutorial you'll have a better understanding of why keeping presentation data out of your content model is important, and some tips for doing so.
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.
Often, there's an existing Drush command that does most of what you want, but needs just a few tweaks or enhancements to make it meet your project requirements. Maybe the existing core Drush command has the functionality but lacks some additional validation. Or maybe you need to add an option to perform some application-specific debugging logic for all commands in a group.
Drush hooks can be used to alter, extend, and enhance existing Drush commands.
In this tutorial we'll:
- Learn how to alter a Drush command with code in a custom module
- Declare a validation hook that alters the
user:password
command with additional password validation logic
By the end of this tutorial you should be able to alter a Drush command provided by Drush core or a contributed module with your own custom code.
Back-end developers, and Drupal site builders, often find themselves having to perform the same UI steps over and over again, like exporting configuration, importing configuration changes, running cron, processing a large queue of jobs, indexing items for Search API, and more. Performing these tasks with Drush saves time and reduces the number of clicks required.
Drush core contains commands to execute all the most common tasks. Many contributed modules provide their own Drush commands to make interaction with the module's features, easier, faster, and scriptable.
In this tutorial we'll:
- Learn about the Drush core commands for common tasks like interacting with queues, performing database backups, and importing/exporting configuration
- Demonstrate how to find the Drush commands provided by contributed modules in your project
By the end of this tutorial you'll learn some popular commands for common tasks that'll speed up your daily work.
Every Drupal site consists of many Drupal projects like modules and themes. Drush comes with a group of commands that aid in managing projects from the command line. These commands can check which modules are present in a site's codebase, report their security status, enable modules, and display metadata for modules and themes. All of these commands start with the pm
prefix, and are part of the project manager group.
Common use cases for the project manager commands include: quickly enabling/disabling modules via the CLI rather than performing numerous clicks in the UI, and as part of CI/CD process that lists (or maybe even automates) security updates.
In this tutorial we'll:
- List the available
pm
commands - Enable a module with Drush
- Uninstall a module with Drush
- Use Drush to check for security updates for modules, themes and PHP packages
By the end of this tutorial you'll have an understanding of the project manager commands that come with Drush, how to use them, and how to speed up common workflows and maintenance tasks.
Administration and maintenance of Drupal websites consists of many tasks that can both be performed via the command line, and automated, with Drush. Using Drush's site and environment administration commands you can run database updates, check an environment's status, clear (rebuild) the cache, perform Cron-related operations, and manage users. These tasks are repetitive, often require many steps in the UI, and may be tedious in the long run. Learning to execute them with Drush can save you time and allows for more automation of common tasks.
In this tutorial we'll:
- Use Drush to check a site's status
- Learn how to perform database updates with Drush
- Clear the Drupal cache with Drush
- Use Drush to execute Cron tasks for a Drupal site
- Learn how to use Drush to login to a site as any user, and manage existing users
By the end of this tutorial you'll be able to perform many common Drupal environment and administration tasks from the command line with Drush. We're not going to cover all of the environment management commands in this tutorial, just some of the more popular ones. We encourage you to explore further on your own.
What Is Drush?
FreeDrush, aka The Drupal Shell, is a command line utility and UNIX scripting interface for Drupal. It allows access to common Drupal features and tasks via the command line. It can help speed up common tasks for Drupal site builders, developers, and DevOps teams. Among other things, it makes it easier to integrate Drupal into CI/CD workflows.
In this tutorial we'll:
- Learn what Drush is and what can be done with Drush
- Install Drush
- Find a list of Drush commands
- Learn how to execute commands
By the end of this tutorial, you'll understand how to install and use Drush with your Drupal projects, navigate the list of its commands and run them. This is intended as an overview. Other tutorials will provide more detail about common commands and use-cases.
Make your custom Drush command more flexible by allowing users to pass command line arguments into it. For example, rather than hard-coding that the command lists users with a specific status, allow the desired status to be specified at run-time. This allows the command's logic to be more generic, and to return different results, or operate on different data, based on the provided parameters.
Parameters are variables that are passed from user input at the command line into the Drush command method. Typically, they are either single string values, or comma-delimited strings of values. Parameters are typically used to provide input for the command related to what the command should work on, in contrast to options, which are typically used to configure how the command works.
In this tutorial we'll:
- Declare parameters for a custom Drush command in its attributes
- Use the parameter input inside the custom Drush command method
By the end of this tutorial you should understand how to work with parameters inside custom Drush commands.
When you create a custom Drush command it might be useful to allow users to pass options (predefined values) that change the way a command works. You can think of options as being flags, or variables, that affect the command's internal logic. As an example, consider the Drush core user:login
command which by default returns a one-time login link for the root account. The command also accepts an optional --name
option which allows the internal logic to create a link for a specified user instead of only being able to create links for the root user. This makes the command useful in a wider variety of situations. Another common option is the --format
option which allows a user to specify that they want the command to return its output in a format (CSV, JSON, Table, etc.) other than the default.
Options are defined in the Drush command's attributes. Their values are passed as part of an associative array to the command method. Unlike parameters, options are not ordered, so you can specify them in any order, and they are called with two dashes like --my-option
. Options are always optional, not required, and can be set up to accept a value --name=John
or as a boolean flag without a value --translate
.
In this tutorial we'll:
- Declare options for a custom Drush command in its attributes
- Learn how to use these options inside the custom Drush command method
By the end of this tutorial, you should be able to add options to your own custom Drush commands.
Drush commands are commonly run in the Drupal docroot, the directory where Drupal's files live. This is a relatively simple task on your local development environment. But if you're working on multiple sites and each of those sites has one or more remote environments that you connect to via SSH, workflows quickly become complicated. Creating and using Drush site aliases allows you to run Drush commands on any site, local or remote, that you have credentials to access, from any location on your computer that has access to a Drush executable.
Imagine you've got a Drupal project with dev, test, and live environments in the cloud somewhere. And you need to clear the cache on the dev environment. You could SSH to that environment, and execute drush cr
there. Or, after configuring a site alias you could do something like:
drush @provider.dev cr -y
And Drush will connect to the remote environment and clear the cache.
Site aliases allow bundling the configuration options (--uri
, --root
, etc.) for a specific remote server under an alias. This reduces the amount of typing required. Even more importantly, it helps teams agree on a common definition for environments like @dev
, @test
, and @live
by committing their configurations to version control.
In this tutorial we'll:
- Define what a Drush site alias is
- Understand the use case for aliases
- Learn how to configure and use Drush site aliases
By the end of this tutorial, you should understand how Drush site aliases work, how to create Drush site aliases, and how to use them in a Drush command.
The Drush executable can be configured through the use of YAML configuration files and environment variables. This configuration can help cut down on typing lengthy frequently-used commands. You can tell Drush to look for command files in project-specific locations. Configuration can also set the value(s) of a specific command's options, instead of having to type them at the command line every time.
In this tutorial we'll:
- Explore different Drush configuration options
- Learn how to configure Drush for your project
By the end of this tutorial, you'll know how to provide project specific, and global, configuration that helps customize Drush and improve your own efficiency.
Creating a custom Drush command requires creating a PHP class that Drush can find with methods that have PHP attributes that provide metadata about each custom command. You'll use an autowire trait to inject any services into it. You'll also optionally modify the project's composer.json to tell Drush what versions of Drush the command is compatible with.
Custom Drush commands are a great way to expose your custom module's features to help automate these tasks and allow users to perform them as background processes. They can also provide a more efficient way to execute PHP code that takes a long time and is prone to timing out when run via the web server.
Depending on your use-case it can also be more efficient to create a custom Drush command to execute your logic instead of coding a complete UI. For example, if all the command needs to do is generate a CSV list it might take less effort to write a Drush command and pipe the output to a file than to create a UI that generates a file and prompts the user to download it.
In this tutorial we'll:
- Declare a new custom Drush command inside a custom module
- Make our custom Drush command output a list of all the blocked users on the site
- Verify our new command is working
By the end of this tutorial you should understand how to create a custom Drush command that returns a list of blocked users.
Developers can implement the Drush Command API to write their own custom Drush commands. This allows you to include Drush commands with your modules to allow the module's features to be used via the CLI. You can also create project-specific Drush commands that help with the development, deployment, and maintenance of your particular application.
We've written Drush commands to help generate reports, make it easier for new team members to get up and running, compile custom theme assets, and more. Any time we need to write PHP code that interacts with our Drupal site where we're worried the code might time out because it takes too long to execute we'll reach for Drush. Custom Drush commands are also useful to combine background processes that can be executed on cron, such as nightly imports, data synchronization, bulk database manipulation, custom queues processing, and so much more.
In this tutorial we'll:
- Learn about different types of custom Drush commands
- Review the anatomy of a Drush command
- See how the Drush bootstrap process relates to commands
By the end of this tutorial, you'll be able to identify the parts of a custom Drush command and start writing your own.