App React react-app

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

Le applicazioni di esempio sono un ottimo modo per esplorare le funzionalità headless di Adobe Experience Manager (AEM). Questa applicazione React illustra come eseguire query sui contenuti che utilizzano le API GraphQL di AEM utilizzando query persistenti. Il client AEM Headless per JavaScript viene utilizzato per eseguire le query persistenti GraphQL che alimentano l’app.

Visualizza il codice sorgente in GitHub

È disponibile un tutorial completo che descrive come è stata generata l'app React.

Prerequisiti prerequisites

I seguenti strumenti devono essere installati localmente:

Requisiti di AEM

L’applicazione React funziona con le seguenti opzioni di distribuzione di AEM. Tutte le distribuzioni richiedono l'installazione del sito WKND v3.0.0+.

L'applicazione React è progettata per connettersi a un ambiente AEM Publish, tuttavia può creare contenuto da AEM Author se l'autenticazione viene fornita nella configurazione dell'applicazione React.

Come usare

Il codice

Di seguito è riportato un riepilogo di come viene creata l’applicazione React, di come si connette ad AEM Headless per recuperare contenuti utilizzando query persistenti GraphQL e di come vengono presentati tali dati. Il codice completo si trova su GitHub.

Query persistenti

Seguendo le best practice di AEM Headless, l’applicazione React utilizza query persistenti di AEM GraphQL per eseguire query sui dati di avventura. L’applicazione utilizza due query persistenti:

# 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
      }
    }
  }
}

Esegui query persistente GraphQL

Le query persistenti di AEM vengono eseguite tramite HTTP GET, pertanto il client AEM Headless per JavaScript viene utilizzato per eseguire le query GraphQL persistenti su AEM e caricare il contenuto dell'avventura nell'app.

A ogni query persistente corrisponde un hook React useEffect in src/api/usePersistedQueries.js, che chiama in modo asincrono l'endpoint della query persistente AEM HTTP GET e restituisce i dati relativi all'avventura.

Ogni funzione a sua volta richiama aemHeadlessClient.runPersistedQuery(...), eseguendo la query GraphQL persistente.

// 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 };
}

Viste

L’applicazione React utilizza due visualizzazioni per presentare i dati dell’avventura nell’esperienza web.

Variabili di ambiente

Diverse variabili di ambiente sono utilizzate per connettersi a un ambiente AEM. Il valore predefinito si connette ad AEM Publish in esecuzione alle http://localhost:4503. Aggiornare il file .env.development per modificare la connessione AEM:

Richieste proxy di AEM

Quando si utilizza il server di sviluppo Webpack (npm start), il progetto si basa su una configurazione proxy che utilizza http-proxy-middleware. Il file è configurato in src/setupProxy.js e si basa su diverse variabili di ambiente personalizzate impostate in .env e .env.development.

Se ci si connette a un ambiente di authoring AEM, è necessario configurare il metodo di autenticazione corrispondente.

Condivisione delle risorse tra le origini (CORS)

Questa applicazione React si basa su una configurazione CORS basata su AEM in esecuzione nell'ambiente AEM di destinazione e presuppone che l'app React venga eseguita su http://localhost:3000 in modalità di sviluppo. Consulta ladocumentazione sulla distribuzione AEM Headless per ulteriori informazioni su come configurare CORS.