Yocto-Visualization (for web) dans votre propre page web

Il y a trois semaines, on vous a montré comment intégrer votre propre page web dans Yocto-Visualization (for web). Cette semaine on se propose de vous expliquer comment faire le contraire, c'est-à-dire intégrer Yocto-Visualization (for web) dans des pages web servies par un serveur web arbitraire.

La problématique

Yocto-Visualization (for web) a surtout été conçu pour pouvoir être hébergé par un YoctoHub, un VirtualHub ou encore une instance de VirtualHub for web en tirant parti du petit serveur web intégré dans ces produits. Mais il est aussi possible de l'intégrer sur votre propre serveur web, par exemple dans une simple page PHP.

L'application Yocto-Visualization (for web) est fournie sous la forme d'un fichier JavaScript, la lancer depuis une page HTML quelconque est donc assez trivial. Ce qui l'est moins, c'est de sauver la configuration quelque part, puis de la récupérer ensuite. C'est tout l'objet de cet article.

Préparatifs

Commencez par télécharger le fichier zip de Yocto-Visualization (for web). Dans le répertoire dist/es2017, vous trouvez quatre parfums de Yocto-Visualization (for web).

yv4web-full.js	Version non minimisée, lecture/écriture
yv4web-full.min.js	Version minimisée, lecture/écriture
yv4web-readonly.js	Version non minimisée, lecture seulement
yv4web-readonly.min.js	Version minimisée, lecture seulement

Les versions en lecture seulement ne permettent pas de modifier la configuration ni les widgets, en fait, tout le code qui sert à l'édition est absent des versions en lecture seule. Les versions minimisées prennent un peu moins de place que les versions non-minimisées, mais sont plus difficiles à debugger. Dans le cadre de cet article, le plus judicieux est de choisir la version yv4web-full.js que vous aurez à copier sur votre serveur web.

Instanciation

Imaginons une simple page web

<HTML>

<BODY>

Hello world...

</BODY>

</HTML>

Pour lancer Yocto-Visualisation (for web) dans cette page, il suffit d'insérer un peu de code JavaScript . Notez qu'il faut impérativement utiliser un script de type module. Même si en principe, tous les navigateurs web supportent les modules depuis environ 2018, il est de bon ton de détecter le cas contraire.

<HTML>

<BODY>

Hello world...

</BODY>

<script type="module">

 import { YWebPage} from "./yv4web-full.js";

 YWebPage.run("", null,null);

</script>

<script nomodule="">

 document.write("<p>Yocto-Visualization (for web)"

 +"cannot run on this browser. Sorry.<br>"

 +"Consider using a more recent browser.</p>")

</script>

</HTML>

C'est un début, mais si vous essayez de charger cette page dans votre navigateur, Yocto-Visualization (for web) va râler parce que la configuration est vide et qu'il n'est pas possible d'en créer une nouvelle. Autrement dit, c'est inutilisable en l'état.

Chargement de la configuration

Yocto-Visualisation (for web) sauve sa configuration dans une chaîne de caractère au format XML, c'est le premier paramètre de la fonction YWebPage.run. Pour les besoins de la démonstration, vous pouvez en obtenir un exemple en exportant la configuration d'une autre instance de Yocto-Visualization (for web), ou même en récupérant celui de la version native. Imaginons que ce code XML soit stocké dans un fichier config.xml sauvé même endroit que votre page web. Le code PHP pour charger ce fichier et le fournir à la page web est assez simple:

<HTML>
<BODY>
Hello world...
</BODY>
<script type="module">
import { YWebPage} from "./yv4web-full.js";
<?php
define("CONFIGFILENAME" , "config.xml");
$config="";
if (file_exists(CONFIGFILENAME))
$config = file_get_contents(CONFIGFILENAME);
Printf("YWebPage.run(%s, null,null)",json_encode($config ));
?>
</script>
.....
</HTML>

Maintenant qu'on est capable de charger une configuration, il s'agit de la sauver et c'est là que les choses se compliquent un peu.

Sauvegarde de la configuration

Le troisième paramètre de la fonction YWebPage.run est une fonction de callback que vous devez fournir. Cette fonction sera automatiquement appelée par Yocto-Visualisation (for web) à chaque fois que l'utilisateur sauve. Elle prend deux paramètres:

Le premier est la chaîne de caractères XML qui contient la configuration
Le deuxième est un callback à appeler une fois la sauvegarde terminée. Ce callback prend deux paramètres:
- Un booléen qui indique si l'opération s'est bien passée.
- Une chaîne de caractères détaillant ce qu'il s'est passé.

Si le callback de sauvegarde n'est pas fourni, c'est-à-dire si le troisième paramètre de YWebPage.run est mis à null, Yocto-Visualization (for web) fonctionnera alors en mode lecture seule: l'utilisateur ne pourra pas modifier quoi que ce soit.

Dans le cas qui nous intéresse, on cherche justement à sauver, on va donc écrire une fonction JavaScript saveNow() qui se chargera d'envoyer la configuration sur le serveur PHP sous la forme d'un POST HTTP, et on passera cette fonction saveNow() en paramètre à YWebPage.run.

Il ne nous reste plus qu'à écrire la partie serveur qui se charge de récupérer les données du POST HTML et de les sauver. Notez qu'en termes de sécurité, le minimum syndical consiste à vérifier que le POST contient bien des données XML. Vous n'avez pas forcément envie qu'un petit rigolo utile ce mécanisme pour placer un fichier arbitraire sur votre serveur. Pour que l'exemple reste concis, on a choisi que placer ce code dans la page web elle-même tout au début, mais ce n'est pas une obligation, vous pouvez parfaitement mettre ce code dans un fichier à part.

<?php
define("CONFIGFILENAME" , "config.xml");
if( isset($_POST['xml']) )
{ $status = array("ok"=>false, "msg"=>"");
$XMLdata = $_POST['xml'];
//makes sure it looks like an XML file
$ok = @simplexml_load_string($XMLdata);
if ($ok)
{ if (@file_put_contents(CONFIGFILENAME, $XMLdata)===false)
$status["msg"] = "cannot write config file";
else
$status["ok"] = true;
}
else $status["msg"]="invalid xml config data";
print(json_encode($status));
die();
}
?><HTML>
Hello world...

Notez que pour rendre le mécanisme un peu plus convivial, on renvoie le résultat de l'opération de sauvegarde sous la forme d'une structure JSON que la page web pourra parser, pour ensuite passer le résultat à la fonction de callback fournie par Yocto-Visualisation (for web)

 if (xhr.readyState == 4 && xhr.status == 200 )

 { let res = JSON.parse(xhr.response);

 let desc = res.ok?"Saved":"Save failed: "+res.msg;

 completedCallback(res.ok, desc);

 }

Voilà, voilà, on a fait le tour de la question. Vous savez maintenant comment intégrer Yocto-Visualization (for web) dans votre propre page PHP. Vous trouverez tous les bouts de code décrits ci-dessus rassemblés dans un exemple complet que vous pouvez télécharger ici. Bien entendu, vous pouvez améliorer le concept en utilisant le mécanisme des DIV de positionnement.

Tadaaa! ça marche

Et le deuxième paramètre ?

Les plus attentifs d'entre vous auront remarqué que YWebPage.run prend trois paramètres. Celui du milieu est un aussi un callback qui est appelé à chaque fois que la configuration d'un module Yoctopuce change. C'est utilisé pour détecter dynamiquement les changements du fichier de configuration quand ce dernier est stocké sur le filesystem d'un YoctoHub. Mais cette technique n'est pas applicable dans notre cas.

Un dernier détail

Pour finir, rappelez-vous que, même si le fichier JavaScript et la sauvegarde de la configuration de Yocto-Visualization (for web) sont gérés par votre serveur PHP, l'application elle-même tourne toujours dans votre navigateur web, ce dernier doit donc avoir accès aux modules Yoctopuce que vous souhaitez utiliser, quitte à passer par un VirtualHub for web.

Enfin, vous trouverez ci-dessous une liste d'autres articles faisant référence à Yocto-Visualization (for web).