Les avantages pour vous
Ce tutoriel vous explique comment créer votre première application d'expérience à l'aide d'un ensemble d'outils développeur offerts par Showpad. Il suppose une connaissance de niveau intermédiaire de Showpad et du développement frontend. Si vous êtes débutant en développement, nous vous recommandons de jeter d'abord un coup d'œil à la présentation de nos outils développeur.
Nous allons créer une application d'expérience proposant les fonctionnalités hors ligne suivantes :
- rechercher les ressources par balises
- ajouter des ressources à une collection
- partager des ressources
- télécharger des ressources
Vous allez voir des notes expliquant des trucs, astuces et infos pour les développeurs plus avancés. Vous pouvez tout à fait les ignorer pour suivre ce tutoriel. Au bas de cette page, vous trouverez des fichiers ZIP « avant et après » montrant l'état du projet au début et à la fin.
Les caractères suivants ne sont pas pris en charge dans les titres de fichiers dans une application d'expérience personnalisée : /, ?, #, @, !, $, &, *, +, ;, =.
Remarque : L'application Windows actuelle utilise IE11 comme moteur de rendu. Notre application ne fonctionnera pas dessus, car notre syntaxe va être de type ES6.
Ce qu'il vous faut pour réussir
- accès administrateur à un domaine Showpad
- ressources balisées pour la recherche
- licence Showpad Ultimate
- NodeJs pour installer notre SDK
- Installez le SDK Showpad
- Client OAuth
- Authentification
- Manifest.json
- Config.json
- Index.html
- Serveur de développement SDK
- window.onShowpadLibLoaded
- Traductions
- ShowpadLib.getAssetsByTags
- ShowpadLib.getAssetPreviewUrl
- ShowpadLib.addAssetsToCollection et ShowpadLib.share
- ShowpadLib.upload et ShowpadLib.displayToast
- C'est l'heure de lancer notre application
- Pour finir
Procédez étape par étape
Nous avons préparé un fichier ZIP contenant notre structure de dossiers et certains fichiers. Téléchargez ce ZIP passe-partout de l'application d'expérience et extrayez-le dans un dossier local sur votre système.
Installez le SDK en exécutant la commande suivante :
npm i @showpad/sdk -g
Vous aurez besoin d'un client OAuth pour vous authentifier ainsi que notre application.
- Accédez au backend de Showpad, cliquez sur l'engrenage puis cliquez sur « Intégrations ».
- Cliquez sur « Gérer les clients OAuth » puis cliquez sur le bouton « + » pour en créer un nouveau. Configurez votre client OAuth avec les paramètres suivants :
- Nom : Client développeur
- URL de redirection : https://yourdomain.showpad.biz
- Description : Client OAuth pour le développement d'applications d'expérience
- Site Web : https://yourdomain.showpad.biz
- Ce client doit : cochez toutes les cases
Nous avons à présent notre client OAuth, mais nous devons encore authentifier notre utilisateur sur ce client.
- Modifiez les paramètres en gras de cette URL et collez-la dans un onglet du navigateur. https://yourdomain.showpad.biz/api/v2/oauth2/authorize?client_id=clientid&redirect;_uri=https://yourdomain.showpad.biz&response;_type=code
- Acceptez la requête et votre utilisateur actuellement connecté sera désormais authentifié sur ce client.
Nous allons utiliser le SDK pour créer notre fichier d'authentification.
- Accédez à votre outil de ligne de commande dans notre répertoire et exécutez la commande suivante :
Showpad auth
- Vous devrez répondre à quelques questions. Votre nom d'utilisateur Showpad est votre adresse e-mail. Vous devriez voir un nouveau fichier .showpadconfig.json dans le répertoire.
Le fichier manifest.json contient des informations générales sur votre application d'expérience. Vérifiez bien que vous avez un identifiant unique pour chaque application d'expérience que vous créez et augmentez le numéro de version chaque fois que vous téléchargez une nouvelle version sur Showpad. Copiez et collez la structure suivante dans src/manifest.json. Vous pouvez mettre votre nom dans le champ auteur.
{
"identifier": "com.org.showpad.my.first.experience.app",
"name": "Ma première application d'expérience",
"version": "0.0.1",
"description": "Tutoriel pour créer une application d'expérience",
"author": "Showpad"
}
Le fichier config.json détermine la structure des étiquettes et du contenu qui peuvent être modifiés par l'administrateur Showpad.
- Les « étiquettes » peuvent être des paramètres ou des traductions et sont de format texte.
- Le « contenu » définit les ressources auxquelles votre application et l'utilisateur affecté à votre application doivent avoir accès. Ces ressources seront disponibles hors connexion. Assurez-vous que le fichier config.json ne contient pas de clés d'objet qui pourraient être utilisées par Showpad telles que type, valeur, etc. Si elle est incluse dans la liste suivante, vous ne pouvez pas l'utiliser comme clé personnalisée.
Nous allons ajouter quelques traductions des étiquettes et demander des ressources contenant certaines balises que nous pourrons rechercher plus tard. Copiez et collez la structure suivante dans src/config.json et remplacez ["balise1", "balise2", "balise3"] par les balises que vous utilisez réellement dans le backend. Veillez à ce qu'il existe bien des ressources contenant les balises que vous avez saisies.
{
"version": 1,
"labels": {
"translations": {
"title": {
"value": "Tutoriel",
"description": "Titre"
},
"search_button": {
"value": "Rechercher",
"description": "Bouton Rechercher"
},
"add_to_collection_button": {
"value": "Ajouter à la collection",
"description": "Bouton Ajouter à la collection"
},
"share_button" : {
"value" : "Partager",
"description" : "Bouton Partager"
},
"upload_button" : {
"value" : "Télécharger",
"description" : "Bouton Télécharger"
}
}
},
"contents" : {
"assets" : {
"search": {
"type" : "tags",
"value": { "or": [ "balise1", "balise2", "balise3" ] },
"description" : "Ressources recherchable"
}
}
}
}
La page index.html est la porte d'entrée de notre application d'expérience. C'est ici que vous pouvez configurer votre structure et ajouter toutes les ressources nécessaires, telles que css et js. Le fichier passe-partout contient déjà notre structure. Maintenant que tout est en place, commençons le développement de notre application.
Pour développer des applications d'expérience, nous allons utiliser le serveur de développement SDK. Nous allons ainsi pouvoir injecter la bibliothèque ShowpadLib dans notre application et simuler le comportement de l'application dans une iframe, ce qui sera également le cas sur la plateforme.
- Exécutez la commande suivante dans votre outil de ligne de commande (toujours dans le dossier racine de notre répertoire) pour lancer le serveur.
showpad experience serve
- Un nouvel onglet s'ouvrira sur l'url suivante : http://localhost:9000/. Il y aura déjà des éléments stylisés en place car nous avons chargé des valeurs CSS dans notre page index.html.
Remarque : Si vous souhaitez développer avec un framework comme React, vous pouvez démarrer votre serveur de développement sur un port différent (disons 8080) et pointer le serveur Showpad vers celui-ci. Veillez à ce que votre chemin public soit relatif.
showpad experience serve --host http://localhost:8080
Nous voulons savoir quand Showpad a chargé notre application. Si nous essayons d'appeler les méthodes de ShowpadLib plus tôt, elles échoueront.
- La prochaine chose à faire est de charger notre configuration depuis le fichier config.json pour accéder à nos étiquettes, contenus et ressources. L'objet « assets » contient les ressources que vous avez définis dans le contenu. Ces ressources contiennent toutes les informations nécessaires pour les méthodes ShowpadLib que nous allons utiliser.
- Une fois la configuration chargée, nous allons intégrer ces objets dans la fenêtre afin de pouvoir y accéder facilement partout dans l'application. Copiez et collez le code suivant dans src/js/app.js.
function init () {
console.log(window.labels)
console.log(window.contents)
console.log(window.assets)
}
window.onShowpadLibLoaded = () => {
window.ShowpadLib.getShowpadApi((apiConfig) => {
let url = window.location.href.split('configUrl=')[1].split('&')[0]
url = decodeURIComponent(url)
fetch(url, {
method: 'GET',
headers: {
'Authorization': 'Bearer ' + apiConfig.accessToken,
'Content-Type': 'application/json; charset=utf-8'
}
})
.then(function (response) {
return response.json()
})
.then(function (data) {
window.labels = data.labels
window.contents = data.contents
window.assets = data.assets
init()
})
})
}
Vous devriez maintenant voir vos étiquettes et contenus définis. L'objet « asset » contient des informations fictives sur l'identifiant. C'est le SDK qui nous dit qu'il simule nos ressources.
Remarque : Lors du développement, il peut arriver que les dernières étiquettes et contenus ne se chargent pas tous. Cela peut arriver dans plusieurs situations, par exemple quand vous avez déjà téléchargé une version test. Vous pouvez résoudre ce problème de deux manières. La première consiste à modifier l'identifiant de votre application. La seconde consiste à charger localement votre fichier config.json et à écraser vos objets.
Remarque : Il se peut également que les ressources trouvées ne soient pas à jour. Vous pouvez définir une fonction pour charger les ressources à partir du contenu via l'API REST et les placer sur l'objet. Attention, le résultat avec le SDK sera différent d'avec l'API REST, nous n'encourageons donc pas cette automatisation. La meilleure pratique consiste à définir votre structure à l'avance le mieux possible et télécharger l'expérience sur Showpad, et la prochaine fois que vous développerez, vous disposerez des ressources à jour définies dans votre contenu.
La localisation de votre application d'expérience est très puissante. Vous pouvez ajouter différents champs de langue au même objet ou simplement dupliquer votre application d’expérience et traduire chaque copie dans une langue différente. Nous allons utiliser les traductions que nous avons définies dans notre fichier config.json pour définir notre titre et remplir nos boutons. Lorsque notre application est prête et téléchargée, l'administrateur pourra modifier ces traductions sans codage.
Ajoutez la fonction suivante à src/js/app.js et appelez-la dans la fonction init. Notre application devrait maintenant contenir ces traductions.
function translations () {
document.getElementsByTagName("h1")[0].innerHTML = window.labels.translations.title.value
document.querySelector('#search #search_submit').innerHTML = window.labels.translations.search_button.value
document.querySelector('#actions #actions_collection').innerHTML = window.labels.translations.add_to_collection_button.value
document.querySelector('#actions #actions_share').innerHTML = window.labels.translations.share_button.value
document.querySelector('#upload #upload_submit').innerHTML = window.labels.translations.upload_button.value
}
La prochaine fonctionnalité que nous allons ajouter est la possibilité de rechercher des ressources par balise. Vous pouvez rechercher parmi toutes les ressources affectées à cet utilisateur. Cela signifie que la fonctionnalité n'est pas nécessairement limitée par les balises que nous avons définies dans notre fichier config.json. Pour créer cette fonctionnalité, nous allons utiliser la méthode ShowpadLib.getAssetsByTags(). Toutes les méthodes ShowpadLib sont simulées par le SDK. Vous pouvez voir au lien suivant quelles en sont les limitations et à quoi devrait ressembler le résultat attendu.
- Ajoutez la fonction suivante à src/js/app.js et appelez-la dans la fonction init.
function search () { document.querySelector('#search #search_submit').addEventListener('click', (e) => {
e.preventDefault()
ShowpadLib.getAssetsByTags([document.querySelector('#search input[type=text]').value], (assets) => {
console.log(assets) }) }) } - Si vous recherchez maintenant une ressource que vous avez définie dans le fichier config.json, vous devriez la voir dans la fenêtreconsole.log.
Remarque : Notez que les fonctions ShowpadLib avec la même charge utile sont ignorées lorsqu'elles sont répétées rapidement. Vérifiez toujours la réponse obtenue pour vérifier si un appel a réussi.
Nous voulons maintenant afficher nos résultats à l'utilisateur. Il est possible d'extraire une vignette à l'aide de la méthode ShowpadLib.getAssetPreviewUrl() où nous définissions l'identifiant, le slug et la taille de notre vignette. La valeur par défaut est de 400 et la valeur maximale est de 1600.
Nous voulons également que notre utilisateur ouvre la ressource trouvée pour voir si c'est la bonne. Showpad dispose d'un schéma de fichiers unique qui intercepte ces demandes et ouvre la visionneuse de ressources. Cette URL est construite de la manière suivante : showpad://file/ + assetSlug. La visionneuse de ressources offre également des fonctionnalités natives telles que le partage ou l'ajout de ressources à une collection.
Nos résultats contiendront également une case à cocher pour identifier les ressources que nous voulons partager ou ajouter à une collection. Ajoutez la fonction suivante à src/js/app.js pour afficher nos résultats. Appelez cette fonction dans le rappel de vos résultats de recherche et passez-y les ressources.
function displayResults (actifs) {
document.getElementById('results').innerHTML = ''
for (let key in assets) {
let asset = assets[key]
let assetPreviewUrl = ShowpadLib.getAssetPreviewUrl(asset.id, asset.slug, 400);
let result = document.createElement('div')
result.className = 'result'
let html = '<a href=showpad://file/' + asset.slug + ‘?modal=1>’
html += '<img src="" + ShowpadLib.getAssetPreviezUrl(asset.id, asset.slug,
400) + '" />'
html += '</a><input class="results_checkbox" type="checkbox" data-slug='
+ asset.slug +'>'
result.innerHTML = html
document.getElementById('results').appendChild(result);
}
}
Les résultats devraient à présent apparaître après avoir soumis une recherche. Cliquez sur l'image pour ouvrir la visionneuse de ressources native de Showpad. Nous allons à présent mettre en place un code pour garder une trace des ressources que nous marquons comme actives en cochant la case correspondante. Copiez et collez la fonction suivante dans src/js/app.js et appelez-la dans votre fonction init ().
function actions () {
document.querySelector('body').addEventListener('click', (e) => {
if (e.target.classList.contains('results_checkbox')) {
if (e.target.checked) {
activeAssets.push(e.target.dataset.slug)
} else {
activeAssets = activeAssets.filter(asset => asset !== e.target.dataset.slug);
}
}
})
}
Comme vous pouvez le voir, nous stockons nos ressources dans le tableau activeAssets. Ajoutez-le en haut de votre fichier comme ceci :
let activeAssets = []
Lors d'une recherche, nous voulons veiller à ne pas inclure nos résultats précédents, il faut donc supprimer vos ressources activeAssets dans l'écouteur d'événements de recherche.
ShowpadLib.addAssetsToCollection et ShowpadLib.share
Nous allons maintenant ajouter notre tableau de ressources activeAssets à une collection. Pour cela, nous allons ajouter un écouteur d'événement au bouton et vérifier si notre tableau activeAssets n'est pas vide. Si ce n'est pas le cas, nous allons appeler la méthode ShowpadLib.addAssetsToCollection() et y passer nos ressources. Le rappel nous fournira l'identifiant de la collection à laquelle nos ressources seront ajoutées. Copiez et collez le code suivant dans la fonction actions() dans src/js/app.js.
document.querySelector('#actions #actions_collection').addEventListener('click', (e) => {
e.preventDefault()
if (activeAssets.length > 0) {
ShowpadLib.addAssetsToCollection(activeAssets, (collectionId) => {
if (collectionId) console.log('Assets are added to collection with id: ' + collectionId)
})
}
})
Nous devrions obtenir une réponse du SDK indiquant que notre appel a réussi. Nous voulons faire exactement la même chose avec notre bouton de partage. Pour cela, nous allons utiliser la méthode ShowpadLib.share(). Il nous faudra passer un paramètre si nous voulons pouvoir partager par lien ou par e-mail. Dans notre exemple, nous allons choisir le partage par e-mail. Copiez et collez le code suivant dans la fonction actions() dans src/js/app.js.
document.querySelector('#actions #actions_share').addEventListener('click', (e)
=> {
e.preventDefault()
if (activeAssets.length > 0) {
ShowpadLib.share('email', activeAssets,(result) => {
if (result === 'success') console.log('Ressources partagées avec le client')
})
}
})
Remarque : Vous pouvez toujours vérifier les paramètres qui existent et ceux qui sont requis ici. Notez le numéro de version dans le coin supérieur droit. Toutes les plateformes Showpad n'utilisent pas la même version, certaines d'entre elles risquent donc de ne pas disposer des fonctionnalités dont vous avez besoin. Vous pouvez consulter le lien suivant pour connaître les versions des plateformes.
Si nous testons notre application, le partage devrait à présent également provoquer un rappel. Nous avons créé une application qui peut rechercher des ressources par balises, ouvrir les ressources, ajouter les ressources aux collections et partager les ressources. Une autre caractéristique importante des applications personnalisées est la génération de ressources en fonction des saisies et la possibilité de les enregistrer hors ligne.
ShowpadLib.upload et ShowpadLib.displayToast
La méthode « upload » permet aux utilisateurs de télécharger du contenu généré dans Mes Fichiers. Elle nécessite un nom de fichier et un fichier, et renverra un émetteur d'événement disposant de plusieurs états. Nous allons générer un fichier .txt à partir d'un champ textarea et le passer à la méthode. La méthode ShowpadLib.displayToast() nous permet d'afficher ces états à l'utilisateur via une notification toast native sur chaque plateforme. Copiez et collez la fonction suivante dans src/js/app.js et appelez-la dans la fonction init().
function upload () {
document.querySelector('#upload #upload_submit').addEventListener('click', (e)
=> {
e.preventDefault()
const filename = 'ma_premiere_application_d_experience.txt';
const file = new File([document.querySelector('#upload textarea').value], filename);
const upload = ShowpadLib.upload({
file: file,
filename: filename
})
upload.on('queued', () => {
ShowpadLib.displayToast({
type: "info",
text: "En attente"
})
})
upload.on('uploading', (data) => {
ShowpadLib.displayToast({
type: "info",
text: "Téléchargement de (" + parseInt((data.bytesSent / data.bytesTotal)*100) + "%)"
})
})
upload.on('processing', () => {
ShowpadLib.displayToast ({
type: "info",
text: "Téléchargement en cours"
})
})
upload.on('success', (data) => {
ShowpadLib.displayToast({
type: "success",
text: "Terminé"
})
})
})
}
En testant cela dans notre application, le SDK répondra par le téléchargement et plusieurs réponses sous forme de notification toast. L'objet de données dans le gestionnaire de succès répondra avec notre ressource.
Remarque : Si vous êtes hors ligne, la ressource restera en attente. Attendre que le gestionnaire de succès relâche votre application peut bloquer votre interface hors ligne. Nous suggérons une interface utilisateur non obstructive avec des notifications élégantes sur l'état de traitement.
Au moment de la rédaction de cet article, il n'est pas possible de partager une ressource téléchargée ou de l'ajouter à une collection.
C'est l'heure de lancer notre application ! 🚀
Notre application est à présent prête à être déployée. Nous allons utiliser le SDK pour empaqueter notre application. Accédez à votre outil de ligne de commande dans le répertoire racine de l'application et exécutez la commande suivante :
showpad experience package
- Vous verrez le SDK valider tous nos fichiers et créer un fichier .showpad.
- Vous pouvez maintenant accéder au backend de votre domaine et ouvrir le créateur de canaux.
- Créez un nouveau canal avec le type « Application d'expérience » et sélectionnez notre fichier .showpad nouvellement créé.
- Après le téléchargement, vous devriez voir notre application mais sans l'initialisation du JS. C'est parce que nous appelons notre fonction init() dans l'appel Showpad .getShowpadApi() qui n'est pas exécuté dans l'aperçu. Cet appel fonctionnera dans le frontend.
Si vous cliquez sur modifier, vous verrez la structure que nous avons définie dans le fichier config.json. Comme vous pouvez le voir, vous pouvez modifier les traductions, et ajouter et supprimer des balises à notre application. - Cliquez sur « Publier l'expérience » et attendez que la plateforme publie notre application. Cela peut prendre une minute.
Allez maintenant sur le frontend et ouvrez notre nouveau canal. L'application tutoriel devrait apparaître dans toute sa splendeur. N'hésitez pas à en tester toutes les fonctionnalités.
Vous pouvez trouver la version finie dans le fichier « Experience app codebase » pour comparer les différences avec votre code.
Les pages « Développeur » sont votre source privilégiée de référence lorsque vous développez votre application d'expérience.
Nous vous invitons à poser vos questions dans la rubrique « Communauté » afin que les autres développeurs puissent répondre à vos questions et que tout le monde puisse apprendre les uns des autres.
Bon codage !
