Custom Field

I custom field consentono alle organizzazioni di estendere le entità di Riseact con campi personalizzati, senza modificare lo schema di base. Possono essere usati per raccogliere informazioni aggiuntive sui sostenitori o sulle donazioni, e possono essere esposti nel form di donazione direttamente dalla configurazione della campagna.

Concetti chiave

I custom field si basano su due oggetti distinti:

• CustomFieldDefinition - La definizione del campo: nome, tipo, opzioni. È uno schema condiviso a livello di organizzazione per una specifica entità.
• CustomField - Il valore effettivo salvato su una specifica istanza di sostenitore o donazione.

Entità supportate

I custom field possono essere definiti per due entità:

Tipi di campo

Chiave del campo (key)

La chiave (key) è un identificatore univoco per il campo all'interno dell'organizzazione, su tutte le entità. Viene generata automaticamente dal nome del campo al momento della creazione (slugificando il nome, es. "Data di nascita" → "data-di-nascita"). Se la chiave generata è già in uso, viene aggiunto un suffisso numerico incrementale (es. "data-di-nascita-2").

La chiave è immutabile dopo la creazione e viene usata per referenziare il campo nelle configurazioni di campagna e nei payload dei checkout.

Integrazione con le campagne

I custom field di tipo supporter possono essere inclusi nella configurazione di una campagna tramite i campi shown_fields e required_fields, usando la chiave del campo. In questo modo il campo comparirà nel form di donazione della campagna:

• shown_fields - Il campo è visibile nel form
• required_fields - Il campo è visibile e obbligatorio

Quando si elimina una definizione di custom field, la chiave viene automaticamente rimossa da tutte le configurazioni di campagna che la referenziano.

Nelle notifiche e nei documenti

I valori dei custom field del sostenitore e della donazione sono disponibili nei template delle notifiche (email e SMS, compresa la mail di ringraziamento) e dei documenti generati, nel dizionario customfields, indicizzato per chiave:

Hai preso {{ customfields['numero-scarpe'] }} scarpe.

Un campo senza valore, o non disponibile nel contesto (es. un campo donazione in una notifica che riguarda solo il sostenitore), produce una stringa vuota. Per mostrare un testo solo quando il campo è valorizzato:

{% if customfields['numero-scarpe'] %}
  scarpe prese: {{ customfields['numero-scarpe'] }}
{% endif %}

Archivio e cancellazione

Le definizioni di custom field non vengono cancellate fisicamente: vengono archiviate (archived: true). I valori già salvati sui sostenitori e sulle donazioni rimangono invariati. I campi archiviati non vengono restituiti dalle query di default (a meno che non si filtri esplicitamente con archived: true).

Checkout

Durante un checkout, i valori dei custom field raccolti nel form vengono salvati nei campi supporter_custom_fields e donation_custom_fields del checkout (come JSON), prima ancora che il sostenitore o la donazione vengano creati. Questo garantisce che i dati non vadano persi anche in caso di checkout non completato.

API GraphQL

Query

Lista definizioni:

query {
  customfieldDefinitions(filters: { entity: supporter }) {
    id
    name
    key
    type
    options
    position
    archived
  }
}

Singola definizione:

query {
  customfieldDefinition(id: 1) {
    id
    name
    key
    type
  }
}

Mutations

Crea una definizione:

mutation {
  customfieldDefinitionCreate(data: {
    entity: supporter,
    name: "Professione",
    description: "Professione del sostenitore",
    type: text
  }) {
    customFieldDefinition {
      id
      key
    }
    userErrors {
      field
      message
    }
  }
}

Crea un campo di tipo select:

mutation {
  customfieldDefinitionCreate(data: {
    entity: donation,
    name: "Destinazione fondi",
    description: null,
    type: select,
    options: ["Progetto A", "Progetto B", "Progetto C"]
  }) {
    customFieldDefinition {
      id
      key
      options
    }
    userErrors {
      field
      message
    }
  }
}

Aggiorna una definizione:

mutation {
  customfieldDefinitionUpdate(id: 1, data: {
    name: "Professione aggiornata",
    position: 2
  }) {
    customFieldDefinition {
      id
      name
    }
    userErrors {
      field
      message
    }
  }
}

Archivia (elimina) una definizione:

mutation {
  customfieldDefinitionDelete(id: 1) {
    customFieldDefinition {
      id
      archived
    }
    userErrors {
      field
      message
    }
  }
}

Fonte: https://dev.riseact.org/docs/guides/custom-fields. Copia automatica da dev.riseact.org: non modificare qui, le modifiche vanno fatte sulla documentazione Docusaurus.