Developers can implement hook_views_pre_render() to make changes to a ViewsExecutable object and change the render array that gets generated by the render phase of a view. By the time hook_views_pre_render() gets invoked, the data to display has already been collected, and things like field formatter configuration have been loaded. This hook gives you the opportunity to dynamically alter that configuration before it's passed to field handlers that will ultimately calculate and return a render array by combining the field configuration with the query results.
You might, for example, dynamically change the label used in a table depending on context that doesn't exist in the view itself. Another example, and the one we'll use here, is transforming a view's rows into a slider (or tabs, or an accordion). That requires that you alter the views object before rendering and attach a custom JavaScript library.
If the thing you want to change is the configuration of the display or any fields, or the contents of the results (versus the presentation of the results) of a view, than hook_views_pre_render() is the right place to do that. If you're looking to alter the generated render array than you'll likely want to use hook_views_post_render().
In this tutorial we'll:
- Alter a
ViewsExecutableobject usinghook_views_pre_render()before the view is rendered. - Attach custom JavaScript (or CSS) to a view.
- Transform a view of article nodes into an interactive slider using the Slick Slider JavaScript library and some custom JavaScript code.
By the end of this tutorial, you should know how to alter the render array of a view and attach custom and third-party asset libraries in a Drupal site.
At its core, Views is a query generator. It provides a way for site builders and developers to construct queries for Drupal content using an intuitive user interface. The UI allows you to configure the fields, filters, sorting, and relationships in the generated query using common conditions. In most cases, this is sufficient. However, there are situations where you need to dynamically alter the constructed query using hook_views_query_alter() prior to its execution.
One example use case is adding sort parameters to a search view if no search terms have been entered. You can use hook_views_query_alter() to check if a search term was entered. If so, sort the result by relevance; and if there are no search terms, sort the results by date. Or maybe you need to dynamically set the value of a filter condition based on a calculation performed by your custom code.
Using hook_views_query_alter() in a custom module, you can alter the query that is generated by a view before the query is performed. In most cases this alters the SQL query used. This same technique will work regardless of the storage system Views is querying.
In this tutorial we'll:
- Learn how to alter a view's query using the
hook_views_query_alter()hook in Drupal - Use
hook_views_query_alter()to dynamically add a new sort condition that could not be achieved using the UI
By the end of this tutorial you should know how to alter the database query used to retrieve the results for a view.
The Views module is a query generator and render engine in Drupal core. It's typically used to create and output collections of items such as Drupal content entities. But it can also aggregate users, blocks, log records, and more. The output can be rendered many ways, including as a list, a grid, or an RSS feed. Views is commonly used in Drupal to create pages, blocks and other types of displays.
Through the Views API developers can expose new data to Views, add new configuration options, create new output plugins, field formatters, sort handlers, filter handlers, and more. By creating these customizations as extensions of Views instead of as stand alone queries, or hard-coded lists, you can empower site administrators to mix and match your customizations with the existing feature set in any way they might need.
In this tutorial we'll:
- Get a high level overview of the Views API.
- Discuss the functional parts of the Views API such as hooks, plugins, and data types.
- Learn how to use the Views API in your project.
By the end of this tutorial you'll have a solid understanding of the parts of the Views API and some guidance on which to use for your goals.
In the process of displaying the content of a view to an end user, every view goes through a common build cycle. As a developer it helps to understand the build and render cycle that a view goes through and how you can use it to alter the final result. It helps to know where things are in the cycle when your code is executed, and how that impacts what your code can and can't do. The Views module exposes hooks -- documented in views.api.php -- that allow developers to influence every step of the cycle. This includes altering the database query that gets executed, changing the configuration of filters, computing things based on raw results, and changing the rendered output of any field.
In this tutorial we'll:
- Learn the steps of the Views build and render cycle.
- Identify the hooks invoked during each step and provide examples of what types of things you might do with each hook.
By the end of this tutorial you should be able to list the hooks invoked by Views, when they get called during the build and render cycle, and explain the impact this has.
Drupal's Entity API allows developers to expose custom entities to the Views module, and takes care of many common features. It can handle exposing the fields associated with fieldable entity types for use as fields, filters, sorts, and arguments. It provides a way to customize any aspect of the Views integration, and makes it possible to create explicit relationships between 2 different entity types.
In this tutorial we'll:
- Expose a custom Subscriber content entity type and all of its data to Views.
- Create an explicit relationship between the custom content entity and Drupal core User entities.
- Build a view of Subscriber entities.
By the end of this tutorial you should know how to expose custom entities to Views.
Filter plugins provide the logic for determining what items to include in a view. They are the equivalent of a WHERE clause in an SQL statement. Filters can be exposed to the end user, allowing the viewer to enter a value, or select from a list of options, that are used to filter a list. For example, the options at the top of the Content list at /admin/content allow you to limit the list by content type.
Drupal's Views module provides filter plugins that can handle filtering for all core defined field types, as well as generic data types like numbers and strings. In situations where these filters don't meet your functional requirements, or you need a filter for a custom field, you may want to define a custom Views filter plugin. A common real-world scenario is defining a new filter plugin that extends an existing one and adds new possible values or options. For example, providing a relative date filter that allows a user to choose options like Last week or Last month.
In this tutorial we'll:
- Learn how to create a Views filter plugin.
- Associate our new custom filter with data exposed to Views, so it can be used.
- Learn how to use it in a view as an exposed filter.
By the end of this tutorial you should know how to create a custom filter plugin and use it in Views.
Sort plugins are responsible for determining how the data in a list created with Views is sorted. Sort plugins are applied to fields. For example, a field might contain numbers and the sort plugin can handle putting the values into ascending or descending order. Typically, sort plugins work by adding to the ORDER BY clause of an SQL query.
The Views module provides sort plugins for all core field types. This includes handling for most primitive data types like strings and numbers. A typical use case for creating a custom sort plugin is extending an existing sort plugin with new conditions or custom sorting logic. For example, you might need to create an alphabetical title sort that excludes articles like a, an, and the. Or a sort based on combining the values in multiple fields.
In this tutorial we'll:
- Learn how to create a custom Views sort plugin
- Associate our custom sort plugin with a field exposed to Views
- Use the sort plugin in a view to sort a list of Article nodes
By the end of this tutorial you should know how to create a custom sort plugin for the title field.
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.
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.
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.
In the last several years REST has been the de facto standard for web services. However, there are several common problems when developing websites and digital experiences with the traditional REST implementations. Luckily, those issues have solutions, either complete or partial.
Modern web service specifications like JSON:API and GraphQL implement those solutions, although they differ slightly in their implementation.
In this tutorial we will learn about:
- The problems of traditional REST implementations
- Common solutions to those problems, and how JSON:API and GraphQL deal with them
By the end of this tutorial you'll be able to explain some of the common pitfalls of REST-based APIs, and how JSON:API and GraphQL address those issues.
The term web services has been around for quite a while. Given that web services is such a broad topic, let's define what web services are and how we are going to refer to them throughout this series so we are all on the same page.
This tutorial is an introduction to web services that will help you:
- Learn what a web service is.
- Understand that this series focuses on HTTP web services, and mostly on REST principles.
- Get some examples of APIs in the wild and what type of consumers they have.
By the end of this tutorial, you'll be able to define what web services are, and how we'll use the term in the context of these tutorials.
As a theme developer you can extend an existing asset library to include custom CSS and/or JavaScript from your theme. This is useful when you want to add styles or behaviors to components provided by Drupal core or another module.
Sometimes there are CSS or JavaScript asset libraries attached to the page by Drupal core, a contributed module, or another theme, that do something you don't like, and you want to change it or even exclude it all together. There are a couple of different ways that themes can override, alter, or extend, an existing asset library in order to modify the CSS and JavaScript that get attached the page by other code belonging to another theme or module.
In this tutorial we'll learn how to:
- Extend an existing asset library using
libraries-extend, so that our custom CSS and JavaScript is included whenever that library is used. - Override an existing asset library using
libraries-override, to alter the definition of the library, and replace or exclude individual assets (or the entire library).
By the end of this tutorial you should be able to use your custom theme to override, extend, or alter any of the asset libraries added to the page by another theme or module.
When running migrations you can use the highwater_mark source plugin configuration option to influence which rows are considered for import on subsequent migration runs. This allows you to do things like only look at new rows added to a large dataset. Or to reimport records that have changed since the last time the migration was run. The term, highwater mark, comes from water line marks found on structures in areas where water level changes are common. In running migrations, you can think of a highwater mark as a line that denotes how far the migration has progressed, and saying, "from now one, we only care about data created after this line".
Another common use case for highwater marks is when you're importing a large dataset and the system runs out of resources. Usually this will look like a migration failing because it timed out, or the process ran out of memory. A highwater mark should allow you to pickup from where you left off.
In this tutorial we'll:
- Define what a highwater mark is, and how you can use them to limit the rows considered for importing each time a migration is executed.
- Demonstrate how highwater marks can be used to reimport source records that have been modified since the previous time the migration was executed.
- Introduce the
track_changesoption.
By the end of this tutorial you should be able to define what a highwater_mark is and how to use them to speed up the import of large datasets or force the migration to reimport records when the source data is changed.
You should also be aware of the track_changes feature which is a slower, but more dynamic, method of checking for changes in source data and reimporting records when a change is found.
If you need to write a migration that is capable of being executed multiple times and picking up changes to previously imported data, you can use the track_changes configuration option of most source plugins. This will tell the migration to keep a hash of each source row, and on subsequent runs of the same migration it will compare the previous hash to the current one. If they don't match this means the source data has changed, and Drupal will reimport that record and update the existing destination record with new data.
Using track_changes differs from calling drush migrate:import --update in that using --update will force every record to be re-imported regardless of whether the source data has changed or not.
In this tutorial we'll:
- Learn how change tracking works to detect changes in your source data
- Use the
track_changesoption in a migration
Note that progress of a migration can also be tracked using highwater marks if the source data has something like a last_updated timestamp column. Using highwater marks in this case is likely more efficient than using track_changes. It's a good idea to understand how both features work, and then choose the appropriate one for each migration.