Code Components - Data fetching

SWR

SWR is provided as a native package and can be imported and used for general data fetching. Data returned will be shown in the “Data Fetch” pane under the component preview.

import useSWR from 'swr';

export default function Profile() {
  const { data, error, isLoading } = useSWR(
    'https://my-site.com/api/user',
    fetcher,
  );

  if (error) return <div>failed to load</div>;
  if (isLoading) return <div>loading...</div>;
  return <div>hello {data.name}!</div>;
}

Drupal data

Page and site data

You can access information about the current page with the getPageData utility. Results can be viewed in the Data Fetch pane below the component preview.

import { getPageData } from 'drupal-canvas';

const { pageTitle, breadcrumbs, mainEntity } = getPageData();

Main entity metadata

The main entity is the primary Drupal entity (e.g. article, canvas_page, blog) associated with the current page. Access main entity metadata of the page you are on with getPageData. This can be used to construct JSON:API parameters for requests.

ℹ️ Not every route has a main entity, in that case mainEntity will be null (e.g. front page, /user/login, or inside the Canvas code editor).

If the Code Component is added to a region that may appear on all pages (including pages without a main entity), ensure to check for the existence of mainEntity before trying to access its metadata to avoid JS errors. The example below uses a wrapper component to check for the existence of mainEntity and also checks that mainEntity is an article node before calling the useSWR hook that fetches related articles. If the Code Component will only be used on pages with a main entity, then this check is not necessary.

Example usage that fetches a list of articles but excludes the current article being viewed:

import { getPageData } from 'drupal-canvas';
import { JsonApiClient } from 'drupal-canvas';
import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
import useSWR from 'swr'

const client = new JsonApiClient();

function RelatedArticles({ mainEntity }) {
  const { bundle, entityTypeId, uuid } = mainEntity;
  const { data, error, isLoading } = useSWR(
  [
    'node--article',
    {
      queryString: new DrupalJsonApiParams()
        .addFilter('id', uuid, '<>') // Exclude current article by uuid.
        .getQueryString(),
    },
  ],
  ([type, options]) => client.getCollection(type, options),
  );

   return (...);
}

// Wrapper component to check for mainEntity existence and type before calling a hook since
// hooks cannot be called conditionally (React rules of hooks).
function RelatedArticlesWrapper() {
  const { mainEntity } = getPageData();

  // Return early if there is no mainEntity, or it is not an article node.
   if (
     !mainEntity ||
     mainEntity.entityTypeId !== 'node' ||
     mainEntity.bundle !== 'article'
   ) {
     return null;
  }
  return <RelatedArticles mainEntity={mainEntity} />;
}

export default RelatedArticlesWrapper;

Translations and language switcher

mainEntity carries everything needed to build a language switcher:

• requestedLanguage: the language code requested via the URL (e.g. fr).
• renderedLanguage: the language the content actually rendered in. It falls back to the default translation when the requested language has no translation, so it can differ from requestedLanguage.
• translations: every enabled site language, even when the entity itself is not translatable, so a language switcher is always complete. Empty when the site is monolingual. Each entry has:
  • langcode: the language code (e.g. en, fr).
  • name: the language name in the current display language (e.g. German).
  • nativeName: the language’s own native name (e.g. Deutsch).
  • url: URL to view the entity in this language, resolved according to the site’s configured language negotiation (path prefix, domain, etc.). When the translation is unavailable to the current user, this is the default translation’s URL in that language, so it never discloses anything about the translation itself (such as a translated path alias).
  • translationAvailable: whether the entity has a translation in this language that the current user may view. Unpublished or otherwise inaccessible translations are reported as translationAvailable: false (see note below), so this reflects viewable translations, not raw translation existence.
  • current: whether this is the requested language, even when its content falls back to the default translation.

ℹ️ Languages the entity is not translated into (and translations the current user cannot view, such as an unpublished draft) are still included, with translationAvailable: false. Their url still points to that language’s URL (for example a /fr/ path prefix or an fr.example.com domain, depending on the site’s language negotiation), but the content falls back to the default translation. Neither the list nor the URLs reveal the existence of a translation the current user may not see, and both can vary per user (an editor may see translationAvailable: true where an anonymous visitor sees translationAvailable: false).

Example language switcher:

import { getPageData } from 'drupal-canvas';

function LanguageSwitcher() {
  const { mainEntity } = getPageData();
  if (!mainEntity) {
    return null;
  }
  const { requestedLanguage, renderedLanguage, translations } = mainEntity;

  return (
    <nav>
      {requestedLanguage !== renderedLanguage && (
        <p>Not available in your language; showing {renderedLanguage}.</p>
      )}
      <ul>
        {translations.map(
          ({ langcode, nativeName, url, translationAvailable, current }) => (
            <li key={langcode}>
              {current ? (
                <span lang={langcode} aria-current="true">
                  {nativeName}
                </span>
              ) : (
                <a href={url} lang={langcode} hrefLang={langcode}>
                  {nativeName}
                  {!translationAvailable && ' (not translated)'}
                </a>
              )}
            </li>
          ),
        )}
      </ul>
    </nav>
  );
}

export default LanguageSwitcher;

You can also access site information with the getSiteData utility

import { getSiteData } from 'drupal-canvas';

const { siteName } = getSiteData().branding;

JSON:API

drupal-canvas provides the JSON:API client automatically configured with a baseUrl as well as DefaultSerializer for deserialization. Drupal core’s JSON:API module must be enabled to use this client.

The associated parameter helper package is also included as a native package.

import { JsonApiClient } from 'drupal-canvas';
import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
import useSWR from 'swr';

const client = new JsonApiClient();

export default function List() {
  const { data, error, isLoading } = useSWR(
    [
      'node--article',
      {
        queryString: new DrupalJsonApiParams()
          .addInclude(['field_tags'])
          .getQueryString(),
      },
    ],
    ([type, options]) => client.getCollection(type, options),
  );

  if (error) return 'An error has occurred.';
  if (isLoading) return 'Loading...';
  return (
    <ul>
      {data.map((article) => (
        <li key={article.id}>{article.title}</li>
      ))}
    </ul>
  );
}

You can override the baseUrl and any default options:

const client = new JsonApiClient('https://drupal-api-demo.party', {
  serializer: undefined,
  cache: undefined,
});

Tip

For development outside of Drupal Canvas, use @drupal-canvas/vite-plugin to automatically provide the necessary configuration based on environment variables.

Note

When working with Code Components outside of Drupal Canvas, you may need to configure CORS headers on your Drupal site to allow JSON:API requests from your development environment.

Helper utilities

Utility functions for working with JSON:API and core APIs are provided in the drupal-canvas package.

Examples

Fetching nodes with JSON:API

The following example fetches nodes using a preconfigured version of the JSON:API client from the Drupal API Client, and outputs links to each of them using the getNodePath utility from the drupal-canvas package, which will return the path alias if exists, or fall back to the /node/[nid] path.

import { getNodePath, JsonApiClient } from 'drupal-canvas';
import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
import useSWR from 'swr';

const Articles = () => {
  const client = new JsonApiClient();
  const { data, error, isLoading } = useSWR(
    [
      'node--article',
      {
        queryString: new DrupalJsonApiParams()
          .addSort('created', 'DESC')
          .getQueryString(),
      },
    ],
    ([type, options]) => client.getCollection(type, options),
  );

  if (error) return 'An error has occurred.';
  if (isLoading) return 'Loading...';
  return (
    <ul>
      {data.map((article) => (
        <li key={article.id}>
          <a href={getNodePath(article)}>{article.title}</a>
        </li>
      ))}
    </ul>
  );
};

export default Articles;

Using the JSON:API Menu Items module

This example builds a navigation menu using the JSON:API Menu Items module:

import { JsonApiClient, sortMenu } from 'drupal-canvas';
import useSWR from 'swr';

const client = new JsonApiClient();

const Navigation = () => {
  const { data, isLoading, error } = useSWR(
    ['menu_items', 'main'],
    ([type, resourceId]) => client.getResource(type, resourceId),
  );
  if (error) return 'An error has occurred.';
  if (isLoading) return 'Loading...';

  const menu = sortMenu(data);

  return (
    <ul>
      {menu.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
};

export default Navigation;

Using Drupal core’s linkset endpoint

You can also build a navigation menu using Drupal core’s linkset endpoint.

import { sortLinksetMenu } from 'drupal-canvas';
import useSWR from 'swr';

const Navigation = () => {
  const { data, isLoading, error } = useSWR(
    '/system/menu/main/linkset',
    async (url) => {
      const response = await fetch(url);
      return response.json();
    },
  );
  if (error) return 'An error has occurred.';
  if (isLoading) return 'Loading...';

  const menu = sortLinksetMenu(data);

  return (
    <ul>
      {menu.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
};

export default Navigation;