Documentation technique

Aspects

Les aspects permettent de saisir des informations dédiées à des cibles de communication spécifiques. Ces informations sont fournies en complément / surcharge des informations dites « standard » de la fiche principale.

Il est important de noter les règles suivantes :

  • Les aspects sont facultatifs ; ils ne sont pas systématiquement saisis (soit pour des raisons de ressources, soit pour des raisons d’intérêt). Seule est assurée la saisie de l’objet principal.
  • Les aspects sont saisis que si des informations spécifiques sont à fournir. Exemple, une balade en raquette ne possède généralement pas d’aspect hiver puisque son axe de présentation par défaut sera relatif à l’hiver.
  • De ce fait, il ne faut pas utiliser la présence d’un aspect pour juger de la pertinence d’un objet pour un public particulier. Exemple : les balades en raquette ne possèdent pas d’aspect hiver, mais elles sont pertinentes pour un site hiver. Pour la sélection de l’offre, il faut se reposer de manière générale sur des sélections spécifiques (qui utilisent par exemple des critères activité ou public).

Principe général

Les aspects permettent de définir du contenu spécifique sur un objet, en surchargeant certains champs. Les différents aspects disponibles sont :

  • HIVER : pour les informations de l’objet à exploiter en hiver,
  • ETE : pour les informations de l’objet à exploiter en été,
  • HANDICAP : pour les informations relatives au tourisme pour les personnes handicapées,
  • TOURISME_AFFAIRES : pour les informations relatives au tourisme d’affaires.
  • GROUPES : pour les informations relatives aux groupes de personnes.
  • PRESTATAIRE_ACTIVITES : pour les informations spécifiques aux activités proposées par un objet touristique. Exemple, un restaurateur proposer des cours de cuisine et d’oenologie, catégorisés dans les ACTIVITE. Cet aspect contiendra des informations (descriptif, images, …) centrée sur ces cours plutôt que sur la restauration.

Un objet peut seulement implémenter 1 aspect de chaque type.

Attention, les aspects ne sont pas des objets complets qui se substituent à l’objet dit « Standard ». Les aspects permettent simplement de surcharger certains champs de l’objet standard afin de définir du contenu qui aura du sens, et qui peut être exploité dans certaines circonstances. Il n’y a aucun automatisme concernant l’exploitation du contenu des aspect. Un projet qui récupère un objet peut exploiter ses aspects comme il l’entend.

Cas d’usage des aspects

Réalisation d’un site Hiver

Il est nécessaire de créer des sélections spécifiques contenant l’offre à mettre en avant. Lors des affichages, l’aspect hiver sera exploité de manière systématique

Mise en avant des activités et de leur prestataire

Dans le site, la section dédiée aux activités met en avant le prestataire (de manière à mettre en avant les autres activités proposées, …). Dans ce cas, l’aspect PRESTATAIRE_ACTIVITES est à favoriser. L’utilisation de l’aspect est alors décidé par la logique de navigation. Si on consulte une fiche restaurant après une recherche de restaurant, l’aspect standard est utilisé. Si on consulte une fiche restaurant déclarée en prestataire d’une activité, on privilégie alors l’aspect PRESTATAIRE_ACTIVITE si présent.

Autres cas

D’autres idées, d’autres besoins ; vous voulez vérifier que votre utilisation des aspects est cohérente avec les règles du réseau Apidae. N’hésitez pas à nous contacter.

Format JSON

Les aspects sont regroupés dans le champ aspects. Ce champ est un tableau JSON d’aspects, ayant chacun la structure suivante :

aspect

  • description : le type de l’aspect parmi HIVER, ETE, HANDICAP, TOURISME_AFFAIRES et GROUPES.
  • type : chaîne de caractères.
  • exemple :
"aspect" : "HIVER"

champsAspect

  • description : la liste des champs qui sont surchargés par l’aspect.
  • type : liste de chaînes de caractères.
  • remarque : ce champ permet également de savoir quels champs ont été surchargés avec des valeurs vides. Les champs avec une valeur vide n’apparaissant pas dans le flux, il est important d’exploiter champsAspect, et de ne pas se baser uniquement sur le contenu de l’aspect. Voir champs vides.
  • exemple :
"champsAspect" : [ "presentation.descriptifDetaille", "localisation.environnements" ]

Contenu des champs surchargées

Après les champs aspect et champsAspect, on trouve le contenu des champs surchargés, avec une structure similaire à l’objet touristique « Standard ».

Exemple d’aspect :

"aspects" : [ {
    "aspect" : "HIVER",
    "champsAspect" : [ "presentation.descriptifCourt", "presentation.descriptifDetaille", "localisation.environnements" ],
    "presentation" : {
      "descriptifCourt" : {
        "libelleFr" : "En hiver, notre gîte offre un panorama magnifique..."
      }
    },
    "localisation" : {
      "environnements" : [ {
        "elementReferenceType" : "Environnement",
        "id" : 147,
        "libelleFr" : "Lac ou plan d'eau à moins de 300 m",
        "ordre" : 13,
        "description" : "300 m maxi"
      }, {
        "elementReferenceType" : "Environnement",
        "id" : 173,
        "libelleFr" : "En ville",
        "ordre" : 2
      } ],
      "environnementsRemove" : [ {
        "elementReferenceType" : "Environnement",
        "libelleFr" : "Gare routière à moins de 500 m"
      } ]
    },
  } ],

Eléments de référence

Les champs d’éléments référence sont présentés différement sur les aspects. Pour ces champs, les aspects n’autorisent que la suppression d’éléments par rapport à l’objet standard. Chaque champ d’élements de référence, est donc décomposé en deux champs sur l’aspect :

  • Le contenu du champ sur l’aspect, avec potentiellement certains éléments de référence retirés par rapport à l’objet standard.
  • La liste des éléments de référence retirés par rapport à l’objet standard, s’il y en a. Ce champ est nommé avec le nom du champ original, suffixé avec le mot-clé « Remove ».

Il est conseillé d’exploiter de manière directe la liste des éléments de référence (dans notre exemple, le champ environnements). La liste *Remove est présente pour donner la vision de la saisie telle que réalisée par l’utilisateur (qui a saisi des aspects sur le standard, puis désactivé les critères non pertinents pour l’aspect).

Exemple :

Dans l’exemple ci-dessus, l’aspect surcharge le champ environnement, en retirant l’élément référence « Gare routière à moins de 500 m ». Il y donc deux champs dans l’aspect :

  • environnement :
"environnements" : [ {
        "elementReferenceType" : "Environnement",
        "id" : 147,
        "libelleFr" : "Lac ou plan d'eau à moins de 300 m",
        "ordre" : 13,
        "description" : "300 m maxi"
      }, {
        "elementReferenceType" : "Environnement",
        "id" : 173,
        "libelleFr" : "En ville",
        "ordre" : 2
      } ],
  • envionnementRemove :
"environnementsRemove" : [ {
        "elementReferenceType" : "Environnement",
        "libelleFr" : "Gare routière à moins de 500 m"
      } ]

Champs vides

Il est possible qu’un champ apparaisse dans champsAspect, sans apparaître dans le contenu de l’aspect. Ceci indique que le champ a été volontairement surchargé avec une valeur vide, afin d’indiquer que la valeur standard doit être ignorée pour cet aspect.

Il est donc important d’exploiter le champ champsAspect pour avoir la liste exhaustive des champs surchargés, au lieu de ne se baser que sur les champs apparaissant sur l’aspect.

Dans l’exemple ci-dessus, le champ presentation.descriptifDetaille est présent dans champsAspect, mais n’apparaît pas dans le contenu de l’aspect, indiquant que le descriptif détaillé de l’objet ne doit pas être utilisé pour cet aspect.