Aplicativo React react-app

[AEM Headless as a Cloud Service]{class="badge informative"}

Aplicativos de exemplo são uma ótima maneira de explorar as capacidades headless do Adobe Experience Manager (AEM). Este aplicativo React demonstra como consultar conteúdo usando as APIs do GraphQL do AEM usando consultas persistentes. O AEM Headless Client para JavaScript é usado para executar as consultas persistentes do GraphQL que alimentam o aplicativo.

Exibir o código-fonte no GitHub

Um tutorial passo a passo completo que descreve como este aplicativo React foi compilado está disponível.

Pré-requisitos prerequisites

As seguintes ferramentas devem ser instaladas localmente:

Requisitos do AEM

O aplicativo React funciona com as seguintes opções de implantação de AEM. Todas as implantações exigem que o WKND Site v3.0.0+ esteja instalado.

O aplicativo React foi projetado para se conectar a um ambiente AEM Publish, no entanto, ele pode obter conteúdo do autor do AEM se a autenticação for fornecida na configuração do aplicativo React.

Como usar

O código

Abaixo está um resumo de como o aplicativo React é criado, como ele se conecta ao AEM Headless para recuperar conteúdo usando consultas persistentes do GraphQL e como esses dados são apresentados. O código completo pode ser encontrado no GitHub.

Consultas persistentes

Seguindo as práticas recomendadas do AEM Headless, o aplicativo React usa consultas persistentes do AEM GraphQL para consultar dados de aventura. O aplicativo usa duas consultas persistentes:

# Retrieves a list of all Adventures
#
# Optional query variables:
# - { "offset": 10 }
# - { "limit": 5 }
# - {
#    "imageFormat": "JPG",
#    "imageWidth": 1600,
#    "imageQuality": 90
#   }
query ($offset: Int, $limit: Int, $sort: String, $imageFormat: AssetTransformFormat=JPG, $imageWidth: Int=1200, $imageQuality: Int=80) {
  adventureList(
    offset: $offset
    limit: $limit
    sort: $sort
    _assetTransform: {
      format: $imageFormat
      width: $imageWidth
      quality: $imageQuality
      preferWebp: true
  }) {
    items {
      _path
      slug
      title
      activity
      price
      tripLength
      primaryImage {
        ... on ImageRef {
          _path
          _dynamicUrl
        }
      }
    }
  }
}

# Retrieves an Adventure Fragment based on it's unique slug.
#
# Required query variables:
# - {"slug": "bali-surf-camp"}
#
# Optional query variables:
# - {
#     "imageFormat": "JPG",
#     "imageSeoName": "my-adventure",
#     "imageWidth": 1600,
#     "imageQuality": 90
#   }
#
# This query returns an adventure list but since the the slug property is set to be unique in the Content Fragment Model, only a single Content Fragment is expected.

query ($slug: String!, $imageFormat:AssetTransformFormat=JPG, $imageSeoName: String, $imageWidth: Int=1200, $imageQuality: Int=80) {
  adventureList(
    filter: {slug: {_expressions: [{value: $slug}]}}
    _assetTransform: {
      format: $imageFormat
      seoName: $imageSeoName
      width: $imageWidth
      quality: $imageQuality
      preferWebp: true
  }) {
    items {
      _path
      title
      slug
      activity
      adventureType
      price
      tripLength
      groupSize
      difficulty
      price
      primaryImage {
        ... on ImageRef {
          _path
          _dynamicUrl
        }
      }
      description {
        json
        plaintext
        html
      }
      itinerary {
        json
        plaintext
        html
      }
    }
    _references {
      ... on AdventureModel {
        _path
        slug
        title
        price
        __typename
      }
    }
  }
}

Executar consulta persistente do GraphQL

As consultas persistentes do AEM são executadas por HTTP GET e, portanto, o cliente AEM Headless do JavaScript é usado para executar as consultas persistentes do GraphQL AEM em relação ao e carregar o conteúdo de aventura no aplicativo.

Cada consulta persistente tem um gancho React useEffect correspondente em src/api/usePersistedQueries.js, que chama de forma assíncrona o ponto de extremidade da consulta persistente AEM HTTP GET e retorna os dados de aventura.

Cada função, por sua vez, invoca o aemHeadlessClient.runPersistedQuery(...), executando a consulta persistente do GraphQL.

// src/api/usePersistedQueries.js

/**
 * React custom hook that returns a list of adevntures by activity. If no activity is provided, all adventures are returned.
 *
 * Custom hook that calls the 'wknd-shared/adventures-all' or 'wknd-shared/adventures-by-activity' persisted query.
 *
 * @returns an array of Adventure JSON objects, and array of errors
 */
export function useAdventuresByActivity(adventureActivity, params = {}) {
  ...
  let queryVariables = params;

  // If an activity is provided (i.e "Camping", "Hiking"...) call wknd-shared/adventures-by-activity query
  if (adventureActivity) {
    // The key is 'activity' as defined in the persisted query
    queryVariables = { ...queryVariables, activity: adventureActivity };

    // Call the AEM GraphQL persisted query named "wknd-shared/adventures-by-activity" with parameters
    response = await fetchPersistedQuery("wknd-shared/adventures-by-activity", queryVariables);
  } else {
    // Else call the AEM GraphQL persisted query named "wknd-shared/adventures-all" to get all adventures
    response = await fetchPersistedQuery("wknd-shared/adventures-all", queryVariables);
  }

  ...
}

...
/**
 * Private function that invokes the AEM Headless client.
 *
 * @param {String} persistedQueryName the fully qualified name of the persisted query
 * @param {*} queryParameters an optional JavaScript object containing query parameters
 * @returns the GraphQL data or an error message
 */
async function fetchPersistedQuery(persistedQueryName, queryParameters) {
  let data;
  let err;

  try {
    // AEM GraphQL queries are asynchronous, either await their return or use Promise-based .then(..) { ... } syntax
    const response = await aemHeadlessClient.runPersistedQuery(
      persistedQueryName,
      queryParameters
    );
    // The GraphQL data is stored on the response's data field
    data = response?.data;
  } catch (e) {
    // An error occurred, return the error messages
    err = e
      .toJSON()
      ?.map((error) => error.message)
      ?.join(", ");
    console.error(e.toJSON());
  }

  return { data, err };
}

Exibições

O aplicativo React usa duas visualizações para apresentar os dados de aventura na experiência da web.

Variáveis de ambiente

Várias variáveis de ambiente são usadas para se conectar a um ambiente AEM. O padrão se conecta ao AEM Publish em execução em http://localhost:4503. Atualize o arquivo .env.development para alterar a conexão AEM:

Solicitações de Proxy AEM

Ao usar o servidor de desenvolvimento do webpack (npm start), o projeto depende de uma configuração de proxy usando http-proxy-middleware. O arquivo está configurado em src/setupProxy.js e depende de várias variáveis de ambiente personalizadas definidas em .env e .env.development.

Se você estiver se conectando a um ambiente de autor AEM, o método de autenticação correspondente precisará ser configurado.

Compartilhamento de recursos entre origens (CORS)

Este aplicativo React depende de uma configuração CORS baseada em AEM sendo executada no ambiente AEM de destino e presume que o aplicativo React é executado em http://localhost:3000 no modo de desenvolvimento. Revise adocumentação de implantação do AEM Headless para obter mais informações sobre como configurar o CORS.