Documentation technique

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 multimédias selon le champ : le champ illustrations n’accepte que des multimédias de type « IMAGE » alors que le champ multimedias n’accepte pas les multimédias de ce type.
• Faire attention au type des multimédias selon 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

Pour ajouter un nouveau multimédia 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 >= 5.5
    if (function_exists('curl_file_create')) {
        return curl_file_create($filePath, $contentType, $fileName);
    }

    // Version compatible PHP < 5.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 mon 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 multimédia

L’ajout d’un nouveau multimedia se fait en insérant dans la liste au format JSON un nouvel élément à l’emplacement souhaité.
Un multimédia doit à minima porter un type et un fichier ou un lien externe pour la version française. Pour la liste exhaustive des champs disponibles sur un multimédia, se référer aux schémas JSON du multimédia.
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 multimédias (raccourcis pour simplifier l’exemple)

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

Données injectées dans le formulaire : ajout d’un multimédia 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 multimédia existant

On distingue deux cas de modification d’un multimédia existant :

• la modification des métadonnées du multimédia (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 multimédia, il est recommandé de créer un nouveau multimédia, plutôt que d’essayer d’en réutiliser un existant.

Modification des métadonnées

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

• 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, le 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 du multimédia doit toujours être présent sur le multimédia pré-existant, afin de pouvoir déterminer quel est le multimédia 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.

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"
    }
  } ]
}

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 le multimédia 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 multimédia existant

Pour supprimer un multimédia d’une liste, il suffit de retirer ce multimédias 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 mutlimédia, il suffit de changer sa position dans les données JSON à injecter. Les multimédias 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’image 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
} ]