Plugandwork javascript sdk

plugandwork-sdk est un client plugandwork javascript (compatible avec node) qui vous aidera a créer des applications basées sur plugandwork.

Installation

npm install plugandwork-sdk ou, si vous utilisez yarn, yarn add plugandwork-sdk

Importation

import Plugandwork from "plugandwork-sdk" ou const Plugandwork = require("plugandwork-sdk");

Initialisation du client

Le client plugandwork vous aidera à interagir avec les données d'un serveur plugandwork. Pour l'instancier :

const pawClient = Plugandwork.createClient(options: ClientOptions);

Options du client

interface ClientOptions
{
  host: string; // url de l'hote plugandwork (http/s)
  accessToken?: string; // token d'acces à l'api
  credentials?: { user_token: string; username: string } | { auth_token: string; uuid: string } // identifiants d'accès à l'api
  d3Compatible?: boolean;
}

La seule option obligatoire du client est l'hôte plugandwork.

Outils de base

Connexion

Pour récupérer un token valide, vous pouvez connecter le client à un compte plugandwork avec la méthode login.

pawClient.login({ username: "admin", password: "document" }).then(function() { console.log("connecté!") });

Par défaut, la méthode utilise grant_type: "password", mais vous pouvez surcharger cette options dans les paramètres de la méthode login.

Validation md5

pawClient.validateMd5("md5String")
  .then(function() { console.log("Ce document n'existe pas encore, à vous de le créer !") })
  .catch(function() { console.log("Ce document existe déjà !") });

Attention ! La méthode validateMd5 déclenchera une erreur si le md5 existe déjà, pensez à l'intercepter avec un try catch ...

Accès aux modèles

Le client plugandwork, une fois initialisé, vous donne accès à différents modèles :

• Doc pawClient.models.Doc
• Space pawClient.models.Space

Chaque modèle étend la classe PawModel, qui initialise un store redux pour mettre en cache les instances et donne accès à plusieurs méthodes :

Récupération des instances (PawModel.fetch)

La méthode fetch permet de récupérer les instances du modèle sur plugandwork. Cette méthode prend en paramètres une requete.

const query = { per_page: 10, page: 2 };
 
// docs sera un tableau de 10 documents (typeof pawClient.models.Doc) correspondants aux 10 documents de la page 2
const docs = await pawClient.models.Doc.fetch(query);

Création d'une nouvelle instance (PawModel.create)

La méthode create permet de créer une nouvelle instance d'un modèle.

// doc sera un document plugandwork (typeof pawClient.models.Doc)
const doc = await pawClient.models.Doc.create({ title: "Mon nouveau document !" });

Cas particuliers

Création d'un document avec fichier

Les documents plugandwork sont liés à des fichiers. Pour créer un document avec un fichier, il vous faut envoyer le buffer du fichier dans le champ file

exemple avec node (fs)

  const fileBuffer = fs.createReadStream("./monfichier.png");
  const doc = await pawClient.models.Doc.create({ title: "Mon nouveau document !", file: fileBuffer });
  console.log(doc.file_url); // /send/...

Mettre à jour une instance (PawModel.prototype.update)

  const space = await pawClient.models.Space.create({ title: "Mon espace plugandwork" });
  await space.update({ title: "Mon espace plugandwork modifié" });
  console.log(space.title); // Mon espace plugandwork modifié

Supprimer une instance (PawModel.prototype.delete)

  const space = await pawClient.models.Space.create({ title: "Mon espace plugandwork" });
  await space.delete();

récupérer une instance (PawModel.get)

Une fois instancié (avec le client plugandwork), le modèle vous permet d'accéder à son cache et d'y récupérer une instance via son id.

const doc = pawClient.models.Doc.get("identifiant");
console.log(doc?.id); // "identifiant"

Cette méthode vous permet également de récupérer une instance sur plugandwork, en définissant le second paramètre de la méthode fetch à true (fetch). Dans ce cas, la méthode fetch renverra un Promise

const doc = await pawClient.models.Doc.get("identifiant");
console.log(doc?.id); // "identifiant"

Récupérer une instance en cache (PawModel.get)

Une fois instancié (avec le client plugandwork), le modèle vous permet d'accéder à son cache et d'y récupérer une instance via son id.

const doc = pawClient.models.Doc.get("identifiant");
console.log(doc?.id); // "identifiant"

Récupérer une instance avec son id (PawModel.get)

Cette méthode vous permet également de récupérer une instance sur plugandwork, en définissant le second paramètre de la méthode fetch à true (fetch). Dans ce cas, la méthode fetch renverra un Promise

const doc = await pawClient.models.Doc.get("identifiant");
console.log(doc?.id); // "identifiant"

Compatibilité d3

Si votre instance plugandwork est compatible avec l'api d3 (version >= 3.5), vous pouvez récupérer une version simplifié de certains modèles (pour la recherche par exemple). Pour activer cette option, pensez à définir l'option d3Compatible à true à l'initialisation du client (voir l'initialisation du client ci-dessus).

Si cette option est activée, les modèles suivants seront simplifiés:

• Doc

Autrement dit, la méthode fetch de ces modèles ne renverra pas la version complète mais une version simplifié. Vous bénéficierez donc d'un temps d'exécution beaucoup plus rapide. Cependant, si vous avez besoin d'accéder à l'instance complète, vous pourrez la récupérer en la peuplant.

Peupler une instance (PawModel.prototype.populate)

const doc = await pawClient.models.Doc.create({ ... });

🚀