Quels sont les avantages pour vous ?
Ce tutoriel explique comment développer une première Experience app à l'aide d'un ensemble d'outils de développeur Showpad que nous fournissons. Cela nécessite un niveau de connaissance intermédiaire de Showpad et du développement front-end. Si vous débutez dans le développement, nous vous recommandons de jeter d'abord un coup d'œil à la présentation des outils développeur que nous fournissons.
Nous allons créer une Experience app avec les moyens hors ligne suivants :
- interroger les actifs par balises
- ajouter des actifs à une collection
- partager des actifs
- télécharger des actifs
Vous pouvez trouver plusieurs articles dans lesquels nous donnons des trucs et astuces ainsi que des informations pour les développeurs plus avancés. Vous pouvez ignorer ceci en toute sécurité dans le tutoriel. Au bas de cette page, nous fournissons des fichiers ZIP avant et après, qui indiquent l'état de début et de fin du projet.
Remarque : l'application Windows actuelle utilise IE11 comme moteur de rendu. Notre application ne fonctionnera pas car notre syntaxe sera ES6.
Ce qu'il vous faut pour réussir
- accès administrateur à un domaine de Showpad
- actifs balisés utilisés pour la recherche
- licence Showpad Ultimate
- Node.js pour installer notre SDK
Le moyen rapide d'accéder à la génialité
- Installer le kit SDK de 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
- Envoyons notre application
- Note de fin
Procédez étape par étape.
Nous avons préparé un fichier ZIP avec notre structure de dossiers et quelques fichiers en place ; téléchargez le ZIP standard de l'Experience app et faites une extraction dans un dossier local de votre système.
Vous pouvez le faire avec la commande suivante :
npm i @showpad/sdk -g
Vous aurez besoin d’un client OAuth pour vous authentifier et authentifier notre application.
- Allez au backend de Showpad, cliquez sur la roue dentée puis sur « Intégrations ».
- Cliquez sur « Gérer les clients OAuth » et cliquez sur le bouton « Plus » pour en créer un nouveau. Utilisez les paramètres suivants pour votre client OAuth :
- Nom : client développeur
- URL de redirection : https : //yourdomain.showpad.biz
- Description : client OAuth pour le développement d'Experience apps
- Site Web : https : //yourdomain.showpad.biz
- Ce client doit : cocher toutes les cases
Nous avons maintenant notre client OAuth, mais nous devons authentifier notre utilisateur pour ce client.
- Modifiez les paramètres en gras de cette URL puis 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 demande et votre utilisateur actuellement connecté sera maintenant authentifié pour ce client.
Nous allons utiliser le SDK pour créer notre fichier d'authentification.
- Allez dans votre outil de ligne de commande dans notre répertoire principal et utilisez la commande suivante.
Showpad auth
- Quelques questions vous seront posées. Votre nom d'utilisateur Showpad est votre e-mail. Il devrait y avoir un nouveau fichier .showpadconfig.json dans le répertoire.
Le fichier manifest.json contient des informations générales sur votre Experience app. Assurez-vous que votre identifiant est unique pour chaque Experience app que vous créez et d'augmenter le numéro de version chaque fois que vous téléchargez une nouvelle version sur Showpad. Copiez-collez la structure suivante dans src/manifest.json. Vous pouvez définir l'auteur à votre nom.
{
« identifiant » : « com.org.showpad.my.first.experience.app »,
« nom » : « Ma première experience app »,
« version » : « 0.0.1 »,
« description » : « Tutoriel pour développer une Experience app »,
« auteur » : « Showpad »
}
Le fichier config.json détermine la structure des étiquettes et du contenu pouvant être modifiés par l'administrateur Showpad.
- Les étiquettes peuvent être des paramètres ou des traductions et sont basées sur du texte.
- Le contenu définit les actifs auxquels votre application et l'utilisateur affecté à votre application doivent avoir accès. Ces actifs seront disponibles hors connexion. Assurez-vous que le fichier config.json ne contient pas de clés d'objets pouvant être réservées par Showpad, telles que type, valeur, etc… S'il y en a dans la liste suivante, vous ne pouvez pas l'utiliser comme clé personnalisée : https://showpad.pages.showpad.io/public-sdk/config.json.html.
Nous allons ajouter des traductions dans les étiquettes et demander des actifs avec des balises que nous pourrons rechercher ultérieurement. Copiez-collez la structure suivante dans src/config.json et modifiez [« balise1 », « balise2 », « balise3 »] avec les balises que vous utilisez réellement dans le backend. Assurez-vous qu'il y a des actifs avec les balises que vous avez entrées.
{
"version": 1,
"labels": {
"translations": {
"title": {
"value": "Tutorial",
"description": "Title"
},
"search_button": {
"value": "Search",
"description": "Search button"
},
"add_to_collection_button": {
"value": "Add to collection",
"description": "Add to collection button"
},
"share_button": {
"value": "Share",
"description": "Share button"
},
"upload_button": {
"value": "Upload",
"description": "Upload button"
}
}
},
"contents": {
"assets": {
"search": {
"type": "tags",
"value": { "or": [ "tag1", "tag2", "tag3" ] },
"description": "Searchable assets"
}
}
}
}
Le fichier index.html est le point d'entrée de notre Experience app. Vous pouvez configurer votre structure et ajouter toutes les ressources nécessaires telles que css et js ici. Le standard contient déjà notre structure. Maintenant que tout est en place, commençons le développement de notre application.
Pour développer des Experience apps, nous allons utiliser le serveur de développement SDK. Cela injectera ShowpadLib dans notre application et imitera le comportement de notre application s'exécutant dans une Iframe, ce qui sera également le cas sur la plateforme.
- Entrez ce qui suit dans votre outil de ligne de commande (toujours dans notre répertoire principal) pour démarrer le serveur.
showpad experience serve
- Un nouvel onglet s'ouvre avec l'URL suivante : http : // localhost:9000/. Vous voyez déjà certains éléments stylés en place car nous avons chargé des feuilles de style CSS dans notre fichier index.html.
Remarque : si vous souhaitez développer avec une structure telle que React, vous pouvez démarrer votre serveur de développement sur un autre port (disons 8080) et y pointer le serveur Showpad. Assurez-vous de rendre relatif votre parcours public.
showpad experience serve --host http://localhost:8080
Nous voulons savoir quand Showpad a chargé notre application. Si nous essayons de lancer des méthodes de ShowpadLib plus tôt, cela échouera.
- Nous souhaitons ensuite charger notre configuration depuis config.json pour accéder à nos étiquettes, contenus et actifs. L'objet actifs contient les actifs que vous avez définis dans le contenu. Ces actifs contiennent toutes les informations nécessaires aux méthodes ShowpadLib que nous allons utiliser.
- Une fois que la configuration est chargée, nous allons placer cet objet sur la fenêtre afin de pouvoir y accéder facilement via l'application. Copiez-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',
en-têtes : {
'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. Dans l'objet Actif, nous voyons des informations de mock-id. C'est le SDK qui nous dit qu'il simule le comportement de nos actifs.
Remarque : lors du développement, vous pouvez rencontrer une situation dans laquelle les étiquettes et le contenu les plus récents ne sont pas chargés. Cela peut être dû à diverses situations, lorsque vous avez par exemple déjà téléchargé une version à tester. 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 config.json et à écraser vos objets.
Remarque : il se peut également que les actifs renvoyés ne soient pas à jour. Vous pouvez écrire une fonction grâce à laquelle vous chargez les actifs à partir du contenu via l'API REST et les placez sur l'objet. Attention, le résultat du SDK sera différent de celui de l'API REST ; nous n'encourageons donc pas cette automatisation. La meilleure pratique consiste à définir au mieux votre structure à l'avance, à charger l'expérience dans Showpad et lors de votre prochain développement, vous disposerez des actifs à jour que vous avez définis dans votre contenu.
La localisation de votre Experience app est très efficace. Vous pouvez ajouter différents champs de langue pour le même objet ou simplement dupliquer votre Experience app et traduire chacune d'elles 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 nommer nos boutons. Lorsque notre application est prête et téléchargée, l'administrateur peut 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
}
Nous ajoutons ensuite la possibilité de rechercher des actifs par balises. Vous pouvez rechercher tous les actifs affectés à cet utilisateur. Cela signifie que ce n'est pas nécessairement contenu dans les balises que nous avons définies dans notre fichier config.json. Pour cela, nous utilisons la méthode ShowpadLib.getAssetsByTags (). Toutes les méthodes ShowpadLib sont simulées par le SDK. Vous pouvez voir sur le lien suivant quelles 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 un actif que vous avez défini dans config.json, vous devriez le voir dans la fenêtre console.log.
Remarque : sachez 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 renvoyée pour savoir si un appel a été passé.
Nous voulons maintenant afficher nos résultats à l'utilisateur. Nous pouvons récupérer une vignette en utilisant la méthode ShowpadLib.getAssetPreviewUrl () où nous passons l'identifiant, le slug et une taille de notre vignette. La valeur par défaut est 400 et la valeur maximale est 1600.
Nous voulons également que notre utilisateur ouvre l'actif réel pour voir si c'est le bon. Showpad a un schéma de fichier unique dans lequel il intercepte ces demandes et ouvre l'afficheur d'actifs. Cette URL est construite de la manière suivante : showpad://file/ + assetSlug L'afficheur d’actifs fournit également des fonctionnalités natives telles que le partage ou l’ajout d’actifs à une collection.
Nos résultats contiendront également une case à cocher pour identifier quels actifs nous souhaitons 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 transmettez-lui les actifs.
function displayResults (assets) {
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.getAssetPreviewUrl (asset.id, asset.slug,
400) + '"/ > '
html += '< / a >< input class="result_checkbox" type="checkbox" data-slug='
+ asset.slug +'> '
result.innerHTML = html
document.getElementById('results').appendChild(result);
}
}
Après avoir lancé une recherche, les résultats devraient maintenant apparaître. Nous pouvons cliquer sur l'image pour ouvrir l'afficheur d'actifs natif de Showpad. Nous implémentons maintenant du code pour garder une trace des actifs que nous avons marqués comme actifs en cochant la case. Copiez-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 constater, nous stockons nos actifs dans le tableau activeAssets. Ajoutez ceci en haut de votre fichier comme suit :
let activeAssets = []
Lors de la recherche, nous voulons éviter d'inclure nos résultats précédents. Désactivez donc activeAssets dans l'auditeur d'événements de recherche.
ShowpadLib.addAssetsToCollection et ShowpadLib.share
Nous voulons maintenant ajouter notre tableau activeAssets à une collection. Pour cela, nous ajoutons un auditeur d'événement au bouton et vérifions si notre tableau activeAssets n'est pas vide. Sinon, nous appelons la méthode ShowpadLib.addAssetsToCollection () et transmettons nos actifs. Le rappel nous fournit l'identifiant de la collection à laquelle nos actifs sont ajoutés. Copiez-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 ('Les actifs sont ajoutés à la collection avec l'identifiant :' + collectionId)
})
}
})
Nous devrions voir une réponse du SDK indiquant que notre appel est passé. Nous voulons faire exactement la même chose avec notre bouton de partage. Pour cela, nous utilisons la méthode ShowpadLib.share (). Nous devons passer en paramètre si nous voulons partager par lien ou par e-mail. Dans notre exemple, nous choisissons l'e-mail. Copiez-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 ('Les actifs sont partagés avec le client')
})
}
})
Remarque : vous pouvez toujours vérifier quels paramètres existent et lesquels 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 peuvent donc manquer de fonctionnalités dont vous avez besoin. Vous pouvez vérifier sur le lien suivant quelle plateforme a quelle version.
Si nous testons notre application, le partage devrait également renvoyer un rappel. Nous avons créé une application qui peut rechercher des actifs par balises, ouvrir les actifs, ajouter les actifs aux collections et partager les actifs. Une autre chose importante dans les applications personnalisées est la génération d'actifs basée sur les entrées et la possibilité de sauvegarder ces données hors connexion.
ShowpadLib.upload et ShowpadLib.displayToast
La méthode de téléchargement permet aux utilisateurs de télécharger le contenu généré vers « Mes fichiers ». Elle nécessite un nom de fichier et un fichier, et renverra un émetteur d'événement ayant plusieurs statuts. Nous générons un fichier .txt à partir d'un champ de texte et le transmettons à la méthode. Avec la méthode ShowpadLib.displayToast (), nous pouvons afficher ces statuts à l'utilisateur avec un toast natif sur chaque plateforme. Copiez-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 = 'my_first_experience_app.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: "queued"
})
})
upload.on ('uploading', (data) = > {
ShowpadLib.displayToast ({
type: "info",
text: "uploading (" + parseInt((data.bytesSent / data.bytesTotal)*100) + "%)"
})
})
upload.on('processing', () = > {
ShowpadLib.displayToast ({
type: "info",
text: "processing"
})
})
upload.on ('success', (data) = > {
ShowpadLib.displayToast({
type: "success",
text: "success"
})
})
})
}
En testant cela dans notre application, vous verrez que le SDK répond avec le téléchargement et plusieurs réponses toasts. L'objet des données dans le gestionnaire de réussite renvoie notre actif.
Remarque : en mode hors connexion, l'actif reste en attente. Attendre que le gestionnaire de réussite publie votre application risque de bloquer votre interface hors ligne. Nous suggérons une interface utilisateur non obstructive avec des notifications progressives sur le statut.
Au moment de la rédaction, il n’est pas possible de partager ou d'ajouter un actif téléchargé à une collection.
Envoyons notre application ! 🚢
Notre application est désormais prête à être déployée. Nous allons utiliser le SDK pour conditionner notre application. Allez dans votre outil de ligne de commande dans le répertoire principal de l'application et entrez 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 générateur de canaux.
- Créez un nouveau canal avec le type d’Experience app et sélectionnez notre nouveau fichier .showpad.
- Après le téléchargement, vous devriez voir notre application, mais sans le JS initialisé. C'est parce que nous appelons notre fonction init () dans l'appel Showpad.getShowpadApi () qui n'est pas exécuté dans l'aperçu. Cela 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 constater, vous pouvez modifier les traductions et ajouter/supprimer des balises à notre application. - Cliquez sur « publier l'expérience » et attendez que la plateforme publie notre application. Cela peut prendre une minute.
Si vous allez maintenant au frontend et ouvrez notre nouveau canal, l'application tutorielle devrait apparaître dans toute sa splendeur. Allez-y et testez toutes les fonctionnalités.
Vous pouvez trouver la version complète du code base de l'Experience app ici pour comparer les différences avec votre code base.
Les pages développeur sont votre source d'informations incontournable lors du développement d'Experience apps.
Nous vous invitons à poser vos questions dans la partie communauté afin que les autres développeurs puissent répondre à vos questions et que tout le monde puisse apprendre de tout le monde.
Bon codage !
