Les API EditGrid pour vos tableurs en ligne

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.

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 !

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);    
}

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.

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);
}

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 !');

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);
}