Présentation du contrôle communautaire “Digital signature”

Comme promis dans l’article de Jean sur les projets remarquables de la communauté K2, voici un billet vous présentant le contrôle « Digital signature pad ».

Je vous expliquais alors que ce contrôle Smartforms permet de capter et afficher des signatures “manuscrites” sur les formulaires K2, mais que malheureusement, ce dernier manquait de documentation sur comment l’installer et l’intégrer à ses formulaires.

Je vais donc tâcher de corriger cet impair en vous expliquant tout ce que vous voulez savoir sur ce fameux composant.

Cet article s’articule en 3 parties :

  • Téléchargement
  • Installation
  • Ajout à un formulaire

1 – Téléchargement

Sur le Market du site Community, un premier obstacle se dresse devant nous : il y a 4 versions de disponibles pour ce contrôle !

Pas de panique, ces 4 versions sont là parce que chacune d’entre elles a été créée par des membres différents de la communauté K2 à partir d’une version précédente, afin de l’améliorer.

Logiquement, la version qui nous intéresse est la dernière en date, disponible au lien suivant : http://community.k2.com/t5/K2-blackpearl/Digital-Signature-v3/ba-p/93216

2 – Installation

Comme d’habitude lorsqu’on télécharge quelque chose provenant du Market K2, on récupère une archive ZIP.

Une fois l’archive décompressée, la panique vous envahit à nouveau : l’arborescence est tout sauf claire et le fichier read me pour le moins laconique !

À la racine de l’archive décompressée, il y a deux répertoires « Deploy » et « Source ». C’est bien entendu le dossier « Deploy » qui nous intéresse pour le déploiement qui, vous verrez, est finalement assez simple.

Le dossier « Source » contient lui l’ensemble de la solution Visual Studio, si l’envie vous prend de la modifier/améliorer. Il contient également un package de déploiement K2 avec des exemples sur l’utilisation du contrôle.

Si votre objectif est simplement d’utiliser le contrôle, alors tout se passe dans le répertoire « Deploy ». Il s’y trouve un second fichier read me, nous indiquant de d’abord déployer un Smartobject.

 

Notre Smartobject a bien été importé, il apparaît maintenant dans la category “DigitalSignatureObjects” :

Ensuite, nous devons modifier le fichier RegisterCustomControl.bat du répertoire « Release » pour que ses instructions pointent bien vers le dossier d’installation de K2 sur votre serveur, avant de l’exécuter.

Pour que le script fonctionne correctement, j’ai deux sortes de modifications à effectuer :

  • D’abord adapter les paramètres des deux instructions xcopy en mettant le chemin absolu vers la dll
  • Ensuite, si K2 n’est pas installé dans le répertoire par défaut, il faut également modifier les paramètres [destination] des instructions xcopy, ainsi que les deux chemins de ligne de commande suivante

Dans mon cas, j’avais décompressé l’archive du market dans le répertoire C:\EnK2Besoin\Signature\ et K2 est installé dans le répertoire par défaut sur ma machine. Mon fichier BAT modifié ressemble donc à ça :

Je peux maintenant exécuter le script pour finir l’installation du contrôle.

Attention : le script contient une instruction iisreset, qui va provoquer une brève interruption de service. Prenez garde à cela si vous déployez le contrôle sur un environnement où d’autres utilisateurs travaillent !

J’exécute ce script en cliquant droit dessus, puis en choisissant l’option « Exécuter en tant qu’administrateur »

Voilà ! Le control est installé !

3 – Utilisation

Nous avons désormais sur notre serveur deux objets à notre disposition : un smartobject et un contrôle smartforms. Mais que faire de ces éléments ?

3.1 – Capturer une signature

Logiquement, la première étape est de pouvoir capter une signature sur un formulaire. Nous allons donc ajouter un contrôle signature sur la vue ou le formulaire de notre choix.

Une fois déposé sur le formulaire, nous avons accès à l’onglet Properties du contrôle, qui nous permet de paramètrer son apparence sur le formulaire :

Panneau de configuration du control DigitalSignature

Le champ “Title” permet d’afficher une chaîne de caractères au dessus de l’encart destiné à la signature si besoin. Par défaut ce champ contient le mot Signature. Les champs Width et Height permettent de définir respectivement la largeur et la hauteur de l’encart. Par défaut l’encart est large de 200 pixels et haut de 60 pixels.

Mais ça n’est pas suffisant. En s’arrêtant là pour tester le bon fonctionnement du contrôle, vous risquez d’être déçus : rien ne s’affiche à l’écran si ce n’est un genre de label avec le mot « Signature ».

Tout ça pour ça ?!!

Une petite explication s’impose. Le contrôle signature permet de faire deux choses : capturer ou afficher des signatures. Selon le contexte, il doit donc être paramétré différemment.

Pour pouvoir capturer une signature, nous devons exécuter la méthode « Initialise for signing ». On peut par exemple le faire lorsque notre vue s’initialise :

Cette fois-ci, lorsqu’on exécute notre formulaire, un encart apparaît dessus, en dessous du label « Signature », sur lequel nous pouvons dessiner notre signature, soit à la souris, soit directement sur son écran si celui-ci est tactile :

3.2 – Enregistrer une signature

Une fois la signature capturée sur le formulaire, se pose la question de comment l’enregistrer.

Plusieurs options se présentent à nous avec les contrôle et Smartobject DigitalSignature :

  • Enregistrer la signature capturée dans le Smartobject DigitalSignature (l’image de la signature y sera stockée en Base64) et ajouter l’identifiant de la ligne créée dans notre objet métier,
  • Générer du code JSON et le stocker dans notre objet métier.
  • Enregistrer la signature sous forme de fichier dans un objet métier.

Chacune de ces méthodes vient avec ses avantages et ses inconvénients, que je vais m’efforcer de lister en même temps que j’expliquerai comment les appliquer.

3.2.1 – Enregistrer une signature avec le Smartobject DigitalSignature

Dans un premier temps, il faut exécuter la méthode du contrôle DigitalSignature appelée “Save as Image”.

Cette méthode prend deux paramètres facultatifs en entrée : le FQN de l’utilisateur qui a signé, et “Form URL” pour indiquer quel formulaire a été signé.

Paramètres de la méthode Save as Image

La méthode retourne ensuite l’identifiant de la ligne créée dans le SmartObject DigitalSignature, que l’on va récupérer sur notre formulaire pour pouvoir ensuite l’enregistrer dans notre objet métier.

Finalement, une fois tout configuré, notre règle pour enregistrer une signature sous cette forme doit ressembler à ça :

Avantages :

  • Un Smartobject dédié au stockage des signatures, avec toutes les informations a priori nécessaires à la contextualiser.
  • L’image est enregistrée sous forme de code Base64, ce qui permet de l’afficher comme n’importe quelle autre image (plus à ce sujet en partie 3.3).

Inconvénients :

  • Les signatures sont stockées dans un Smartobject Smartbox.
  • L’image est enregistrée sous forme de code Base64, plus gourmand en espace disque que du JSON.
3.2.2 – Enregistrer une signature en JSON

Cette façon de faire est encore plus simple que la première : il suffit de mapper le contrôle DigitalSignature sur le champ où l’on souhaite sauvegarder la signature dans la méthode Save / Create de notre objet métier :

Attention tout de même à avoir une colonne de type nvarchar(MAX) ou Memo afin de bien pouvoir stocker le code JSON de la signature entier, qui représente un nombre élevé de caractères.

Avantages :

  • L’image est stockée directement dans le Smartobject métier.
  • Le code JSON est nettement plus léger que le Base64.

Inconvénient :

  • obligation d’utiliser le contrôle signature pour réafficher la signature, même en lecture seule (plus à ce sujet en partie 3.3).
3.3.2 – Enregistrer une signature en comme un fichier

Ici il faut à nouveau passer par deux étapes pour pouvoir enregistrer la signature. D’abord exécuter la méthode “Get Image to File property” du contrôle DigitalSignature, qui ne prend pas de paramètre et renvoie un fichier qu’il faut mapper vers un contrôle Image Attachment. Puis enregistrer ce contrôle Image Attachment dans notre objet métier.

Avantages :

  • L’image est stockée directement dans le Smartobject métier.
  • L’image est stockée sous forme de fichier, ce qui permet de la télécharger facilement sur son propre ordinateur.

Inconvénient :

  • L’image est stockée sous forme de fichier, ce qui ne permet pas de l’afficher directement sur le formulaire. L’utilisateur doit télécharger le fichier pour pouvoir ensuite l’afficher en local.

3.3 – Afficher une signature

Selon la façon dont vous avez choisi d’enregistrer vos signatures, il faudra utiliser différentes méthodes du contrôle signature.

Si la signature à afficher est stockée sous forme de JSON, une seule solution : la charger dans un contrôle DigitalSignature via la méthode “Display JSON Signature” qui prend en paramètre le code JSON que vous aurez chargé au préalable dans un contrôle intermédiaire depuis votre objet métier.

Pour une signature enregistrée sous forme de fichier, là encore une seule solution : la charger dans un contrôle Image Attachment via la méthode Load, Read ou List de votre objet métier.

En revanche, si vous avez opté pour une sauvegarde en Base64, vous pouvez :

  • comme pour le format JSON l’afficher dans un contrôle DigitalSignature via la méthode “Display Signature Image”, qui prend en paramètre l’ID de la ligne que l’on souhaite charger.
  • ou alors récupérer directement le code base64 de la ligne enregistrée via la méthode Load du SmartObject DigitalSignature dans un contrôle literal (type Data Label), en l’encadrant avec une balise HTML <img />. Pour suivre cette méthode, il faut passer par un contrôle intermédiaire qui stockera le code base64 de l’image et par une expression posée sur notre contrôle literal qui ajoutera autour de la valeur contenue dans notre contrôle intermédiare la balise <img />, comme illustré dans la série de captures d’écran ci-dessous.
On s’assure d’abord que notre control est bien literal

Ça n’est clairement pas la méthode la plus pratique, mais sachez qu’elle existe et qu’elle permet également d’ajouter, pourquoi pas, du CSS à la balise <img /> 

C’est tout pour cette fois, j’espère que cet article vous aura donné envie d’utiliser ce contrôle, qui fait toujours fureur auprès des utilisateurs finaux !

 

Thomas

Chez K2 France depuis 2013, je ne suis pas magicien mais j'ai tout de même quelques tours dans mon sac en matière d'applications K2, dont je veux bien vous révéler les secrets ;-)

3 thoughts to “Présentation du contrôle communautaire “Digital signature””

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.