Documentation

Installation

Pour installer l’extension Import en Masse, veuillez vous référer à notre documentation à propos de l’installation des extensions étant donné qu’il n’y a rien de particulier pour Import en masse. Il n’y a pas non plus de mise en place, l’extension n’a aucun réglages.

Par défaut, seuls les administrateurs pourront utiliser les fonctionnalités d’import de masse. Si vous voulez autoriser les autres rôles à l’utiliser, vous devrez ajuster les permissions dans l’écran : Réglages > WP Customer Area > Permissions > Général. Vous pouvez ensuite activer la permission « Création en masse de contenu privé » pour autant de rôles que vous le souhaitez.

Utilisation

La procédure d’import en masse consiste en quelques étapes seulement :

1. Constituez votre fichier JSON, en décrivant tous les articles que vous voulez importer. Le format est décrit ci-dessous.
2. Téléversez tous les fichiers joints (requis pour le type d’article cuar_private_file dans le dossier par défaut wp-content/customer-area/ftp-uploads.
3. Rendez-vous ensuite dans la page d’import de masse et validez le formulaire : WP-Admin > Espace Privé > Import En Masse
4. Si WP Customer Area valide votre fichier, vous pouvez alors démarrer le processus d’import. Tous les articles listés dans le fichier JSON seront traités.

Pré-requis : format du fichier JSON

Cette extension est conçue en priorité pour les développeurs mais peut être utilisée par toute personne comprenant comment un fichier JSON peut être décrit. Vous devez constituer ce fichier, soit à la main, soit en développant un outil qui le construira à partir d’une autre source de données.

Un fichier JSON est un fichier texte structuré suivant une syntaxe particulière. Vous pourrez vous assurer que votre fichier respecte bien cette structure en utilisant le service gratuit JSON Lint.

Le tableau racine

La racine du fichier JSON est un tableau contenant un objet pour chaque contenu que vous souhaitez créer.

[
 {
   // Cette partie représente le premier contenu à créer, Cf. ci-dessous pour la syntaxe
   // Veuillez noter la virgule qui sépare cet objet du suivant.
 },
 {
   // Cette partie représente le deuxième contenu à créer, Cf. ci-dessous pour la syntaxe
   // Veuillez noter la virgule qui sépare cet objet du suivant.
 },
 {
   // Cette partie représente le deuxième contenu à créer, Cf. ci-dessous pour la syntaxe
   // Comme cet objet est le dernier, nous ne plaçons pas de `,` après `}`.
 }
]

Les objets

Chaque objet décrivant du contenu privé est constitué d’une série de propriétés. Certaines sont communes à tous les types de contenu, d’autres sont spécifiques à certains types de contenu.

Les propriétés sont nommées, encadrées par des guillemets, et séparées de leur valeur par deux points. Elles sont séparées entre elles par des vigules. Voici un exemple d’un objet JSON valide, avec 4 propriétés de types variés.

{
 "nombre" : 12,
 "texte" : "Lorem ipsum",
 "tableau" : [1, 2, 3, 4],
 "objet" : {
   "propriete_enfant" : 123
 }
}

Propriétés obligatoires

Dans tous les cas, les propriétés type et owners sont obligatoires.

Nom	Valeurs	Description
type	cuar_private_file cuar_private_page cuar_tasklist cuar_conversation	Type : Texte Le type de contenu privé WP Customer Area.
owners	usr: tableau d’ID d’utilisateurs (Extension Nouveaux Types de Propriétaires nécessaire pour autoriser plusieurs ID utilisateur) glo: tableau de règles globales. Valeurs valides : any_reg (n’importe quel utilisateur) (Extension Nouveaux Types de Propriétaires requise) rol: tablea de rôles, tels que administrator, author, etc. (Extension Nouveaux Types de Propriétaires requise) grp: tableau d’ID de groupes (Extension Nouveaux Types de Propriétaires requise) mrgp: tableau d’ID de groupes administrés (Extension Groupes Administrés requise) srgp: tableau d’ID de groupes intelligents (Extension Groupes Intelligents requise) prj: tableau d’ID de projets (Extension Projets requise)	Type : Objet Un objet décrivant à qui/quoi assigner le contenu privé. Chaque propriété est un type de propriétaire et la valeur est un tableau d’identifiants. Notez que pour certains types de propriétaires, vous aurez besoin d’extensions supplémentaires.

Exemple

Ci-dessous, nous créons une page privée, accessible aux utilisateurs ayant pour ID 1 ou 3, ainsi qu’aux utilisateurs ayant accès au projet portant l’ID 80 :

{
 "type" : "cuar_private_page",
 "owners" : {
   "usr" : [1, 3],
   "prj" : [80]
 }
}

Propriétés facultatives

Nom	Valeurs	Description
author	–	Type : Texte Par défaut : L’ID de l’utilisateur actuellement connecté ID de l’utilisateur auteur du contenu
title	–	Type : Texte Par défaut : Texte vide Titre du contenu
content	–	Type : Texte Par défaut : Texte vide Description / corps du contenu
excerpt	–	Type : Texte Par défaut : Texte vide Texte d’aperçu du contenu
status	draft, publish, …	Type : Texte Par défaut : “publish” Un des statuts d’article de WordPress, comme par exemple draft ou publish. Utile pour créer des contenus par anticipation, sans les publier.
meta	–	Type : Objet Par défaut : N/A Un objet clé/valeur qui sera interprété comme ensemble de post meta (méta données d’article). Utile quand vous souhaitez attacher des méta données à un article, qui seront utilisées par des plugins tierces (par exemple Advanced Custom Fields et notre extension Intégration ACF).

Exemples

Dans l’exemple suivant, nous allons créer une page privée, dont l’auteur sera l’utilisateur ayant pour ID 2, assignée à tous les administrateurs du site et non publiée (brouillon).

{
  "type" : "cuar_private_page",
  "title" : "Ceci est un titre d'exemple",
  "content" : "Ceci est un contenu d'exemple",
  "excerpt" : "Ceci est un extrait d'exemple",
  "author" : 2,
  "status" : "draft",
  "owners" : {
    "rol" : ["administrator"]
  }
}

Propriété liées aux types de contenu particuliers

Pour certains types de contenu, vous pouvez ajouter des données :

• Pièces jointes aux fichiers privés
  1. Copiez les pièces jointes vers votre serveur en utilisant FTP
     Avant l’import de masse, vous devez envoyer toutes les pièces jointes vers votre serveur dans le répertoire de téléversements FTP de WP Customer Area (par exemple avec Filezilla). Par défaut, ce répertoire ce trouve dans wp-content/customer-area/ftp-uploads.
  2. Listez les pièces jointes et décrivez comment lier les pièces jointes à la publication de fichier privé
     Une fois les fichiers dans le répertoire FTP sur votre serveur, vous devez décrire comment les attacher au fichier privé dans le JSON. Si vous avez l’extension Améliorations pour les fichiers, vous pouvez même attacher plus d’une pièce jointe par publication.

• Tâches pour les contenus « liste de tâche »
• Réponses aux conversations

Nom	Type de contenu	Description
attachments	cuar_private_file	Type : Objet Par défaut : N/A Un objet pour décrire comment attacher les fichiers. Chaque propriété est le nom du fichier dans le dossier FTP, et sa valeur est un objet ayant pour propriétés : method : comment gérer l’attachement (texte | obligatoire) copy : une fois le contenu privé créé, le fichier est conservé dans le répertoire FTP move : une fois le contenu privé créé, le fichier est supprimé du répertoire FTP caption : si vous voulez personnaliser l’affichage du nom de fichier (texte | optionnel) Extension Améliorations pour les Fichiers requise pour pouvoir insérer plusieurs objets.
tasks	cuar_tasklist	Type : Tableau Par défaut : N/A Un tableau d’objets décrivant les tâches de la liste. Chaque élément du tableau est un objet ayant pour propriétés : description : description de la tâche (texte | obligatoire) order : le numéro d’ordre de la tâche (entier | obligatoire) Extension Listes de Tâches requise.
replies	cuar_conversation	Type : Tableau Par défaut : N/A Un tableau d’objets décrivant les réponses à la conversation. Chaque élément du tableau est un objet ayant pour propriétés : content : le contenu de la réponse (texte | obligatoire) author : ID de l’utilisateur auteur de la réponse (entier | obligatoire) Extension Conversations requise.

Exemples

Ci-dessous, nous créons un fichier privé ayant pour titre « Vos factures », assigné à l’utilisateur ID 3, et ayant 2 pièces jointes.

{
  "type" : "cuar_private_file",
  "title" : "Vos factures",
  "attachments" : {
    "Facture_3320959.pdf" : {"method" : "move"},
    "Facture_2101122.pdf" : {"method" : "move", "caption" : "Votre facture 210112"}
  },
  "owners" : {
    "usr" : [3]
  }
}

Ci-dessous, nous créons une liste de tâches ayant pour titre « Mes tâches », assignée à l’utilisateur ID 1, et composée de 3 tâches.

{
  "type" : "cuar_tasklist",
  "title" : "Mes tâches",
  "owners" : {
    "usr" : [1]
  },
  "tasks": [
    {
      "description" : "Première tâche",
      "order" : 50
    },
    {
      "description" : "Troisième tâche",
      "order" : 500
    },
    {
      "description" : "Deuxième tâche",
      "order" : 145
    }
  ]
}

Ci-dessous, nous créons une conversation ayant pour titre « Discutons », assignée à l’utilisateur ID 2, ouverte par l’utilisateur ID 1, et ayant 3 réponses.

{
  "type" : "cuar_conversation",
  "title" : "Discutons",
  "author" : 1,
  "owners" : {
    "usr" : [2]
  },
  "replies": [
    {
      "content" : "Première réponse",
      "author": 1
    },
    {
      "content" : "Deuxième réponse",
      "author": 2
    },
    {
      "content" : "Troisième réponse",
      "author": 1
    }
  ]
}

Un exemple complet pas à pas

Étape 1 : Préparer le fichier JSON

Créez un fichier texte, ayant le contenu suivant et nommez le bulk-import.json

Note : nous avons intentionnellement glissé deux erreurs dans ce fichier à des fins de démonstration.

[
  {
    "type" : "cuar_private_page",
    "title" : "Hello world",
    "content" : "This is a test",
    "author" : 2,
    "owners" : {
      "usr" : [1, 3],
      "unknown": ["This line will trigger an error"]
    }
  },
  {
    "type" : "cuar_private_page",
    "title" : "This is a test title",
    "content" : "This is a test content",
    "excerpt" : "This is a test excerpt",
    "author" : 2,
    "status" : "draft",
    "owners" : {
      "usr" : [99999999]
    }
  }
]

Étape 2 : Validez le fichier JSON

Naviguez vers Espace Privé > Import en Masse, téléversez votre fichier, puis cliquez le bouton « check file » ( « Vérifier le fichier » ). WP Customer Area vérifie la syntaxe de votre fichier et que tous les utilisateurs référencés existent bien. En cas d’erreur, les articles ne seront pas importés et vous serez d’abord invité à corriger les erreurs.

Dans la capture d’écran ci-dessous, vous verrez les deux erreurs introduites dans notre exemple. Il faut maintenant les corriger. Vous pouvez enlever la propriété « unknown » et corriger l’ID utilisateur qui n’existe pas.

Vous devrez répéter cette seconde étape jusqu’à ce que votre fichier passe la validation.

Étape 3 : Téléversez de nouveau le JSON et recommencez le processus

Si le JSON est validé, recommencez à envoyer votre fichier.