Office 365: introduzione allo sviluppo - add-ins
Introduzione
Questo post è il primo di una una serie dedicata allo sviluppo di applicazioni Office 365, dove vedremo quali sono le opportunità che questa piattaforma offre agli sviluppatori, quali tecnologie mette a disposizione per creare nuove esperienze utente e come fare per utilizzarle al meglio.
Ma vediamo di partire dall’inizio.
Che cos’è Office 365?
La risposta più comune a questa domanda è che si tratta della nuova suite di servizi, che ci offre la possibilità di utilizzare le applicazioni Office dovunque ci troviamo e da qualunque dispositivo.
Ma non si tratta soltanto di questo. Office 365 è anche (e soprattutto) una piattaforma che permette di sviluppare e distribuire applicazioni, e di farlo attraverso uno Store che offre nuove possibilità di business e di visibilità per sviluppatori e ISV.
Possiamo integrare funzionalità di Office nelle nostre applicazioni grazie alle Office 365 APIs, oppure creare add-ins che possono essere utilizzati all’interno delle applicazioni Office e grazie ai quali raggiungere milioni di utenti in tutto il mondo.
Con le Microsoft Graph APIs (precedentemente chiamate Office 365 Unified API) viene fornito un unico end-point per accedere ai diversi servizi Microsoft, ottenere informazioni su utenti, gruppi, files, mail, calendari ecc., semplificando moltissimo la gestione dei tokens e le relazioni fra i servizi stessi, indipendentemente dalla piattaforma o dal fatto che si stia sviluppando una Web App oppure una Mobile App nativa.
In questo primo post inizieremo a vedere in dettaglio come creare un add-in, ma se volete cominciare ad esplorare e testare il funzionamento delle APIs potete visitare il sito:
http://dev.office.com/getting-started/office365apis
dove trovate inoltre tutte le risorse e le guide per iniziare a sviluppare incredibili applicazioni per Office 365.
Office Add-ins
Come dicevamo, in questo post verrà illustrato nel dettaglio come creare da zero un add-in per Office 365 utilizzando Visual Studio 2015.
Prima di iniziare però, è necessario capire meglio che cos’è un add-in per Office 365 e quali tipi di add-in possiamo generare e distribuire tramite lo Store di Office (e non solo).
In sostanza un add-in è una applicazione web che viene eseguita all’interno di Office 365 (Word, Excel, Outlook ecc.) e che, grazie ad apposite API JavaScript, ci permette di interagire con l’ambiente Office aggiungendo funzionalità e/o servizi.
Ci sono principalmente 3 tipi di add-in che possiamo creare: Contextual Pane, Task pane e Embedded Content
Il Contextual pane è un pannello contestuale all’interno di un messaggio di posta, un contatto o un appuntamento del calendario, Questo tipo di add-in è quindi utilizzabile da Outlook (desktop e web access)
Il Task pane è un pannello laterale all’interno dell’applicazione che permette di interagire sia in lettura che in scrittura con il contenuto del documento. Questo tipo di add-in è utilizzabile con Excel, Word, Power Point e Project
L ’Embedded content è invece un’area interna al documento stesso ed è utilizzabile con Excel e Power Point
Tutti questi tipi di add-in girano sia sulle versioni desktop che sulle versioni web e mobile (quindi anche iOS e Android) delle applicazioni Office 365, risultando quindi completamente cross-platform.
Ora che abbiamo completato l’introduzione, possiamo passare alla parte vera e propria di sviluppo, andando a creare un add-in di tipo Task pane per Excel che vada a generare automaticamente una tabella popolata con dati di esempio, partendo dalla cella selezionata.
Per prima cosa lanciamo Visual Studio e creiamo un nuovo progetto di tipo Office Add-in che chiameremo ExcelAddInDemo
Una volta cliccato su OK ci viene presentato il wizard che ci consente di scegliere qualo tipo di add-in vogliamo creare. Selezioniamo Task pane e clicchiamo su Next.
Nel passaggio successivo lasciamo selezionato solamente Excel e clicchiamo su Finish
A questo punto Visual Studio genera una nuova solution con 2 progetti:
un progetto ExcelAddInDemo contenente solo il file manifest che definisce le proprietà del pacchetto che verrà deployato (ExcelAddInDemoManifest); e un progetto ExcelAddInDemoWeb che è di fatto l’applicazione web che verrà eseguita nel Task pane.
Come potete vedere, la struttura del progetto ExcelAddInDemoWeb è quella di una classica applicazione web, dove possiamo costruire l’interfaccia grafica mediante pagine HTML e definirne il comportamento con JavaScript.
Iniziamo dunque ad analizzare la pagina principale dell’applicazione, che troviamo sotto la cartella AddIn/Home.
Aprendo il file Home.html possiamo notare che fra gli script inclusi c’è anche uno script office.js. Questo script ci permette di avere a disposizione le API necessarie per interagire con il contenuto del documento Office. Grazie a queste API potremo leggere e scrivere dati, creare fogli, tabelle, grafici e altro ancora.
Se avete Office installato, potete già provare ad eseguire il programma così com’è, ed iniziare a vedere come si presenta il nostro Task pane all’interno di Excel.
All’avvio dell’applicazione, Visual Studio si occuperà di far partire IIS sulla macchina locale
in modo da far girare la nostra applicazione web e lancerà un’istanza di Excel collegata al debugger. Il risultato è che abbiamo già una prima versione del nostro pannello visibile e funzionante sul lato destro della pagina.
Arrestiamo quindi il debug e cominciamo a modificare la home page in modo da adattarla alle nostre necessità.
Nel progettare l’interfaccia grafica, è bene utilizzare un responsive front-end framework chiamato Office UI Fabric, che ci mette a disposizione molti elementi quali font, icone, colori o animazioni, e grazie ai quali possiamo facilmente dare al nostro add-in il look and feel tipico delle applicazioni Office.
Per includere il framework dobbiamo referenziare il CSS dalla CDN (oppure scaricarlo da GitHub qui ) aggiungendo queste righe nella sezione <head> del file home.html
<link rel="stylesheet" href="//appsforoffice.microsoft.com/fabric/1.0/fabric.min.css">
<link rel="stylesheet" href="//appsforoffice.microsoft.com/fabric/1.0/fabric.components.min.css">
poi andiamo a sostituire il bottone utilizzando il controllo di UI Fabric in questo modo
<button class="ms-Button ms-Button--primary" id="crea-tabella">
<span class="ms-Button-icon">
<i class="ms-Icon ms-Icon--plus"></i>
</span>
<span class="ms-Button-label">Crea Tabella</span>
<span class="ms-Button-description">Crea una nuova tabella con i dati di test</span>
</button>
Analizzando questo codice possiamo notare che i controlli derivano dalle classi del framework (ms-Button, ms-Icon ecc…) e che al bottone è stato assegnato un id “crea-tabella” che ci servirà lato JavaScript per recuperare il riferimento al controllo e sottoscrivere l’evento di pressione del pulsante (click).
Aggiungiamo infine un campo con id “error-log” per visualizzare eventuali errori
<p/>
<p id="error-log"></p>
A questo punto possiamo aprire il file Home.js per implementare la funzione di generazione del contenuto all’interno del foglio di Excel quando viene premuto il bottone.
Per prima cosa cancelliamo interamente la funzione getDataFromSelection(), poi modifichiamo la riga di codice jQuery che troviamo nella Office.Initialize per farla puntare al nostro nuovo bottone.
Il risultato finale dovrebbe essere questo:
/// <reference path="../App.js" />
(function () {
"use strict";
// The initialize function must be run each time a new page is loaded
Office.initialize = function (reason) {
$(document).ready(function () {
app.initialize();
$('#crea-tabella').click(creaTabella);
});
};
})();
Non ci resta che creare la funzione creaTabella nella quale ci occuperemo di generare il contenuto di prova sotto forma di tabella utilizzando l’apposita API di Office.
function creaTabella() {
//creo un oggetto tabella
var miaTabella = new Office.TableData();
//aggiungo le intestazioni di colonna
miaTabella.headers = ['Nome', 'Cognome'];
//Aggiungo un array di righe con i dati di test
miaTabella.rows = [['Mario', 'Rossi'], ['Franco', 'Bianchi'], ['Luca', 'Verdi']];
//utilizzo l'API per generare la tabella nel foglio
Office.context.document.setSelectedDataAsync(miaTabella, { coercionType: Office.CoercionType.Table },
function (result) {
var error = result.error
if (result.status === Office.AsyncResultStatus.Failed) {
$('#error-log').text(error.name + ": " + error.message);
}
});
}
Siamo finalmente pronti a testare il nostro primo add-in!
Facciamo quindi partire il debugger da Visual Studio e, una volta avviata l’istanza di Excel, proviamo a cliccare sul bottone “Crea Tabella” (che come noterete ha l’aspetto tipico dei pulsanti Office).
Il risultato sarà la generazione di una nuova tabella posizionata a partire dalla cella attualmente selezionata (nel mio caso A1)
Come avete potuto constatare, in pochi minuti e con il minimo sforzo, abbiamo creato il nostro primo add-in per Office 365!
Il progetto completo è disponibile su GitHub: https://github.com/mamarche/ExcelAddInDemo
Nei prossimi post vedremo come utilizzare le Microsoft Graph APIs per creare applicazioni connesse ai dati di Office 365 e i passaggi necessari per la pubblicazione degli add-ins sullo Store di Office.
Link utili:
http://dev.office.com/getting-started
https://github.com/OfficeDev/office-js-docs
http://officesnippetexplorer.azurewebsites.net/#/add-in/excel
https://github.com/OfficeDev
Good coding!