Utilizzare componenti personalizzati per eseguire il rendering di un modulo headless developing-for-headless-forms-using-your-own-components

In Headless Adaptive Forms puoi creare e implementare componenti personalizzati per definire l’aspetto e le funzionalità dei moduli. Anche se i componenti predefiniti forniscono un comportamento standard, potrebbe essere necessario specificare elementi o interazioni dell’interfaccia utente, ad esempio un componente personalizzato "Annuncio" o un campo specifico "Firma a mano".

Questo articolo ti guida attraverso la creazione di un componente React personalizzato e la mappatura sul tuo modulo adattivo headless.

​1. Creare un componente React personalizzato

Innanzitutto, crea il componente React che eseguirà il rendering del campo modulo. Questo componente può utilizzare qualsiasi libreria React (come l’interfaccia utente Materiali, Progettazione formiche o stili personalizzati).

Ad esempio, creiamo un componente Annuncio personalizzato che esegue il rendering di un messaggio di sola lettura con uno stile specifico.

import React from 'react';
import { useRuleEngine } from '@aemforms/af-react-renderer';
import { FieldJson, State } from '@aemforms/af-core';

const Announcement = function (props: State<FieldJson>) {
    // The useRuleEngine hook connects the component to the form logic
    const [state, handlers] = useRuleEngine(props);

    if (!state.visible) {
        return null;
    }

    return (
        <div className="custom-announcement" style={{ border: '1px solid #ccc', padding: '10px', backgroundColor: '#f9f9f9' }}>
            <h3>{state?.label?.value}</h3>
            <p>{state?.default}</p>
        </div>
    );
}

export default Announcement;

​2. Mappare il componente personalizzato

Per utilizzare il componente personalizzato, è necessario mapparlo nel file mappings.ts. Il runtime Forms headless utilizza questo mapping per determinare quale componente React eseguire il rendering per ogni campo nel formato JSON.

Esistono due modi principali per mappare i componenti: per Tipo campo o per Tipo risorsa.

Mappatura per tipo di campo

Il mapping standard è basato sulla proprietà fieldType nel JSON del modulo (ad esempio, text-input, checkbox, button). Questa opzione è utile quando si desidera sostituire tutte le istanze di un componente standard con la versione personalizzata.

import { mappings } from "@aemforms/af-react-components";
import Announcement from "../components/Announcement";

const customMappings: any = {
  ...mappings,
  "text-input": Announcement // This would replace ALL text-input fields (use with caution)
};

export default customMappings;

Mappatura per tipo di risorsa (componenti personalizzati)

Se hai creato un componente personalizzato in AEM (ad esempio, un componente "Annuncio" che estende un componente Testo standard) e vuoi eseguire il rendering di solo tale componente in modo diverso nell'app React, devi mapparlo in base al suo Tipo risorsa o a un identificatore univoco.

Questo approccio consente di eseguire normalmente il rendering dei componenti di testo standard, mentre il componente personalizzato "Annuncio" utilizza l’implementazione di React specializzata.

import { mappings } from "@aemforms/af-react-components";
import Announcement from "../components/Announcement";

const customMappings: any = {
  ...mappings,
  // Map by resource type or custom identifier
  "my-project/components/announcement": Announcement
};

export default customMappings;

Nota: assicurarsi che il modello AEM Form esporti il :type o l'identificatore corretto corrispondente alla chiave utilizzata in mappings.ts.

​3. Applicare le mappature

Infine, assicurati che l’istanza del modulo headless utilizzi queste mappature personalizzate.

import React from 'react';
import { AdaptiveForm } from '@aemforms/af-react-renderer';
import customMappings from './utils/mappings';
import formJSON from './form-def.json';

function App() {
  return (
    <AdaptiveForm
      formJson={formJSON}
      mappings={customMappings}
    />
  );
}

export default App;

Seguendo questi passaggi, puoi estendere le funzionalità del Forms adattivo headless con componenti che soddisfano i requisiti di progettazione e funzionali specifici.