Chapter 9: Working with Data

Drupal uses 4 primary information types for canonical data storage: content, configuration, session, and state. Content encompasses the site's visible data, such as articles, images, and files. Content data are called content entities in Drupal. Configuration data stores site settings including site name, content types, and views. Session data tracks user interactions, including login status. State data holds temporary information like the last cron execution time.

In this tutorial, we'll:

• Define the 4 main information types and their use cases.
• Get a high-level overview of when module developers should expect to encounter each data type.

By the end of this tutorial you should be able to recognize each of the 4 main information types used in Drupal.

The Configuration API provides a standardized method for storing and managing a module's settings in Drupal. This tutorial covers the concepts of active configuration, simple configuration, configuration entities, and configuration schemas, and how to interact with, create, and retrieve configuration data.

By the end of this tutorial, you'll have a better understanding of how to work with configuration data in Drupal, focusing on simple configuration for module settings.

Modules in Drupal often rely on the Configuration API to adapt their behavior based on administrator-defined settings. This involves both reading values from configuration objects in custom code and enabling administrators to modify these values with a settings form.

In this tutorial, we'll:

• Demonstrate accessing configuration data with the config.factory service.
• Examine the module's settings form's interaction with the Configuration API.
• Adjust the WeatherPage controller's behavior based on administrator-defined configuration.

By the end of this tutorial, you should be able to read and output simple configuration data within a module.

Modules must provide metadata about their configuration data via a schema definition, which serves localization and validation purposes. Modules can optionally specify default configuration values to ensure that the module functions when installed.

In this tutorial, we'll:

• Define schema for the Anytown module's configuration.
• Set default module settings.

By the end of this tutorial you should be able to define a configuration object's schema and default values.

Entities are the building blocks of Drupal's data structures. As module developers, the Entity API provides a way to manage custom data with minimal code. You'll use it when altering or enhancing existing content or when managing custom data sets. Instead of writing SQL, you'll be using the Entity API to manage data within a Drupal application.

In this tutorial, we'll:

• Define entities and their significance in Drupal.
• Distinguish between content entities and configuration entities.
• Explore entity-related terminology such as bundles, fields, annotations, plugins, and handlers.

By the end of this tutorial, you'll have a foundational understanding of the Entity API and how it's used for data management in Drupal.

In Drupal, content entities can have fields. Field data is entered using widgets and displayed with formatters. The Field API provides developers with means to customize fields, widgets, and formatters. Which gives site builders tools to build flexible, extensible sites using customized data models.

In this tutorial, we'll:

• Learn what it means for an entity to be fieldable.
• Define what field types, widgets, and formatters are and give examples of each.
• Explore the differences between base fields and user-defined fields.
• Define the concept of field instances.

By the end of this tutorial you should be able to define the main components of the Field API and understand how developers leverage the Field API to alter and enhance Drupal.

To implement a custom vendor attendance status feature, we need to add new fields to the Vendor content type. This tutorial will guide you through adding these fields and discuss the considerations for choosing between Drupal's UI for data modeling versus code-based alterations of entity types.

In this tutorial, we'll:

• Add new fields to the Vendor content type required for the vendor attendance status feature.
• Discuss the pros and cons of modeling data with Drupal's Field UI compared to using hooks for modifying entity base fields.

By the end of this tutorial, you'll know how to update the Vendor content type with necessary fields and understand why this approach suits our specific case.

Adding the new vendor attendance feature starts with adding a custom module, and defining the form controller with a simplified user interface. This is mostly accomplished using concepts that we've already explored, so we'll use this as a chance to practice what we've learned.

In this tutorial, we'll:

• Construct a new module, form controller, and route.
• Discover how to create local tasks for an enhanced administrative UI.

By the end of this tutorial you should be able to navigate to the Attendance tab of Vendor node to access a simplified UI.

Entities objects are loaded using the entity type manager service (technically, the entity storage manager). Field values are read from the entity object. Doing this, instead of directly accessing data in the database, ensures that our custom code can remain agnostic about any underlying data storage logic. Reading field values is a common task, and we'll practice it by loading a vendor entity and using existing field values to pre-populate the new vendor attendance form.

In this tutorial, we'll:

• Load an entity using the entity type manager service.
• Access raw values of entity fields.
• Use #default_value in Form API to pre-populate form fields.

By the end of this tutorial, you'll be able to get raw field values from entities.

Updating entity field values involves loading the entity object, modifying field values, and saving the entity to the database. We'll add a submit handler in our form that uses Entity API methods to update the vendor entity with new attendance data from the form.

In this tutorial, we'll:

• Update and save an entity's field values.
• Implement a submit handler in the attendance form to update the vendor entity with new data.

By the end of this tutorial, you should be able to modify an entity's field values and save the updated entity.

If we use parameter upcasting in our entity route definition, we can simplify code in the StatusUpdateForm controller. Parameter upcasting works by instructing Drupal to load entity objects referenced in a route's path automatically. This approach reduces boilerplate code related to the entity type manager service and entity object loading.

In this tutorial, we'll:

• Define parameter upcasting and its advantages.
• Update the StatusUpdateForm controller with type hinting to use parameter conversion services.
• Refine our route definition's access checking for entity-specific verification.

By the end of this tutorial you should be able to use parameter upcasting to load full entity objects through an updated route definition.

Validation happens whenever an entity is created or updated, ensuring data integrity across form submissions, JSON:API requests, and direct entity object manipulation. Drupal's Entity Validation API, consists of constraints, validators, and their integration. As module developer, we'll use this API to enforce custom rules about what constitutes valid data.

In this tutorial, we'll:

• Learn about the roles of constraints and validators within Drupal's validation system.
• See how to create and integrate custom validation rules.
• Apply custom validation to an entity type that enforces specific data integrity rules.

By the end of this tutorial, you should be able to define new constraints and validators, and associate them with entity types.

Entity queries are the standard method for retrieving, filtering, and sorting lists of entities programmatically in Drupal. Unlike direct database queries, entity queries work seamlessly with Drupal's entity system, including support for access control and abstraction from storage details.

In this tutorial, we'll:

• Introduce entity queries and their operation within Drupal.
• Explain the advantages of using entity queries over direct database queries.
• Provide examples of entity query usage.

By the end of this tutorial, you'll understand how to efficiently and securely fetch lists of entities using entity queries.

Learn how to use a cron job combined with an entity query to reset the attending status of vendor nodes every week. This will ensure that the vendor entity data only contains current check-ins.

In this tutorial, we'll:

• Implement hook_cron() within the Anytown module.
• Use an entity query to identify all vendor nodes requiring updates.
• Apply Entity API methods to reset each vendor's attending status.

By the end, you'll know how to execute an entity query, retrieve nodes, and update their status with cron.

Drupal allows site administrators to configure view modes, defining an entity's display. As module developers, we use view builders to transform an entity object into a renderable array, respecting site-specific configurations without hard-coding display details.

In this tutorial, we'll:

• Introduce view builders and explain their significance in entity rendering.
• Develop a route and controller for a new /attending page
• Use an entity query to retrieve vendor nodes and render them with view builders

By the end of this tutorial, you'll know how to display entities using a site-specific teaser view mode.

Drupal's Entity API enables us to define custom content entity types. It provides a structured approach to store custom data. Creating a custom entity makes sense when built-in entity types like nodes or taxonomy terms don't meet the specific requirements of a project. Custom entities allow for custom data structures, and use Drupal's core features such as access control, Views integration, and JSON:API support. Using the Entity API to create custom content entities ensures your custom data will be compatible with other Drupal modules.

In this tutorial, we'll:

• Discuss use cases for custom content entities.
• Get a high-level overview of defining a custom entity type.
• Provide additional resources where you can learn more about defining custom entity types.

By the end of this tutorial, you'll understand the use case for custom content entities and how to begin defining one.