How-To

In November 2022 the Drupal community and the Drupal Security Team will end their support for Drupal 7. By that time, all Drupal websites will need to be on Drupal 8 to continue receiving updates and security fixes from the community. The jump from Drupal 7 to 8 is a tricky migration, often requiring complex data transformations to fit legacy content into Drupal’s new paradigm. If you are new to Drupal migrations, you can read the official Drupal Migrate API, follow Mauricio Dinarte’s 31 Days of Drupal Migrations starter series, or watch Redfin Solutions’ own Chris Wells give a crash course training session. This blog series will cover more advanced topics such as niche migration tools, content restructuring, and various custom code solutions. See the first blog in the series Custom Migration Cron Job.

In November 2022 the Drupal community and the Drupal Security Team will end their support for Drupal 7. By that time, all Drupal websites will need to be on Drupal 8 to continue receiving updates and security fixes from the community. The jump from Drupal 7 to 8 is a tricky migration, often requiring complex data transformations to fit legacy content into Drupal’s new paradigm. If you are new to Drupal migrations, you can read the official Drupal Migrate API, follow Mauricio Dinarte’s 31 Days of Drupal Migrations starter series, or watch Redfin Solutions’ own Chris Wells give a crash course training session. This blog series will cover more advanced topics such as niche migration tools, content restructuring, and various custom code solutions.

Accessibility isn’t just a concern for web developers. With content being dynamically created, there are a few points content editors can keep in mind to make sure their content is accessible to everyone. Following accessibility standards helps non-visual users, but can also help all users find and understand the information they’re looking for.

Creating Emphasis

One of the most common times accessibility issues pop up is when content editors are trying to emphasize sections of text. It is important to keep in mind that screen readers do not recognize details like different colors or bolded text, but will intonate exclamation points. If it is vital to the understanding of the content that a certain sentence be highlighted, consider using an exclamation point. If it is not vital but may help visual users to better understand the message, your best bet is making use of bold. 

From a usability standpoint, be wary of using color for emphasis. Colors can have unintended implications, such as causing the user to think the text is a warning, or even a link. Text also has to pass a certain color contrast ratio with its background to maintain accessibility, so unless a designer or developer with a knowledge of accessibility has picked out new colors for you, it’s best not to introduce more.

Another common mistake when emphasizing content is using all uppercase letters. A screen reader will read this out like an acronym, which could be particularly painful for a full sentence. Aside from screen readers, it is also shown to be less readable for all users when there are more than one or two words in a row in all-caps. Sometimes you’ll see all-caps used on buttons or labels, but the crucial difference is that these are (or should be) made into all-caps with code. A screen reader will usually ignore the css and see the text as it is originally written.

Is bold not enough variation for your content? Talk to your designer or developer about coming up with additional text styles for you to use. You may think to yourself, “I already have a dropdown with five different text styles I can use!” What you’re probably referring to is the heading selector.

In response to the COVID-19 pandemic, the Redfin Solutions team has shifted to working remotely. Because of the nature of the pandemic, some of our clients have tight deadlines in order to get information out to people as quickly as possible. A recent client with a special need for a quick turnaround is the Rural Aspirations Project, a non-profit in Maine committed to connecting parents and educators with resources, support, and networking opportunities provided by trusted local organizations. When the schools closed, parents and educators’ need for help grew exponentially. 

Rural Aspirations came to us with the idea for Community Learning for ME. The goal of this project was to create a tool for educators and families to find reliable resources specific to their needs. We knew that for this to be successful it was crucial to keep our focus on the user. At the same time, we had to finish the project within two weeks, including design and implementation, all while adjusting to the new normal of remote work.

User personas + User journeys

Our first step was to get acquainted with the user audiences. Luckily, those at Rural Aspirations are very connected with who their users are, as they work with them personally. In their documentation for the site, they had already included a mix of what we refer to as user personas and user journeys. These outline rough groups of people who will use the website, and the situation they might be in at that moment. 

One of our user personas was Caitlin, a mom of two kids, one in second grade and one in eighth. Her partner is an essential service worker and she has a job where she has to be in meetings during the day. She is overwhelmed by work and childcare but wants to help her kids more. 

Each persona allows the Redfin team to understand a little bit more about one type of person that might be using the site including basic information, the challenges they face, and their goals. We also wanted to understand how they might be using the site – the user journey. For instance, when Caitlin uses this site she wants to get to content for her kids quickly (she may be minutes away from an important meeting) and not have to spend time figuring out if it’s safe and quality content. She would also benefit from discovering that there are resources to help her, in case she wanted to come back when she has some time.

This is the last in a series of blog posts about creating an app with React Native. To get started with React Native, read the Basics of React Native: Part 1. If you want to include content from a Drupal website in the app, read Integrating Content with React Native: Part 2.

It’s almost impossible to build a professional app without including third party or custom libraries. Using libraries where and when they’re needed upholds the tenant of reusability that React Native sets forth. It saves time and money by reusing code that already exists. There are only three steps to include a library in a React Native project:

1. Install the library with npm (node package manager)
2. Use ES6 (ECMAScript 6)  import statements to import whatever components are needed from the library.
3. Implement the components within your component or screen.

Here is an example of how to include a library like GooglePlacesAutocomplete in a React Native app. Install the library using:

$ npm install react-native-google-places-autocomplete

Import components from the library wherever they are needed using:

$ import {GooglePlacesAutocomplete} react-native-google-places-autocomplete

Finally, implement the component within the file by calling on it like any other component:

<GooglePlacesAutocomplete placeholder='Enter Location' minLength={2} autoFocus={false} returnKeyType={'default'} fetchDetails={true} currentLocation={false} />

Leveraging your own components is even easier than leveraging components from libraries. In order to include a custom component, use ES6 import statements to import your components, and implement your components within your component or screen. A common place to store these custom-built components is within a project’s components directory. To use a custom component like CustomComponent.js inside a screen include: import CustomComponent from '../components/CustomComponent' at the top of the file, and <CustomComponent /> when you want to use the component.

Libraries enforce code reusability standards because they encourage writing a piece of code only once and implementing it anywhere else it is needed. Your project will be more organized and easier to expand upon later because this method enforces proper library use. It also saves you from wasted time and headaches down the line because your libraries won’t look like spaghetti when you come back to them months later.

We hope you enjoyed this series about creating an app with React Native. Comment below to share what you found useful or more tips that we missed. For updates on new blog posts, our work, and more, like and follow us on Twitter, Facebook, LinkedIn, and Instagram.

This is the second of three of blog posts about creating an app with React Native. To get started with React Native, read the Basics of React Native. Once you are familiar with the system and have an app, it is time to fill it out with content. If you don’t have content on your Drupal website, read Understanding Drupal 8’s Migrate API.

Exposing Drupal content

Some helpful modules to expose Drupal content are: Views, RESTful Web Services, and Serialization. The concept of getting Drupal content to an endpoint is simple:

1. Build a view containing the data you want to expose.
2. Add a “REST export” display to the view. During this step, select the appropriate serialization type.
3. This will automatically create a REST endpoint at the URL.

The dataflow should look something like this: Drupal Content -> View -> Serializer -> REST endpoint.

Using fetch to asynchronously retrieve data

React Native’s compiler is Babel, which means ES6 code can be used anywhere in the project. This is useful for retrieving data, because ES6 enables the async and await keywords. When used in conjunction with something like fetch, you can create a smooth and elegant solution for pulling data from a server, such as content from a Drupal website.

The code for pulling from a Drupal website REST endpoint is the same as REST endpoint. It should look something like this:

async getSomeData() { let url = "https://data.org/useful/data"; let response = await fetch(url); let data = await response.text(); return data; }

The advantage to making a call like this asynchronously is that it allows other threads to continue running while the fetch is waiting for the server call to return with all of the data it ordered. This improves the user experience because it allows them to continue using other functions while the data loads.

Building a FlatList from a data set

After pulling in data from the endpoint, add a component to display the data. <FlatList> is an excellent component already built in to React Native. These components are useful because they could handle infinite amounts of data without impacting performance, since they only render the part of the list that is currently on screen.

A <FlatList> component takes two props for displaying data. You may need to massage the data to make it easier to use inside a <FlatList>. The first prop is the set of data that it will display. The next prop required by a <FlatList> is renderItem, which describes how the data should be displayed. This is a JSX object that tells the <FlatList> component how to represent each list item, and what fields to pull from the data. You can use any component inside renderItem.

The ListItem component provided by React Native Elements has lots of styling features, like color gradients and automatic chevron placement.

Here is an example <FlatList>:

<FlatList> style={{backgroundColor: '#ededed'}} data= {this.state.peopleData} renderItem={({person}) => <View> <ListItem title={person.name} titleStyle={{ color: '#00AEED', fontWeight: 'bold' }} subtitle={person.position} /> </View> } />

With the skills to expose, retrieve, and display your data, you can integrate a Drupal website with your new React Native app.

Redfin Solutions started using React Native in early June when a client needed an app that could integrate with their Drupal website. Since it was our first project with React Native, we recorded useful information to share with the rest of the team. This is the first in a series of three blog posts that will cover what we learned and what we found the most useful while using React Native.

Expo & React Native CLI

There are two main framework options for building a React Native app: React Native CLI and Expo.

React Native CLI is the option most people from a native app development background choose because it trades a streamlined workflow for the ability to add native modules written in Java or Objective-C.

Expo is easier for people from a web development background because it provides a streamlined workflow to those who don’t need to link native modules to their app. It comes with integrated libraries, a client app for development, and it doesn’t require Android Studio or XCode to build the project for Android and iOS separately. With a signing key, Expo handles the building process. This speeds up the development process and frees up time to spend on new features for the app.

Components

The React Native design philosophy separates each screen into a hierarchy of components. At the lowest level are simple components like <Text>. Larger components are constructed out of other smaller components. They can also be designed as a specific case of another component. For example, it may be simpler to create a <HelloWorld> component that is a more specific version of the <Text> component if you are repeatedly creating <Text>Hello World!</Text>components. 

Props & State

Every component has two stores of data that contain information about itself, props and state. Props are the parameters of a component. It is primarily set when the component is created. For example, the URL of an image component is passed in when it’s created and stored in props. 

Conversely, state is used to store data that changes. When state changes, the component is re-rendered to show the change. For example, the current value of a volume slider might be stored in state.

JSX

JSX is a syntax extension for JavaScript that comes with React Native. It is a simple way to express how the React Native components should be rendered into elements on the screen. JSX is intuitive because it functions within React Native that same way HTML functions in a webpage. Take a look at this JSX for putting text and an image on a screen:

<View> <Text> Hello World! </Text> <Image source={require('../assets/images/hello.png')} /> </View>

Lifecycle API

Every component follows a lifecycle API. This is a set of methods that React Native calls during certain events in a component’s life. The only required method, besides the constructor of a component, is the render() method, which expresses how to render the component on the screen by returning React elements that are usually defined by JSX. 

Styling

Styling in React Native is similar to CSS. Every component can be styled with a StyleSheet prop, which is a set of CSS-style selectors passed inside of a JavaScript object. They even support Flexbox. For example: 

const styles = StyleSheet.create({ header: { fontWeight: 'bold', fontSize: 30, }, });

And when you want to apply it to a component: <Text style={styles.header}> Hello World! </Text>

To see all the style options available, check out the documentation for each component. 

React Navigation

It is easier to start app designs at navigation by planning out what each screen will contain and how to navigate between them. This top-down approach prevents context switching between screens while writing. 

React Navigation, one of Expo’s integrated libraries, provides tools for creating a navigation system within React Native. Choose the ‘tabs’ option when initializing the project, and Expo will build a simple navigation system.

A StackNavigator is a good way to control screens because it allows them to remain concurrent when swapping between different screens. Each screen will retain its information.

To learn more about technical details check out the React-Navigation Docs.

Building Screens

To create a simple, static screen, you don’t need many moving parts because React Native provides robust components for these already. For example, components like <ScrollView>, <Image>, <Text>, and <Linking> can do most of the lifting on a page that only has to display information and images. A simple screen might look like this:

import React from 'react'; import { ScrollView, StyleSheet } from 'react-native'; export default function HamsterScreen() { return ( <ScrollView style={styles.container}> <Text> Your mother is a hamster! </Text> <Image source={require('../assets/images/hamster.png')} /> </ScrollView> ); } HamsterScreen.navigationOptions = { title: 'Hamster', }; const styles = StyleSheet.create({ container: { flex: 1, paddingTop: 15, backgroundColor: '#fff', }, });

This is just the beginning of learning how to use React Native. Keep an eye out for our upcoming blog post about using React Native with Drupal. In the mean time, watch Designing an App with Drupal and React Native, a Design 4 Drupal session presented by our summer intern developer, Jacob Morin.

When adding custom Analytics events via Google Tag Manger, make sure to set "Non-Interaction Hit" to "True" if you don't want that event to count towards the bounce rate. Otherwise, if the event fires on a page, GA will think you didn't bounce and subsequently set that session's page bounce rate to 0.

The default behavior for Google Tag Manager (GTM) events is for Non-Interaction Hit = False. This is because, normally, if a user is triggering an event on a page, it would imply they are interacting with the page and thus you would not want that to count as a bounce if the user ended their session shortly after.

However, if you set your event to fire on every page automatically (e.g., on page load) you likely would not want that to count as an interaction. In this scenario, you're best to set Non-Interaction Hit = True.

Please note that setting this to True also affects time on page calculations. If Google has no other hit events to go by, it may have a more difficult time calculating time on page.  A "bounce" is a session containing only one interaction hit. 

More information can be found at Google Analytics.

Lots of people in the Drupal community are eager to learn React these days, following Dries's announcement that React is coming to Drupal.

At NEDCamp in 2018 I presented on how to dip your toe into embedding a react application into a Drupal framework (video on drupal.tv).

This is the long-delayed blog post to follow up to the presentation.

Our approach was fundamentally this:

• we wanted to possibly embed multiple React apps on the site eventually, so we wanted to treat our base React libraries as common across the site.
• we needed to marry React routing and Drupal routing so that we could occupy a whole "namespace" of the site
• we wanted Drupal to store all the entities managed by the front-end, so we had to settle on storage and an API

React Libraries

We wrote a small react_libraries module to expose the libraries for React that we thought we would use everywhere and wanted consistent on every site.

Besides the .info.yml file for the module, the only other thing in the module is the libraries' definitions.

# react_libraries.libraries.yml react: js: https://unpkg.com/react@16/umd/react.production.min.js: external: true https://unpkg.com/react-dom@16/umd/react-dom.production.min.js: external: true react-dev: js: https://unpkg.com/react@16/umd/react.development.js: external: true https://unpkg.com/react-dom@16/umd/react-dom.development.js: external: true

All this does is suck in the libraries from CDN, including a prod (react) version and a dev (react-dev) version.

Our smaller apps just depend on this module and then attach the react_libraries/react(-dev) libraries as needed (you'll see that next).

One lesson learned is that we started with create-react-app, so to make this work we had to eject from that and remove the libraries that are normally in the build app bundle. Next time, we will build our app up from scratch rather than using the scaffolding.

Routing

The way React apps work is that they handle the routing by changing the URL with JavaScript and allow the app to deal with what to do given that route. But, as the page isn't refreshing, it's all just one path to Drupal. The problem comes in when a user bookmarks a URL and expects it to work (and it should). To handle this scenario, we assumed a 'namespace' in the routing by declaring /my-react-app/* to belong to our React app. In Drupal 7, this would've "just worked," as any path registered auto-assumes that anything appearing on the URL after that are just arguments to the route. In Drupal 8, this is no longer true, so we have to sort of fake that old behavior.

To do that, we need a custom module. As part of that module, we can define routing--and we tell our route that there is a single argument passed ({react_route}), and we set the default value of that parameter to "" if it is not passed at all (i.e., you navigate to /my-react-app by itself).

# my_react_app.routing.yml my_react_app.overview: path: /my-react-app/{react_route} defaults: _controller: \Drupal\my_react_app\Controller\MyReactAppController::overview _title: 'My React App' react_route: ''

But, alas - this does not match the path /my-react-app/pathpart1/pathpart2 - so this is not complete yet.

Next, we need to create an Inbound Path Processor, by dropping a new class in our module's src/PathProcessor/ folder.

namespace Drupal\my_react_app\PathProcessor;

use Drupal\Core\PathProcessor\InboundPathProcessorInterface;

use Symfony\Component\HttpFoundation\Request;

class MyReactAppPathProcessor implements InboundPathProcessorInterface {

  public function processInbound($path, Request $request) {
    if (strpos($path, '/my-react-app/') === 0) {
      $names = preg_replace('|^\/my-react-app\/|', '', $path);
      $names = str_replace('/',':', $names);
      return "/savant-tools/$names";
    }

    return $path;
  }
} 

What the above code does is strip out the "namespace" part of our route, and then replace all the forward-slashes with colons so that it appears as a single route parameter. Essentially, PHP is just throwing this out anyway, since it's the front-end that will be using this route information in JavaScript.

The Controller

The final missing piece is - well, what DOES Drupal actually serve up for markup when we hit anything at my-react-app/*? That's defined by the Controller that your routing.yml file refers to. Your routing class gets dropped in your module's src/Controller folder.

<?php
namespace Drupal\savant_tools\Controller;

use Drupal\Core\Controller\ControllerBase;

/** 
 * Controller for My React App. 
*/
class MyReactAppController extends ControllerBase {

  /** 
   * Renders the react app. 
   * @return array 
   * The render array. 
  */ 
  public function overview() { 
    $build = [];

    // @TODO - do dev / prod here. (/react or /react-dev) 
    // Ideally, make this configurable somehow. 
    $build['#attached']['library'][] = 'react_libraries/react-dev';
 
    // This is where you attach the additional library from your 
    // module that contains the non-React-libraries code
    $build['#attached']['library'][] = 'my_react_app/actualapp';
 
    // Finally, drop your main mount point for React. 
    // This ID can be whatever you use in your app. 
    $build['#markup'] = '<div id="root"></div>'; 

    return $build; 
  } 
}

Fin!

At this point, you're now free to write that whole slick frontend!

One last thing to mention, another alternative to this is to mount a React application onto a node. Using JD Flynn's module React Mount Node you can simply specify a node, the div ID, and the library you've registered with your React App in it. You will need React fully bundled, or you'll need to attach your react_libraries on every page or through some other mechanism, and the routing isn't handled with as much elegance - but if you have simpler needs, this is a great way to go!

Drupal 8 ships with a custom CKEditor build. This build is configured with a build-config.js file. We recently ran into a situation in which we wanted to override this configuration in order to disable a plugin. There is some information in this build-config.js file about replacing it with a non-minified build for development purposes, but nothing about overriding it. Here is how we did it.

The plugin we wanted to disable was the <a href="https://ckeditor.com/cke4/addon/showborders" target="_blank">Show Table Borders</a> plugin. This is the feature that provides default dotted borders around all table cells while you're editing a table in CKEditor. We wanted to disable that and, instead, just show the table borders as they would be styled on the front-end. Upon inspection of the build-config.js file that Drupal uses, which is located at core/assets/vendor/ckeditor, we found that the plugins key contained showborders: 1. To disable it, we needed to rebuild CKEditor with this line removed.

To do that, we saved a copy of build-config.js to our theme in a similar location: assets/vendor/ckeditor. We removed the line which enables showborders. Then, we went to CKEditor's online <a href="https://ckeditor.com/cke4/builder" target="_blank">Builder</a> and used the Upload build-config.js feature to download a newly generated copy of CKEditor that would exclude the Show Table Borders plugin. We placed the downloaded files in our theme's assets/vendor/ckeditor directory.

The last step is to override Drupal's core CKEditor build from within the theme's info.yml file. Add the following lines (modified for your theme):

libraries-override: core/ckeditor: js: assets/vendor/ckeditor/ckeditor.js: /themes/custom/YOUR_THEME_NAME/assets/vendor/ckeditor/ckeditor.js

Flush the caches and the plugin should be gone!