React excels at displaying lists of data. But that data needs to come from somewhere. In most cases this happens by making a network request to retrieve data from one or more APIs, processing the response, and then displaying the data. In the context of working with a Drupal site there are two possible options: Drupal core's JSON API module, or the drupalSettings
JavaScript API.
In this tutorial we'll focus on the high-level overview and:
- Explain the difference between content and configuration data
- Introduce the JavaScript Fetch API, and where to find information about using it
- Get an overview of the ES6 array functions we'll use to parse the complex data structures returned from an API
In the remaining tutorials in this series we'll provide examples of real world use cases.
By the end of this tutorial you should have a firm understanding of how to get started making API requests using React.
In order for our React code to list content from Drupal we'll need to enable the Drupal core JSON:API module, and then use fetch()
in our React component to retrieve the desired data. This technique works for both React code embedded in a Drupal theme or module, and React code that is part of a fully decoupled application. We'll discuss the differences between those styles as well.
In this tutorial we'll:
- Use
fetch()
to bring data from Drupal into React - Parse the data using ES6 array functions to find just the bits of data we need
- Combine multiple React components together to render a list of articles retrieved from Drupal
By the end of this tutorial, you should have a better understanding of how data from a Drupal API gets incorporated into a React application.
To perform create, update, and delete (CRUD) operations with Drupal core's JSON:API via React there are a few things you'll need to understand. First, how to format the POST
, PATCH
, and DELETE
requests necessary to add, edit, and delete Drupal entities. Next, how to handle authentication, and cross-site request forgery (CSRF) tokens. Over the next few tutorials we will create a simple but powerful React application that can add, edit, and delete Drupal node content.
This tutorial contains:
- An overview of the application we're building
- Information about making secure authenticated requests to Drupal's JSON:API
- An overview of the API requests we'll use to create, update, and delete nodes
By the end of this tutorial, you should have a picture of the application we're going to build, and know how to make the API requests we'll use in our application.
Using React we can do more than just list content. By using the POST, PATCH, and PUT methods of Drupal core's JSON:API web service we can also add, update, and delete, content entities. To demonstrate how this works we'll create a small React application with a form that lets you add, edit, and delete article nodes.
In this tutorial we'll:
- Learn how to handle user authentication and CSRF tokens in a React application
- Create a single React component that outputs a form to add or edit content
- Create a wrapper around the JavaScript
fetch
API to assist in dealing with requests to Drupal's JSON:API
By the end of this tutorial you should know how to create, edit, and delete content in a Drupal site using a React application.
Now that we know how to build a working application in React and embed the application in Drupal, let's make a stand-alone version of our application which can be used outside of the context of a Drupal module or theme. In the next few tutorials we'll look at how to create a fully decoupled React application whose only interactions with Drupal happen via API requests.
In this tutorial we'll:
- Introduce differences we need to account for in a fully decoupled application
- Provide an example of what the final project will look like
By the end of this tutorial you should have a better understanding of what we're trying to create in the rest of this series.
Using create-react-app we can scaffold a stand-alone React application with boilerplate configuration and organization already in place. It's a great way to get started using React, as well as the ecosystem of associated tools like Webpack, Jest, and Babel. After creating the scaffolding, we'll port the code we wrote in previous tutorials to the new structure.
In this tutorial we'll:
- Use
create-react-app
to scaffold a new React project - Refactor existing code into the organizational structure used by
create-react-app
- Confirm that our code runs
By the end of this tutorial, you should know what create-react-app
is and how to get started using it.
When you create a fully decoupled application, the code in your application can't rely on things like the fetch()
function's same-origin
policy and the browser's use of cookies to authenticate requests. Instead, you need to use alternative methods like OAuth or JSON Web Tokens (JWTs).
We'll focus on setting up and using Drupal as an OAuth provider, and allowing a decoupled application to authenticate users via OAuth. This same technique applies just as well if you want to use JWTs.
In this tutorial we'll:
- Install the Simple OAuth Drupal module, and configure it to work with a password grant flow to allow our code to exchange a username and password for an access token
- Demonstrate how to retrieve and use an OAuth access token to make authenticated requests
By the end of this tutorial you should know how to install and configure the Simple OAuth module and make authenticated API requests using an OAuth password grant flow.
To perform POST, PUT, and DELETE operations to Drupal's JSON:API via a decoupled React application we need to use an OAuth access token. This requires first fetching the access token from Drupal, and then including it in the HTTP Authorization
header of all future requests. We'll also need to handle the situation where our access token has expired, and we need to get a new one using refresh token.
To update our example application we need to first write some JavaScript code to manage the OAuth tokens. Then we'll update our existing React components to use that new code.
In this tutorial we'll:
- Write code to exchange a username and password for an OAuth access token using the password grant flow
- Create a wrapper for the JavaScript
fetch()
that handles inserting the appropriate HTTPAuthorization
headers - Update existing code that calls the Drupal JSON:API to use the new code
By the end of this tutorial you'll be able to use OAuth access tokens to make authenticated requests in a React application using fetch
.
React Fast Refresh (formerly Hot Module Replacement) is a technique for using Webpack to update the code that your browser renders without requiring a page refresh. With fast refresh configured it's possible to edit your JavaScript (and CSS) files in your IDE and have the browser update the page without requiring a refresh, allowing you to effectively see the results of your changes in near real time. If you're editing JavaScript or CSS it's amazing. And, it's one of the reasons people love the developer experience of working with React so much.
If you're writing React code as part of a Drupal theme it's possible configure fast refresh to work with Drupal. Doing so will allow live reloading of any JavaScript and CSS processed by Webpack.
In this tutorial we'll:
- Walk through configuring Webpack and fast refresh for a Drupal theme
- Add an
npm run start:hmr
command that will start the webpack-dev-server in hot mode - Configure the webpack-dev-server to proxy requests to Drupal so we can view our normal Drupal pages
By the end of this tutorial you should know how to configure Webpack to allow the use of React's fast refresh feature to your Drupal theme and preview changes to your React code in real time.
Every theme can contain an optional THEMENAME.theme file. This file contains additional business logic written in PHP and is primarily used for manipulation of the variables available for a template file, and suggesting alternative candidate template file names. Themes can also use this file to implement some, but not all, of the hooks invoked by Drupal modules.
In this tutorial we'll learn:
- The use case for THEMENAME.theme files, and where to find them
- The different types of functions and hooks you can implement in a THEMENAME.theme file
By the end of this tutorial you should be able to know how to start adding PHP logic to your custom theme.
Themes and modules can alter the list of theme hook suggestions in order to add new ones, remove existing ones, or reorder the list. This powerful feature allows for the definition of custom logic in your application that can tell Drupal to use different templates based on your own unique needs. You might for example; use a different page template for authenticated users, or a custom block template for someone's birthday.
In this tutorial we'll cover:
- Adding new theme hook suggestions from a theme using
hook_theme_suggestions_HOOK_alter()
- Altering the list of theme hook suggestions
- Removing theme hook suggestions
- Reordering the list of theme hook suggestions
Just like PHP or JavaScript, Twig has functions that can be used once we’re inside either a Twig delimiter. To see the built-in functions, check out the bottom of the Twig documentation page. In your application, especially if you’re using Twig inside something like Symfony or Drupal, you may have even more functions available to you. Fortunately, the syntax to use a function is always the same: just check out your project’s documentation to see what other goodies you have. In this tutorial, you will start using Twig functions and filters to get the length of a collection in our demo site. We'll also play around with the dump
function to see how we can go about debugging Twig.
Additional resources
Until now, we’ve been working with simple values like pageTitle or products, which is an array that contains simple values where we loop over and print each out. In this tutorial, you will work with more complicated arrays, using keys, and figure out how to get at object data as well.
If we view the HTML source of our project so far, we’ll see just the HTML tags and printed variables from our homepage.twig file
. So far, there’s no HTML layout, head or body tags, but since our project has been ugly long enough, in this tutorial we'll add these. Instead of just putting these in our homepage file, we're going to make this more flexible by using template inheritance, so we can reuse these pieces in other template files as we grow our site. We'll be diving into the world of Twig extends and blocks, and talking about how to avoid common mistakes.
Additional resources
Using a base layout is very common, and we’ve implemented that in the previous tutorial. Sometimes you also need to include some other templates on only select pages. In this tutorial you are going to add a sales banner to the pages using the include
function, and working with the variables we can pass there.
Additional resources
Be sure to check the documentation for the version of Twig in your codebase for the correct syntax and usage.
In our last tutorial we have things set up to include a new template, but we are currently getting an error, due to not passing the correct variable. In this tutorial we'll see how to fix this problem by adding a "defined" test to our code, which will check to see if the variable is defined in the _banner.twig template
, and default to "lightblue" if it is not.
Additional resources
Our products are printing out a bit weird right now because they’re floating, but not breaking correctly. To fix this, we need to wrap every three products in their very own row. In this tutorial, you will use a "divisibleby" test to see if the item number we’re on is divisible by three, and then loop through them. We'll also clean up our if
statement for our background color, by implementing an inline if
syntax.
In this tutorial we're going to purposely make some common Twig mistakes, debug them, and figure out how to fix them. We'll also look at a way to make parts of your Twig code easily reusable, using macros.
Twig: The Basics
FreeTwig is a templating language for PHP, which is a boring way of saying that it’s a tool used to output variables inside HTML. In this series we'll show you how to use Twig from the ground up, clearly pointing out its syntax, and then graduating to some really neat and advanced tricks. We'll start with a look at Twig syntaxes, functions and filters. Then we'll get into the world of debugging with the dump()
function. With the basics under control, we'll move to handling arrays and objects. template inheritance, tests, looping tricks, and macros (Twig functions).
To make this interesting, we're going to build something useful with Twig, like a penguin clothing store! We're starting out with a small website set up under your web server’s document root and a test page called test.php, which you can find in the series demo site download. In this lesson, you will create your first Twig template, render a variable, and learn the basic Twig syntax you'll need to know.
Additional resources
Underscore.js is a very small library which provides several utility functions and helpers to make working with JavaScript a little bit easier. In this tutorial we'll take a look at a part of the library, learn where the full library is documented, and see how we can make use of Underscore.js in a custom block on our Drupal site.