Crochets d'entités

Présentation

Les crochets d'entité sont des crochets React générés qui fournissent un accès simplifié de typage fort aux données et à la logique gérées par les fournisseurs d'entité. Les composants enfants du fournisseur d'entité peuvent tirer parti de ces crochets pour lire facilement le contexte React de l'entité. Cela permet aux composants d'accéder à l'état actuel de React, aux informations relatives au schéma et aux résultats de validation. Disponible à la fois au niveau de l'entité et au niveau du champ individuel.

Note: Les crochets d'entité pour les entités JobLines présentent des différences majeures dans leur comportement. Pour en savoir plus, reportez-vous à la page Utilisation de JobLines.

Utilisation de crochets d'entité

Comme expliqué dans le cahier des charges de l'API des extensions d'interface utilisateur du SDK Digital, le générateur de SDK Jutro crée un répertoire pour chaque entité utilisée par chacune des API disponibles dans un SDK ayant été généré. Vous pouvez importer les crochets d’entité à partir du chemin racine du répertoire des entités.

Ils sont nommés selon le modèle use<entity-name>, et doivent être utilisés par les composants enfants de leur fournisseur d'entité associé.

// import path 'src/generated/JutroUtils/<sdk-name>/<api-name>/<entity-name>'
// for a "Contact" entity in the "account" API of an SDK named "PcSDK"
import {
  ContactProvider,
  useContact,
} from 'src/generated/JutroUtils/PcSDK/account/Contact';

export const ContactPage = (): JSX.Element => (
  <ContactProvider>
    <ContactForm />
  </ContactProvider>
);

const ContactForm = (): JSX.Element => {
  const {
    state,
    setState,
    schema,
    validationResult,
    showSchemaValidationErrors,
    fields,
  } = useContact();
  
  // ...
};

Valeur renvoyée

Les crochets d'entité renvoient un seul objet ayant les propriétés suivantes.

state et setState

La propriété state est une variable d'état React qui stocke les données actuelles de l'entité. La propriété setState est une fonction de définition d'état React qui peut être utilisée pour modifier state. Elle utilise le type d'entité correspondant disponible dans le SDK Digital.

Note: La modification de l'entité state déclenche le fournisseur d'entité qui va réexécuter le schéma d'entité et les fonctions de validation.

L'exemple ci-dessous utilise state et setState pour afficher une entrée contrôlée pour le champ displayName d'une entité « Contact ».

// ...
  const { state, setState } = useContact();

  return (
    <label>
      Enter your name:
      <input
        type="text"
        value={state.displayName}
        onChange={(e) =>
          setState((prev) => ({ ...prev, displayName: e.target.value }))
        }
      />
    </label>
  );
};

schema

La propriété schema est la valeur renvoyée lors de l'appel de la fonction du SDK Digital getEntitySchema.

Note: Le fournisseur d'entité exécute la fonction de schéma pour l'entité correspondante à chaque rendu, en transmettant le state actuel comme argument, et en s'assurant que les règles de schéma sont réévaluées avec cet état.

Pour en savoir plus sur les schémas d'entité, reportez-vous à la documentation du SDK Digital.

validationResult

Cette propriété contient le résultat de l'exécution de la fonction de validation de l'entité disponible dans le SDK Digital.

Note: Le fournisseur d'entité exécute la fonction de validation pour l'entité correspondante à chaque rendu, en s'assurant que le validationResult est à jour avec le state actuel.

Comme expliqué dans la documentation du SDK Digital, l'objet validationResult indique si l'entité isValid après l'application de la validation du schéma JSON au state actuel, et fournit une série de errors au cas où elle ne serait pas valide.

showSchemaValidationErrors

La propriété showSchemaValidationErrors provient directement de la propriété définie par l'utilisateur du fournisseur d'entité.

Il s'agit d'une valeur booléenne utilisée par les composants de champ générés pour basculer l'affichage des erreurs de validation. L'utilisation de showSchemaValidationErrors en association avec validationResult vous permettra de synchroniser vos composants personnalisés avec ce comportement des composants de champ générés.

fields

Dans ces cas, une propriété fields sera disponible :

1. Le schéma d'entité est un type JSONSchemaWithFields.
2. Le schéma d'entité est un JSONSchemaGW et l'indicateur dangerouslyForceEntityFieldGeneration a été utilisé lors de la génération.
3. Le schéma d'entité est un type JSONSchemaCoverage.

Cette propriété est un objet qui possède autant de propriétés que d'objets JSONSchemaField définis dans le schéma, en utilisant le nom du champ comme clé.

const { fields } = useContact();
const { displayName, email, phoneNumber } = fields;

Note: Pour les entités de type JSONSchemaCoverage, la valeur de la propriété selected sera ajoutée à l'objet du champ renvoyé.

Les entités JobLine peuvent également générer des champs supplémentaires. Pour en savoir plus, reportez-vous à la page Utilisation de JobLines.

En tant que valeur, chacune de ces propriétés contient un objet contenant des informations pertinentes sur le champ correspondant, extraites des données disponibles dans le fournisseur d'entité. Vous trouverez plus d'informations sur le contenu de cet objet dans la section Propriétés au niveau du champ.

Propriétés au niveau du champ

Ces propriétés fournissent un accès direct aux informations et à la logique relatives aux champs déjà disponibles au niveau de l'entité. Cela simplifie l'accès aux détails spécifiques aux champs en supprimant la nécessité de parcourir manuellement la structure de données de l'entité.

state et setState

Ces valeurs sont équivalentes aux propriétés state et setState au niveau de l'entité, mais elles ciblent un seul champ de l'état à l'aide de la définition du type de SDK Digital du champ correspondant.

Par exemple, nous pouvons réécrire l'exemple de code en nous basant sur la section state et setState au niveau de l'entité pour utiliser le niveau du champ state et setState comme ceci :

// ...
  const { fields } = useContact();
  const { displayName } = fields;
  const { state, setState } = displayName;

  return (
    <label>
      Enter your name:
      <input
        type="text"
        value={state}
        onChange={(e) => setState(e.target.value)}
      />
    </label>
  );
};

errors

La propriété du champ errors est une version filtrée de la série errors renvoyée par le validationResult de l'entité. Seuls les membres de cette série qui se rapportent au champ spécifique seront inclus.

Vous pouvez l'utiliser pour obtenir les messages d'erreur pertinents pour le champ.

fieldSchema

La propriété du champ fieldSchema est un raccourci vers l'attribut properties.fieldName du schéma de l'entité.

Cela équivaut à accéder à la propriété correspondante du schema de l'entité.

const { schema } = usePhoneNumber();
const numberSchema = schema.properties.number;
//////
const { fields } = usePhoneNumber();
const { number } = fields;
const { fieldSchema: numberSchema } = number;

Propriétés d'entrée HTML

Il s'agit de raccourcis pratiques qui permettent un mappage direct entre les informations disponibles dans le schema de l'entité et un ensemble d'attributs standard HTML pour les entrées, ce qui réduit ainsi la quantité de logique de transformation nécessaire pour afficher les champs de saisie.

• disabled est défini sur true si le champ est marqué comme x-gw-forbidden.
• label est la valeur de schema.properties.<field-name>.title.
• title est la valeur de schema.properties.<field-name>.description.
• readOnly est la valeur de schema.properties.<field-name>.readOnly.
• required est défini sur true si le champ est marqué avec l'une des propriétés x-gw-requiredFor.
• maxLength est la valeur de la propriété x-gw-maximum pour ce champ, le cas échéant.
• minLength est la valeur de la propriété x-gw-maximum pour ce champ, le cas échéant.

// ...
  const { fields } = useContact();
  const { displayName } = fields;
  const {
    state,
    setState,
    required,
    disabled,
    label,
    title,
    readOnly,
    maxLength,
    minLength,
  } = displayName;

  return (
    <label>
      {label}
      <input
        type="text"
        value={state}
        onChange={(e) => setState(e.target.value)}
        required={required}
        disabled={disabled}
        title={title}
        readOnly={readOnly}
        maxLength={maxLength}
        minLength={minLength}
      />
    </label>
  );
};