Les API EditGrid pour vos tableurs en ligne

Jean-François Lépine

EditGrid.com est un webservice pratique pour utiliser facilement des grilles de type Excel sur un site Internet. Je vous propose de voir comment il s'installe et s'utilise. Ce tutoriel ne vise pas à remplacer la documentation officielle, mais simplement à rendre plus abordables des fonctionnalités utiles et efficaces, qui ne sont pas encore, ou peu, documentées en français.

Commentez ♪

- Titre : Les API EditGrid pour vos tableurs en ligne

- Auteur : Jean-François Lépine

- Parution : 1 avril 2009

- Licence : 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.

Sommaire

- I. Introduction

- II. Avant de commencer : installation

- II-A. Paramétrage du compte

- II-B. Installation des fichiers

- III. Authentification

- IV. Pour une meilleure compréhension… Les entités

- IV-A. WorkSpace

- IV-B. WorkBook

- IV-C. WorkSheet

- IV-D. Cell

- IV-E. Ouf !

- IV-F. Configuration

- V. Manipulation de documents

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

- V-B. Créer un nouveau document

- V-C. Ouvrir un document existant

- V-D. Importer un document

- VI. Manipulation de données

- VI-A. Introduction

- VI-B. Lister les feuilles d'un document

- VI-C. Récupérer le contenu d'une feuille

- VI-D. Modifier un document

- VI-E. Exemple récapitulatif

- VII. À l'écran : le JavaScript

- VII-A. Introduction

- VII-B. Préalable : convertir des coordonnées de type « 0,0 » en « A1 »

- VII-C. Naviguer entre les feuilles

- VII-D. Récupérer le contenu de la sélection

- VII-E. Ajouter / Supprimer des feuilles

- VII-F. Modifier le contenu d'une cellule de la feuille active

- VII-G. Personnalisation : cacher le menu

- VIII. Liens & fichiers utilisés

- IX. Pour finir…

I - Introduction

EditGrid.com est un webservice pratique pour utiliser facilement des grilles de type Excel sur un site Internet. Je vous propose de voir comment il s'installe et s'utilise. Ce tutoriel ne vise pas à remplacer la documentation officielle, mais simplement à rendre plus abordables des fonctionnalités utiles et efficaces, qui ne sont pas encore, ou peu, documentées en français.

EditGrid se distingue de ses concurrents (GoogleDocs notamment) par la convivialité de ses grilles, et par le nombre de ses fonctionnalités.

Pour un aperçu, voici la liste des imports supportés :

- MS Excel (.xls) ;

- CSV (.csv) ;

- OpenDocument 1.0 (.ods) ;

- OpenOffice.org Calc 1.x (.sxc) ;

- Gnumeric (.gnumeric) ;

- Lotus 1-2-3 (.123).

Nous allons voir comment utiliser cet outil pour l'intégrer à notre site web. Pour cela, nul besoin de compétences extraordinaires, mas il convient tout de même d'avoir des bases en PHP, en Programmation Orientée Objet et en JavaScript.

II - Avant de commencer : installation

II-A - Paramétrage du compte

Je suppose ici que vous êtes déjà inscrit sur le site d'EditGrid.com. Si ce n'est pas le cas, faites-le avant de continuer. Commençons par créer une nouvelle application. Depuis l'espace développeur, cliquez sur Setup New Application. Suivez la procédure, puis copiez la clef de votre application, et conservez-la dans un coin.

Attribuez une clef de session pour cette application. Cela nous permettra d'éviter d'avoir à passer par une fenêtre de login lors de nos appels aux API : revenez à l'espace développeur, puis cliquez sur Session Key Generator, et suivez les instructions. Choisissez votre application, puis cliquez sur Generate. Copiez votre clef (SessionKey) et conservez-la soigneusement.

Sur la même page, cliquez sur generate an auth token now, et conservez le AuthToken que vous avez ainsi obtenu.

Nous avons maintenant une clef d'authentification, qui sera utilisée pour toutes les opérations sur les documents.

Pour résumer :

Nous avons obtenu deux clefs :

- une AppKey, qui nous permettra d'identifier notre application depuis notre site web ;

- une SessionKey, qui nous permettra de nous authentifier facilement ;

- un AuthToken (ou Token), qui nous permettra, comme la SessionKey, de nous authentifier.

II-B - Installation des fichiers

L'utilisation des fonctions d'EditGrid est très simple, et ne requiert qu'un seul fichier (EditGrid.php, cf. juste ci-dessous).

Nous réaliserons notre exemple sur un serveur local, par exemple sous ZazouWebMiniServer, Wamp ou EasyPHP. Le premier étant le plus facile à utiliser à mon avis, je détaillerai donc la procédure pour ZWMS.

Après avoir lancé ZWMS, vérifiez dans la configuration que l'extension CURL est activée. Pour cela, faites un clic droit sur l'icône du systray > Configuration > php.ini. Trouvez la ligne « extension=php_curl.dll » et enlevez le point-virgule devant s'il y en a un.

Redémarrez ZWMS. Voilà, l'extension est activée.

Maintenant, nous allons créer le répertoire qui contiendra l'ensemble des fichiers de notre site. Allez dans le répertoire d'installation de ZWMS, puis dans le dossier _web.zmwsc. Là, créez un nouveau répertoire nommé « demo_EditGrid », et deux sous répertoires :

- includes : méthodes et classes utilisées pour notre code php ;

- js : fonctions et classes utilisées pour notre code JavaScript.

Nous allons maintenant importer dans notre site la librairie fournie par EditGrid, que vous trouverez ici. Après avoir extrait l'archive, repérez le document EditGrid-php-client\EditGrid-php-client\client\EditGrid.php. C'est le seul fichier dont nous aurons besoin. Toutefois, n'hésitez pas à consulter les exemples fournis.

Copiez ce fichier et collez-le dans le répertoire « includes » de notre site.

Créez un fichier vide nommé « EGrid.php » dans ce répertoire « includes ». Ce fichier contiendra la classe que nous utiliserons dans nos appels (cf. la Section Manipulation de données).

À la racine de notre site (dossier « demo_EditGrid »), créez un nouveau fichier nommé « index.php ». Dans le dossier « css », créer un fichier « feuille.css », et enfin dans le dossier « js » un fichier « functions.js ».

Vous devriez obtenir ceci :

III - Authentification

Pour pouvoir accéder à notre espace de documents (WorkSpace), nous allons maintenant construire les bases de notre site. Voici le code de base de notre fichier index.php :

la base

<?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 des classes
//
require 'includes/editgrid.php';
require 'includes/EGrid.php';

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

Les paramètres de votre application sont ici stockés dans un tableau. Il existe des méthodes plus rapides, mais cela nous suffira pour plus de clarté. Bien sûr, les valeurs entre crochets sont à renseigner avec les informations que vous avez obtenues plus haut.

Nous avons désormais tout ce qu'il nous faut pour commencer !

IV - Pour une meilleure compréhension… Les entités

… Mais nous n'allons pas commencer tout de suite :-) ! Car auparavant, il nous faut bien comprendre ce que nous allons faire, et notamment les types d'éléments que nous allons rencontrer. Si vous avez déjà fait un peu de VBA, vous n'aurez sans doute pas de difficultés à comprendre. Mais même dans le cas contraire, rassurez-vous, ce n'est pas très compliqué.

IV-A - WorkSpace

La première chose à connaître, c'est votre espace de travail. En effet, vos documents sont regroupés et rattachés à votre compte par ce moyen. Imaginez cela comme votre bureau, sur lequel vous mettriez exclusivement des classeurs Excel.

Cet espace de travail, c'est le « WorkSpace » (logique !). Il possède une structure bien précise, que vous serez amené à comprendre un peu plus tard.

Pour le connaître, rien de plus simple : c'est « /user/ » suivi de votre login. Dans mon cas, par exemple, c'est « /user/Halleck ».

Nom

Type

Modif.

Req.

id

string

Identifiant du workspace

path

string

Chemin complet du workspace

name

string

x

Nom du workspace

organisation

string

The full path of the belonging organisation.

organisationId

string

The id of the belonging organisation.

defaultBookPermission

string

x

Permission par défaut pour les workbook de ce workspace: {private/read/read-write}.

defaultListPublic

string

x

Paramètres par défaut d'affichage public des classeurs pour le workspace : {0/1}.

IV-B - WorkBook

le WorkBook, c'est tout simplement un document Excel. Il correspond au fichier .xls que vous êtes habitué à manipuler, et contient des feuilles, des cellules…

Structure de l'entité WorkBook.

Nom

Type

Modif.

Req.

id

string

x

Identifiant du workbook

path

string

Chemin complet du workbook

name

string

x

x

Nom du workbook

currRevId

string

« Identifiant révisé » du workbook"

workspaceId

string

Identifiant du workspace

workspace

string

Chemin complet du workspace

organisationId

string

The id of the owner organisation.

organisation

string

The full path of the owner organisation.

publicAccess

string

x

Droit d'accès du public

isTemplate

int

x

x

1 ou 0. Indique si le workbook est un template ou non

isDeleted

int

1 ou 0. Indique si le workbook est supprimé ou non

timeZone

string

x

x

Zone horaire du workbook

note

string

x

x

Note du workbook

createUserId

string

x

Identifiant de l'utilisateur qui a créé le workbook

createUser

string

Chemin complet de l'utilisateur qui a créé le workbook

createTime

string

x

Date de création du workbook

lastModifiedUserId

string

x

Identifiant de l'utilisateur qui a modifié le workbook en dernier

lastModifiedUser

string

Chemin complet de l'utilisateur qui a modifié le workbook en dernier

lastModifiedTime

string

x

Dernière date de modification du workbook

accessToken

string

Jeton d'authentification pour ce workbook

IV-C - WorkSheet

Comme son nom l'indique, le WorkSheet est la feuille de votre workbook. Si vous ne voyez pas de quoi il s'agit, et bien il s'agit simplement des pages au sein desquelles vous naviguez en cliquant sur les onglets en bas à gauche.

Structure de l'entité WorkSheet.

Nom

Type

Modif.

Req.

id

string

Identifiant de la feuille

path

string

Chemin complet de la feuille

name

string

x

Nom de la feuille

index

int

Index de la feuille

workbookId

string

Identifiant du workbook parent (conteneur)

workbook

string

Chemin complet du workbook parent (conteneur)

IV-D - Cell

Une grille contient des cellules ; elles sont désignées ici par « cell ».

Structure de l'entité Cell.

Nom

Type

Modif.

Req.

sheet

string

Nom de la feuille parente (conteneur)

col

int

Index de la colonne

row

int

Index de la ligne

input

int

x

Valeur saisie par l'utilisateur

display

string

Valeur affichée

value

string

Valeur sans formatage de texte

IV-E - Ouf !

Il y en a d'autres bien sûr, mais nous n'aurons pas besoin d'en savoir plus dans notre exemple.

Pour plus d'informations, voici la liste complète :

- Binary ;

- ErrorLink ;

- SessionInfo ;

- Share ;

- SheetObject ;

- Style ;

- User ;

- WorkBook ;

- WorkSheet ;

- WorkSpace.

IV-F - Configuration

Nous allons regrouper toute notre configuration dans un tableau, d'où les lignes suivantes au début de notre fichier index.php, lignes qui pourraient être placées dans un fichier de configuration par exemple :

//
// 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]',
);
);

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 :

<?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 :

// 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ée plus haut. Insérons dans la classe EGrid une nouvelle fonction, nommée createDoc :

/**
* 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.

<?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).

/**
* 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 :

<?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 :

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 un jour seulement.

VI - Manipulation de données

VI-A - Introduction

Il est possible de récupérer ou modifier des données sans avoir à afficher la grille dans l'une de vos pages.
Voici quelques-unes des fonctions qui vous seront utiles :

- worksheet.list ;

- cell.list ;

- cell.set.

D'autres fonctions existent bien sûr, mais celles-ci nous suffiront dans notre exemple.

VI-B - Lister les feuilles d'un document

Les méthodes que nous allons désormais utiliser se réfèrent les unes aux autres, c'est pourquoi nous allons voir d'un seul coup plusieurs d'entre elles, qui sont, je l'espère, facilement compréhensibles.

Comme d'habitude, insérez le code suivant dans votre fichier EGrid.php :

/** Obtenir la liste des feuilles d'un document
* @param        [string]    nom du document
* @return        [array]        tableau d'objets worksheet
*/
function getSheet($name) {

global $config;

$workbook_name = $config['workspace'] . "/$name";

$result = $this->call(
'worksheet.list',
array('workbook'    =>    $workbook)
);
if ($result->hasError()) trigger_error($result->getError()->toString(), E_USER_ERROR);

// construction du tableau
$tSheet = array();
foreach ($result->getValue() as $sheet) {
$tSheet[] = array(
'id'    =>    $sheet->id,
'path'    =>    $sheet->path,
'name'    =>    $sheet->name,
'index'    =>    $sheet->index,
);
}
return $tSheet;
}
?>

Nous avons utilisé la fonction worksheet.list.

VI-C - Récupérer le contenu d'une feuille

Nous utiliserons la fonction getSheet() que nous venons de définir, et la fonction cell.list.

/** Obtenir le contenu d'une ou plusieurs cellules
* @param            [string]    nom du document
* @param        [string]    nom de la feuille (sheet)
* @param        [string]    marque début des données à récupérer ex. : "A1")
* @param        [string]    marque fin des données à récupérer ex. : "C4")
* @return        [array]    tableau d'objets cell
*/
function getCell($name $worksheet, $cellFrom, $cellTo) {
global $config;

$workbook_name = $config['workspace'] . "/$name";
$result = $this->call(
'cell.list',
array(
'workbook'    => $workbook,
'range'        => "$worksheet!$cellFrom:$cellTo",
)
);
if ($result->hasError()) trigger_error($result->getError()->toString(), E_USER_ERROR);

// construction du tableau
$tCell = array();
foreach ($result->getValue() as $cell) {
$tCell[] = array(
'col'        =>    $cell->col,
'row'        =>    $cell->row,
'input'        =>    $cell->input,
'display'        =>    $cell->display,
'value'        =>    $cell->value,
'sheet'        =>    $cell->sheet,
);
}
return $tCell;
}
?>

VI-D - Modifier un document

/** Insérer du contenu dans un document
* @param        [string]    nom du workbook
* @param        [string]    range
* @param        [array]    cellules (objets cell)
* @return        [bool]    vrai / faux
*/
function insertData($name, $range, $cells) {
global $config;

$workbook = $config['workspace'] . "/$name";

$xml = "<list>";
foreach ($cells as $c){

$xml .= "<cell>
<value>".$c['value']."</value>
<row>".$c['row']."</row>
<col>".$c['col']."</col>
<sheet>".$c['sheet']."</sheet>
<display>".$c['display']."</display>
<input>".$c['input']."</input>
</cell>";

}
$xml .= "</list>";
$xml = utf8_encode($xml);

$workbook = $this->call(
"cell.set",
array('workbook' => $workbook,'range'=>$range,'s' => $config->EditGrid['sessionKey']),
$xml
);
if ($workbook->hasError()) trigger_error($workbook->getError()->toString(), E_USER_ERROR);

return true;
}
?>

VI-E - Exemple récapitulatif

Nous avons nos méthodes, reste à nous en servir !

Nous allons voir maintenant comment fonctionnent nos méthodes.
Nous allons :

1. Instancier un objet EditGrid ;

2. Lister toutes les feuilles d'un document ;

3. Afficher le contenu d'une partie du document à l'écran.

<?php
$config = array (
'appKey'               =>    'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'user'            =>    'user/monnom',
'sessionKey'           =>    'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'authToken'        =>    'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',    // depuis http://www.EditGrid.com/developer/sessionkey
'name'            =>    'mondocdetest',
'workspace'        =>    '/user/monnom',
'workbook'        =>    '',
);

//
// appel des classes
//
require 'includes/editgrid.php';
require 'includes/EGrid.php';

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

// listons les feuilles du document
$tFeuille = $editgrid>getSheet($config['name']);
echo 'Voici la liste des feuilles :';
foreach ($tFeuille as $feuille) {
echo 'La feuille dont le nom est ' . $feuille['name'];
echo ' a pour identifiant : '.$feuille['id'];
echo '<br />';
}

// récupérons le contenu des cellules A1 et B1 de notre première feuille
$tCell = $editGrid->getCell($config['name'], $tFeuille[0], 'A1', 'B1';
echo 'Voici le contenu de la feuille '.$tFeuille[0]['name']. ': ';
foreach ($tCell as $cell) {
echo "la cellule dont les coordonnées sont ({$cell['row']}, {$cell['col']})
a la valeur [$cell['value']}<br />";
}

VII - À l'écran : le JavaScript

VII-A - Introduction

Maintenant que nous avons vu un peu comment gérer nos documents en PHP, donc dans un langage serveur, en manipulant nos documents hors affichage, il est intéressant de voir comment nous allons pouvoir interagir avec la grille EditGrid du côté du navigateur.

En toute logique, la grille est affichée à l'écran, les modifications doivent se faire chez le client… Nous allons donc opérer en JavaScript.

Nul besoin d'être un expert, les fonctionnalités que nous allons aborder ici sont basiques. Toutefois, nous ne nous arrêterons pas en détail sur chaque élément du code livré. En effet, les fonctionnalités « Grid » (JavaScript) sont très bien documentées sur le site officiel, il ne sert à rien dans notre apprentissage de reproduire une documentation qui existe déjà.
Aussi, nous nous contenterons de voir des exemples de ce qu'il est possible de faire dans la gestion et la manipulation de grilles EditGrid.

Vous trouverez la documentation JavaScript en suivant ce lien.

L'affichage d'une grille dans votre site est simple. La procédure est expliquée ici.

VII-B - Préalable : convertir des coordonnées de type « 0,0 » en « A1 »

Quand nous interagissons avec notre document, nous avons des coordonnées en valeurs numériques entières. Or nous avons besoin de connaître les coordonnées d'une cellule comme elle se présente sous Excel, sous la forme d'un assemblage de lettres et d'entiers (ex. : B2, C3…). Voici une petite fonction pour effectuer cette conversion :

//
//    tableau de lettre
//
function toAlpha(col, line) {

var alpha = ['A','B','C', 'D', 'E', 'F',
'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N',
'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'W',
'W', 'X', 'Y', 'Z'];
if(col > alpha.length) { return false; }

// la première de la grille est 0, mais 1 à l'affichage
// (la grille démarre à A1, et non A0 à l'affichage) : on incrémente le numéro de ligne.
line++;

return (alpha[col] + line);
}

//
// Exemple
//
var col = 1;
var row = 1;
alert(toAlpha(col, row);

// résultat : B2

Voilà, c'est aussi simple que ça !

VII-C - Naviguer entre les feuilles

On ne sait jamais, peut-être pourriez-vous avoir besoin de naviguer entre les feuilles, et d'afficher la feuille suivante, la feuille précédente…

Ces exemples nous permettront de voir :

- comment connaître la feuille active : grid.getActiveSheet() ;

- comment changer de feuille active : grid.setActiveSheet() ;

- lister les feuilles d'un document : workbook.getSheets().

function goToNextSheet() {
var book = grid.getWorkbook();

// feuille active :
var sheet = grid.getActiveSheet();
var id = sheet.getId();

// total des feuilles :
var sheets = book.getSheets();

// trouver num feuille active
var idToActivate = 0;
for (var i = 0; i < sheets.length; i++) {
if(sheets[i].getId() == id) {
if(parseInt(i) + 1  >= parseInt(sheets.length)) {
idToActivate = sheets[0].getId();
} else {
idToActivate = sheets[parseInt(i) + 1 ].getId();
}

}
}
// suivant
grid.setActiveSheet(idToActivate);
}

VII-D - Récupérer le contenu de la sélection

Le curseur fait partie de l'objet grid, cet objet que nous appelons en initialisant notre grille. Il est récupéré grâce à la fonction grid.getCursor().

// curseur
var cursor = grid.getCursor();

// dimensions de la sélection
var rowFrom = cursor.getRangeRef().rowFr; //row from
var rowTo = cursor.getRangeRef().rowTo; //row to
var colFrom = cursor.getRangeRef().colFr; //column from
var colTo = cursor.getRangeRef().colTo; //column to

//
// PROBLÈME : comment traiter nos données si l'utilisateur a fait une sélection inverse, c'est à dire
// de bas en haut, ou de droite à gauche
// (si par exemple la cellule source de la sélection est C3, celle de destination, B2) ?
// il faut toujours prendre la sélection dans le même sens :
if(rowFrom > rowTo) {    old = rowFrom;    rowFrom = rowTo;    rowTo = old;     }
if(colFrom > colTo) {    old = colFrom;    colFrom = colTo;    colTo = old;     }

var widthSel = parseInt(rowTo) - parseInt(rowFrom);
var heightSel = parseInt(colTo) - parseInt(colFrom);

// construire le texte
for (var line=rowFrom;line < rowTo +1 ;line++) {

for (var column=colFrom;column < colTo + 1;column++) {

cellName = toAlpha(column, parseInt(line));
cell = sheet.getCell(cellName);
contenu = cell.getText();
alert(contenu);

}

}

Nous voyons dans ce code différents objets, comme les objets cell, sheet…
Cell est une cellule, Sheet une feuille. À chacun de ces objets sont associés des propriétés, dont vous pouvez trouver une liste exhaustive sur la documentation officielle.

VII-E - Ajouter / Supprimer des feuilles

Voici deux fonctions pour ajouter ou supprimer des feuilles.
Pour une utilisation réelle, il convient d'adapter ces fonctions : il est bien évident que les noms des feuilles, tels qu'ils sont générés dans notre exemple, peuvent être des doublons et donc provoquer des erreurs. Toutefois, pour plus de simplicité nous ne tiendrons pas compte de ce problème ici.

Ce script fait appel aux fonctions workbook.addSheetNexTo() et workbook.deleteSheet().

function addFeuille() {
var book = grid.getWorkbook();
var sheet = grid.getActiveSheet();
var id = sheet.getId();
var nbSheets = book.getSheets();
nbSheets = parseInt(nbSheets.length);
book.addSheetNextTo(id, "Feuil" + nbSheets, true)
}
function delFeuille() {
var book = grid.getWorkbook();
var sheet = grid.getActiveSheet();
var id = sheet.getId();
book.deleteSheet(id);
}

VII-F - Modifier le contenu d'une cellule de la feuille active

Ce code très simple fait appel à la fonction cell.setText().

// identifions notre cellule : C3
var sheet = grid.getActiveSheet();
cellName = 'C3';
var cell = sheet.getCell(cellName);

// modifions le contenu de la cellule C3 :
cell.setText('et hop !');

VII-G - Personnalisation : cacher le menu

Il est possible de personnaliser l'affichage de la grille : ajouter des menus, des liens … Tout se fait grâce aux fonctions UI.
Les exemples de la documentation sont bien faits, je vous conseille donc de vous y reporter pour plus d'informations. Toutefois, il n'est nulle part indiqué comment supprimer tous les éléments du menu (cacher la barre de menu). C'est pourquoi voici un petit script qui fera ça pour vous.

Ce script, à placer juste après l'appel de la grille dans votre code, utilise les fonctions grid.getMenuBar(), et appelle la fonction remove(obj) de cet objet.
obj peut être soit le numéro du menu, soit son nom.

//
//
// suppresion de la barre de menu
//
var menuBar = grid.getMenuBar()
for(var i = 0; i < 9; i++) {
menuBar.remove(0);
}

VIII - Liens & fichiers utilisés

Voici les principaux liens utiles pour l'utilisation des API que nous avons traitées ici :

- Site web ;

- Espace développeur ;

- Forum développement ;

- Documentation « Web API » (PHP) ;

- Documentation « Grid API » (JavaScript).

Et les fichiers que nous avons utilisés (qui contiennent certaines fonctions utiles, mais que nous n'avons pas évoquées ici), soit :

- La classe EGrid
Fonctions : createDoc(), deleteDoc(), openDoc(), getData(), getSheet(), insertData()

- Le fichier index.php

- Le fichier functions.js
Fonctions : toAlpha(), mergeAndCombine(), unMergeAndCombine(), addFeuille(), delFeuille(), goToNextSheet(), goToPrevSheet(), goToLast(), goToFirst()

Pour les obtenir, téléchargez cette archive (4 Ko).

IX - Pour finir…

EditGrid est une solution complète pour tous ceux qui ont besoin d'utiliser des tableurs en ligne. L'installation est simple et rapide, et les fonctionnalités nombreuses, le tout avec une interface agréable.

Même s'il n'est pas toujours possible d'éviter de passer par des solutions tierces, de type Spreadsheet_Excel_Writer, le site évolue beaucoup en ce moment, et on peut espérer encore plus dans l'avenir.

N'hésitez pas à utiliser ce webservice, il est très pratique et assez facile à utiliser.

En espérant que ce tutoriel saura vous être utile, je tiens à remercier vivement Yogui pour son aide et ses conseils dans la rédaction de ce tutoriel.