Les API EditGrid pour vos tableurs en ligne


précédentsommairesuivant

V. Manipulation de documents

Nous allons maintenant voir comment manipuler des documents à distance : créer un tableur, le modifier...

Nous n'aborderons l'affichage des grilles au sein des pages de notre site que dans la section suivante.

Pour une meilleure intégration de notre code au sein des méthodes de base d'EditGrid, nous allons créer une classe qui va hériter de la classe EditGrid : la classe EGrid. Dans le fichier includes/EGrid.php, insérez le code suivant :

 
Sélectionnez

<?php
/* la classe hérite de EditGrid */
class EGrid extends EditGrid {

}
?>

V-A. Format des méthodes et paramètres

Comme nous l'avons dit, nous allons inclure toutes nos méthodes au sein de la classe EGrid.

Les méthodes EditGrid sont appelées par l'instruction call, et attendent en général trois paramètres :

  1. le nom de la fonction
  2. les paramètres :
    Un tableau (array), qui contient au moins le WorkSpace et le Token (nommé "s")
  3. l'entité :
    L'entité (par exemple, cell, worksheet...), au format XML.

Soit par exemple :

 
Sélectionnez

// le nom de la fonction
$nom = 'workbook.create';

// les parametres :
$parametres = array = (
 	's'         =>  [votre token],
	'workspace' => $config['workspace'],
);

// l'entité
$entite = "<workbook><name>Un exemple</name></workbook>";

Ne vous inquiétez pas si ce n'est pas très clair, ça le deviendra avec nos exemples.

V-B. Créer un nouveau document

La création d'un nouveau document s'effectue grâce à la fonction workbook.create.

L'appel à cette fonction suit la règle que nous avons énoncé plus haut. Insérons dans la classe EGrid une nouvelle fonction, nommée createDoc :

 
Sélectionnez

/**
 * créer un nouveau document
 *
 * @param   [string]    le nom du document
 * @return  [array]     l'entité créée
 */
public function createDoc ($name) {
	global $config;

	$xml = "<workbook><name>$name</name></workbook>";	
	
	$workbook = $this->call(
		"workbook.create",
		array(
			'workspace'	=> $config['workspace'],
			's'		=> $config['sessionKey']),
		$xml
	);
	
	//
	// controler
	//
	if ($workbook->hasError()) trigger_error($workbook->getError()->toString(), E_USER_ERROR);
	return $workbook->getResult();
}

Bien sûr, nous pourrions nous passer du trigger_error (et renvoyer faux), mais dans notre exemple cela nous permettra d'étudier les éventuelles erreurs.

Et voilà, notre fonction est créée !Il nous faut encore l'appeler. Faisons le depuis notre fichier index.php.

 
Sélectionnez

<?php

//
// configuration editgrid
//
$config = array (
	'appKey'       		=>	'[votre appKey]',
	'user'			=>	'user/[votre pseudo]',
	'sessionKey'       	=>	'[votre sessionKey]',
	'authToken'		=>	'[votre token]',
	'name'			=>	'[le nom de l application]',
	'workspace'		=>	'/user/[votre pseudo]',
);

//
// appel de la classe
//
require 'includes/editgrid.php';
require 'includes/EGrid.php';

//
// instanciation de la classe
//
$editgrid = new EGrid($config['editgrid']['sessionKey']);  

//
// créons notre document
//
$nom = 'un exemple';
$editGrid->createDoc($nom);

echo 'le document "un exemple" est désormais créé !';
?>

Il ne nous reste plus qu'à lire notre script index.php ainsi qu'admirer le résultat sur notre espace personnel d'EditGrid.

V-C. Ouvrir un document existant

Ouvrons notre document grâce à la fonction workbook.get.
Comme précédemment, ajoutons notre fonction à la classe. Cette fois cependant, pas besoin de passer l'entité en paramètre. La fonction va, elle, nous renvoyer l'entité (au format XML donc).

 
Sélectionnez

/**
 * Ouvrir un document
 *
 * @param   [string]    le nom du document
 * @return  [string]    l'identifiant du document, par exemple
 */
public function openDoc ($name) {
	global $config;
	
	$name = $config['workspace']."/$name";
	
	$result = $this->call(
		"workbook.get",
		array(
			'workbook'  => $name,
			's'         => $config['sessionKey'])
	);
	
	//
	// controler
	//
	if ($workbook->hasError()) trigger_error($workbook->getError()->toString(), E_USER_ERROR);
	
	//
	// résultat : l'entité du document créé
	//
	$tDoc = $result->getValue();
	
	//
	// retournons, par exemple, l'identifiant du document
	//
	return $tDoc['id'];
}

Et maintenant le fichier index.php :

 
Sélectionnez

<?php

[...]

//
// obtenir l'identifiant du document
//
$nom = 'un exemple';
$id = $editGrid->openDoc($nom);

echo $id;
?>

Et voilà !

V-D. Importer un document

Il est parfaitement possible d'importer un document existant, au format xls, grâce à la fonction workbook.createRemote :

 
Sélectionnez

public function createRemoteDoc($name) {
		
	global $config;
	
	$workbook_name = $config['workspace'] . "/$name";
	$this->workbook = $workbook_name;
	
	//
	// créer classeur (durée de vie : 1 jour)
	//
	$workbook_xml = "<workbook><name>$name</name></workbook>";
	
	$url_xls = "http://monsite.fr/xls/";
	$load_url = $url_xls."mondoc.xls"; // fichier source
	$save_url = $url_xls."$name.xls";  // fichier de destination
	
	$workbook = $this->call(
		"workbook.createRemote",
		array('workspace' => $config->EditGrid['workspace'],
		'loadUrl' 		=> $load_url,
		'saveUrl' 		=> $save_url,
		'tokenPermission' => 'read-write',
		's' 				=> $config->EditGrid['sessionKey']),
		$workbook_xml
	);
	if ($workbook->hasError()) trigger_error($workbook->getError()->toString(), E_USER_ERROR);
	return true;
}
?>

Toutefois, au moment où je rédige cet article, cette fonctionnalité semble poser quelques soucis, il est préférable de tester l'existence du fichier de sortie lors de l'enregistrement.

Par ailleurs, bien que cette précision ait disparu de certaines parties de la documentation, la durée de vie d'un classeur créé avec cette fonction est de 1 jour seulement.


précédentsommairesuivant

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants : Viadeo Twitter Facebook Share on Google+   

  

Copyright © 2009 Jean-François Lépine. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.