Spécificités des multimédias (écriture)

De manière à gérer les transferts de fichiers et à autoriser des modifications partielles des fichiers associés à une fiche, la modification des champs illustrations et multimédias fait appel à des spécificités de fonctionnement.

Vocabulaire

– Champ illustrations : tableau listant les items `multimedia` de type IMAGE : correspond à la liste dans Multimedias > Illustrations sur l’interface de saisie Apidae
– Champ multimedias : tableau listant des items `multimedia` de tous types sauf IMAGE : correspond à la liste dans Multimedias > Multimedias sur l’interface de saisie Apidae
– Item `multimedia` : représentation d’un item dans les listes ci-dessus : un item `multimedia` est caractérisé par un identifiant, un nom, une liste traductionFichiers…
La distinction entre le champ multimedias (liste) et l’item `multimedia` (item dans la liste) est importante et peut prêter à confusion.

Précautions sur la cohérence des données

Quelques précautions d’utilisation :

  • Attention, ces deux champs sont des listes : chaque fois que leur contenu est modifié, il est impératif d’injecter l’intégralité de la liste. Tout élément de la liste manquant par rapport à l’objet avant appel est considéré comme ayant été retiré de la liste.
  • Faire attention au type des items `multimedia` selon le champ : le champ illustrations n’accepte que des items `multimedia` de type « IMAGE » alors que le champ multimedias n’accepte pas les items `multimedia` de ce type.
  • Faire attention au type des items `multimedia`, si le fichiers doit être hébergé sur Apidae ou si c’est un lien externe : certains types de multimédias sont réservés aux liens externes (webcams, visites virtuelles, chaîne Youtube, galeries Flickr, etc).

Joindre un fichier au formulaire

La taille des images qui peuvent être chargées sur la plateforme est limitée à 10 Mo.

Pour ajouter un nouvel item `multimedia` dans un champ (illustrations ou multimedias) sur une fiche, il est nécessaire de pousser un ou plusieurs fichiers dans le formulaire lors de l’appel. Pour cela, on utilise la norme multipart/form-data.

Exemple PHP : de méthode pour formater proprement un fichier :

// Méthode empruntée de https://github.com/guzzle/guzzle/blob/3a0787217e6c0246b457e637ddd33332efea1d2a/src/Guzzle/Http/Message/PostFile.php#L90
function getCurlValue($filePath, $contentType, $fileName)
{
    // Disponible seulement en PHP au dessus de v5.5
    if (function_exists('curl_file_create')) {
        return curl_file_create($filePath, $contentType, $fileName);
    }

    // Version compatible PHP en dessous de v5.5
    $value = '@{$filePath};filename=' . $fileName;
    if ($contentType) {
        $value .= ';type=' . $contentType;
    }
 
    return $value;
}

// Exemple d'utilisation
var encloseFile = getCurlValue('/mon-dossier/mon-image.jpg','image/jpeg','montagne.jpg');

Une fois le fichier formaté correctement, il faut le pousser dans le formulaire. Le nom du paramètre dans lequel l’image est poussée est important, une partie sera réutilisée pour référencer l’image dans les données JSON.
Le paramètre dans lequel le fichier est poussé doit être préfixé avec « multimedia.« , suivi de la clé qui permettra de réutiliser le fichier.

Le format pour référencer un fichier joint dans les données JSON est le suivant :

MULTIMEDIA#<clé du fichier joint>

Dans l’exemple précédent :

  • pour ajouter le fichier au formulaire avec la clé « illustration-1″, il faudra placer le fichier dans un paramètre nommé « multimedia.illustration-1″.
  • pour référencer ce fichier, on utilisera « MULTIMEDIA#illustration-1″ dans le champ url de la traduction du multimédia.

Exemple PHP :

$formFields['multimedia.illustration-1'] = getCurlValue('/mon-dossier/mon-image.jpg','image/jpeg','montagne.jpg');

Ajouter un item `multimedia` dans un champ (illustrations ou multimedias)

L’ajout d’un nouvel item `multimedia` se fait en insérant dans la liste au format JSON un nouvel élément à l’emplacement souhaité.
Un item `multimedia` doit à minima porter un type et un item dans traductionFichiers un lien externe pour la version française.

Liste des champs

Pour la liste exhaustive des champs disponibles sur un multimédia, se référer aux schémas JSON des items `multimedia` pour n’importe que type objet.

Les champs les plus utilisés sont listés ci-dessous.
Attention : seuls les champs en gras sont modifiables par les API, les autres sont générés par Apidae :

  • identifiant (integer : généré par Apidae)
  • identifiantExterne (string : votre identifiant si vous le souhaitez)
  • link (boolean)
  • type (string / enum : IMAGE, DOCUMENT, VIDEO, PLAN…)
  • source (string : provenance de l’image. Cf. encadré ci-dessous : 30 caractères maximum)
  • nom (object : liste de libelleFr, libelleEn… pour les traductions)
    • libelleFr
    • libelleEn…
  • legende (object : liste de libelleFr, libelleEn… pour les traductions)
  • copyright (object : liste de libelleFr, libelleEn… pour les traductions)
  • traductionFichiers (array : liste des fichiers de l’item `multimedia`)
    • locale (string)
    • url (string)
    • urlListe (string : généré par Apidae)
    • urlDiaporama (string : généré par Apidae)
    • urlQHD? (à venir) (string : généré par Apidae)
    • extension (string : généré par Apidae)
    • fileName (string)
    • taille (integer : généré par Apidae)
    • hauteur (integer : généré par Apidae)
    • largeur (integer : généré par Apidae)
    • lastModifiedDate (string, date-time : généré par Apidae)
  • dateLimiteDepublication (string date-time)
  • locked (boolean) : l’image est verrouillée en modification IHM seulement (provenance de passerelles) : ce champ est modifiable en API d’écriture, et le lock n’empêche pas la modification de l’illustration par API : il ne concerne que l’IHM, pour empêcher l’utilisateur de modifier une illustration qui a été écrite par API et qu’on souhaite verrouiller.
  • identifiantTemporaire (integer)
  • modificationMode (string, enum : MODIFICATION_FICHIERS, MODIFICATION_METADONNEES)

Champ source (30 caractères maximum)
Ce champ n’est pas visible sur l’interface d’Apidae.
Il permet d’identifier, si vous le souhaitez, les fichiers qui ont été ajoutées par une API ou une passerelle, et donc de faire la distinction avec les fichiers ajoutés par exemple par un office du tourisme sur Apidae.
Valeurs courantes : « Clévacances », « Gîtes de France », « Votre société » ou « Votre projet »…
Ce champ est ensuite consultable via les API et les exports.

C’est le champ url de la traduction qui porte la référence au fichier joint au formulaire au format :

MULTIMEDIA#<clé du fichier joint>

Exemple :

Données JSON originales : 2 items `multimedia` dans le champ multimedias (raccourcis pour simplifier l’exemple)

{
  "multimedias" : [ {
    "identifiant" : 200003,
    [...]
  }, {
    "identifiant" : 200004,
    [...]
  } ]
}

Données injectées dans le formulaire : ajout d’un item `multimedia` dans le champ multimedias, en 2ème position

{
  "multimedias" : [ {
    "identifiant" : 200003,
    [...]
  }, {
    "link" : false,
    "type" : "DOCUMENT",
    "traductionFichiers" : [ {
      "locale" : "fr",
      "url" : "MULTIMEDIA#illustration-1"
    } ],
    "nom" : {
      "libelleFr" : "Illustration n°1",
      "libelleEn" : "Illustration #1"
    },
    "legende" : {
      "libelleFr": "Legende pour mon illustration n°1",
      "libelleEn" : "Caption for illustration #1"
    }
  }, {
    "identifiant" : 200004,
    [...]
  } ]
}

Modifier un item `multimedia` existant

On distingue deux cas de modification d’un item `multimedia` existant :

  • la modification des métadonnées de l’item (nom, légende, copyright, date limite de publication)
  • la modification d’un ou plusieurs fichiers de traduction

Pour indiquer quel type de modification on souhaite réaliser, on utilise un champ modificationMode.

Si vous souhaitez modifier à la fois les fichiers et la légende d’un item, il est recommandé de créer un nouvel item, plutôt que d’essayer d’en réutiliser un existant.

Modification des métadonnées

Nous appelons métadonnées d’un item `multimedia` toutes les informations hors fichier joint. Pour modifier les métadonnées, insérez dans l’item existant un champ modificationMode avec pour valeur MODIFICATION_METADONNEES. Modifiez ensuite les différents champs de métadonnées de l’item :

  • nom : un libellé traduisible
  • legende : un libellé traduisible
  • copyright : un libellé traduisible
  • dateLimiteDePublication : une date
  • …

Dans la mesure où seuls les champs de métadonnées sont modifiés, la liste de fichiers traduits traductionFichiers peut être retirée des données JSON injectées, puisqu’il ne sera ni exploité, ni modifié dans ce mode.

En revanche le champ identifiant de l’item doit toujours être présent, afin de pouvoir déterminer quel est l’item modifié. Lorsque vous modifiez les métadonnées veillez également à bien injecter tous les champs de métadonnées préexistant que vous souhaitez conserver. Les champs de métadonnées absents sont considérés comme vides et seront supprimés.

Exemple : données JSON originales :

{
  "illustrations" : [ {
    "identifiant" : 298329,
    "link" : false,
    "type" : "IMAGE",
    "traductionFichiers" : [ {
      "locale" : "fr",
      "url" : "http://static.apidae-tourisme.com/filestore/objets-touristiques/images-principales/57/31/73529.jpg",
      "urlListe" : "http://static.apidae-tourisme.com/filestore/objets-touristiques/images-principales/57/31/73529-liste.jpg",
      "urlFiche" : "http://static.apidae-tourisme.com/filestore/objets-touristiques/images-principales/57/31/73529-fiche.jpg",
      "urlDiaporama" : "http://static.apidae-tourisme.com/filestore/objets-touristiques/images-principales/57/31/73529-diaporama.jpg",
      "extension" : "jpg",
      "fileName" : "sitra_chatelus",
      "taille" : 234489,
      "hauteur" : 862,
      "largeur" : 1150,
      "lastModifiedDate" : "2012-06-28T01:06:46.000+0000"
    } ],
    "nom" : {
      "libelleFr" : "Nom"
    },
    "copyright" : {
      "libelleFr" : "Copyright"
    }
	"source" : "Gîtes de France"
  } ]
}

Exemple : Données injectées dans le formulaire d’écriture :

{
  "illustrations" : [ {
    "identifiant" : 298329,
    "modificationMode" : "MODIFICATION_METADONNEES",
    "nom" : {
      "libelleFr" : "Nouveau nom",
      "libelleNl" : "Nouveau nom NL"
    },
    "legende" : {
      "libelleFr" : "Nouvelle légende",
      "libelleNl" : "Nouveau légende NL"
    }
    "copyright" : {
      "libelleFr" : "Nouveau copyright",
      "libelleNl" : "Nouveau copyright NL"
    },
    "dateLimiteDePublication" : "2015-12-31"
  } ]
}

Modification des fichiers attachés

Pour modifier les fichiers traduits, insérez dans l’item `multimedia` existant un champ modificationMode avec pour valeur MODIFICATION_FICHIERS. Pour remplacer une traduction existante par un nouveau fichier, le fonctionnement est similaire à l’ajout d’un nouveau fichier. Il faut joindre le nouveau fichier au formulaire (voir Joindre un fichier au formulaire), puis le réferencer dans le champ url du fichier de traduction à modifier.

Exemple : données injectées dans le formulaire :

{
  "illustrations" : [ {
    "identifiant" : 298329,
    "traductionFichiers" : [ {
      "locale" : "fr",
      "url" : "MULTIMEDIA#illustration-fr"
     }, {
      "locale" : "nl",
      "url" : "MULTIMEDIA#illustration-nl"
     } ]
  } ]
}

Supprimer un item `multimedia` existant

Pour supprimer un item d’une liste, il suffit de retirer cet item des données JSON injectées.

Exemple : données JSON originales :

"multimedias" : [ {
"identifiant" : 200003,
[...]
}, {
"identifiant" : 200004,
[...]
}, {
"identifiant" : 200005,
[...]
} ]

Données injectées dans le formulaire (suppression du 3ème multimédia) : 

{
  "multimedias" : [ {
    "identifiant" : 200003,
    [...]
  }, {
    "identifiant" : 200004,
    [...]
  }

Réordonner les multimédias

Pour modifier la position d’un item dans la liste, il suffit de changer sa position dans les données JSON à injecter. Les items sont importés dans l’ordre dans lequel ils sont placés dans la liste.

Il est important de retenir que dans le champ illustrations, l’item `multimedia` en première position dans la liste est considérée comme l’image principale de l’objet et est mise en avant par rapport aux autres images.

Réutiliser un multimédia dans un aspect

Il est possible que vous souhaitiez réutiliser un multimédia de la fiche standard sur un des aspects. On distingue deux cas de figure :

  • le multimédia existe déjà sur le standard, et a un identifiant
  • le multimédia n’existe pas encore sur le standard mais va être créé dans le même appel

Si le multimédia existe déjà, il faut l’ajouter dans le champ de l’aspect en le référençant simplement avec son identifiant :

"illustrations" : [ {
  "identifiant" : 543215
}

Si le multimédia n’existe pas encore, il faut utiliser un champ identifiantTemporaire numérique qui permet de donner un identifiant temporaire au multimédia créé sur le standard pour pouvoir le réutiliser sur l’aspect :

/* Données injectées sur le STANDARD */
"illustrations" : [ {
  "identifiantTemporaire" : 4,
  "link" : false,
  "type" : "IMAGE",
  "traductionFichiers" : [ {
    "locale" : "fr",
    "url" : "MULTIMEDIA#illustration-1"
  } ],
  "nom" : {
    "libelleFr" : "Illustration n°1",
    "libelleEn" : "Illustration #1"
  },
  "legende" : {
    "libelleFr": "Legende pour mon illustration n°1",
    "libelleEn" : "Caption for illustration #1"
  }
}
/* Données injectées sur un aspect */
"illustrations" : [ {
  "identifiantTemporaire" : 4
} ]