Api Hours

Api Hours (ou "Multi-horaires") est le module de gestion des horaires d'ouverture du système d'information touristique Apidae. Il permet aux utilisateurs de la plateforme de consulter & saisir des horaires d'ouverture associés aux différents types d'objets touristiques.

Le formulaire web Api Hours est une solution clés en main pour intégrer un formulaire de saisie d'horaires au sein d'un formulaire web existant. Il applique automatiquement la configuration et les contrôles relatifs aux types d'objets Apidae, et vous retourne la saisie des horaires d'ouverture directement dans le format attendu par l'API d'écriture Apidae.
Le mode opératoire ci-dessous décrit les différentes étapes à réaliser pour le mettre en oeuvre.

Intégration - Mode opératoire

1. Référencer les fichiers bundle.js et style.css dans votre page web

Le fichier style.css fournit des styles de base pour le formulaire. Vous pouvez personnaliser le rendu via les paramètres d'initialisation du formulaire, ou en introduisant des styles CSS complémentaires.


  <head>
    ...
    <link href="https://form.apihours.apidae-tourisme.com/0.6.0/styles.css" rel="stylesheet"/>
    ...
  </head>
  <body>
    ...
    <script type="text/javascript" src="https://form.apihours.apidae-tourisme.com/0.6.0/bundle.js"></script>
  </body>

2. Intégrer le formulaire ApiHours au sein de votre formulaire

L'intégration ci-dessous est fournie à titre d'exemple, pour une période d'ouverture unique avec date de début et date de fin.


  <form>
    ...
    <h3>Ouverture</h3>

    <label>Début :</label><input type="date" name="start_date"/>
    <label>Fin :</label><input type="date" name="end_date"/>
    <button type="button" onclick="openApiHours()">Saisie des horaires</button>
    <input type="hidden" name="time_periods"/>
    ...
  </form>

Note : si vous avez besoin d'initialiser le champ de votre formulaire avec une éventuelle saisie ApiHours existante, vous pouvez appeler la fonction asynchrone apihours.loadApiHoursOpening(externalId) où externalId est l'identifiant technique de la période d'ouverture.
Si une saisie ApiHours existe pour cette période, elle sera transmise comme valeur de retour au format JSON (via une promesse JS).

3. Mettre en place le code d'appel au formulaire ApiHours

Les paramètres d'initialisation "nom de l'offre" ainsi qu'un objet contenant des valeurs "date de début", "date de fin" et "identifiant de période" OU "type d'offre" sont obligatoires. Des paramètres complémentaires vous permettent de personnaliser davantage le fonctionnement du formulaire.


  <script>
    ...
    const paramsWithType = {startDate: '2022-01-01', endDate: '2022-12-31', externalType: 'PATRIMOINE_NATUREL'};
    // Variante avec identifiant de période
    // const paramsWithId = {startDate: '2022-01-01', endDate: '2022-12-31', externalId: '1234'};

    function openApiHours() {
      openApiHoursForm('Nom offre', paramsWithType, {
        onSubmit: function(timePeriods) {
          document.querySelector("input[name='time_periods']").value = timePeriods;
        },
        styles: {
          mainBackground: '#ffd1b3',
          mainColor: '#3a2929',
          altBackground: '#ff943c',
          altColor: '#ffffff',
          fontFamily: 'Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace, serif',
          headerImage: 'none'
        }
      });
    }
    ...
  </script>

4. Exploiter la valeur de retour pour la transmettre à l'API d'écriture Apidae.

Voir la documentation développeur Apidae pour davantage d'informations sur le format attendu.

Exemple d'intégration

Le formulaire ci-dessous illustre les différentes étapes de mise en oeuvre de la saisie ApiHours via un exemple interactif.

Ouverture

Début : Fin :

Horaires d'ouverture générés au format JSON :

Effectuez une saisie pour prévisualiser les données.