Saturday Jul 27, 2013

Signature Capture Demo

Many customers, partners and mobile developers have been asking how to provide this via ADF Mobile.  Here is an example that use the JQuery UI signature capture extension along with the JQuery UI Touch Punch extension.  You can find more info about JQuery UI here, more about the JQuery UI signature capture plugin here and finally more info on JQuery UI Touch Punch here


Overview

The main goal of this demo is to show how to use the signature capture component on an AMX page.  Using it on a plain HTML page is provided in the signature capture link above.  The key point to putting in an AMX page is that you can use AMX components to control and manipulate the signature capture control as well as have a consistent styling across them.

What the JQuery Signature capture plugin provides, is a way for the user to draw on the screen, and provides some APIs to control the drawing area.  It also provides an API to fetch a JSON version of what was drawn in the area that can saved and later redrawn into another signature capture or converted to an image later.  The latter is left up to the developer to do but it should be quite easy.

The full source for this completed demo is available here.   This code is based on ADF Mobile version 11.1.2.4.0.

This sample has a single feature with a single AMX page.  That page hosts a signature capture within a Verbatim component.  There are AMX buttons added for Clear (to clear the signature capture area) and Fetch (to return the drawn info as JSON).  When the Fetch is called, the JSON representation of the signature is inserted into the AMX page as text so you can see what was returned.


Step 1 : Get the 3rd Party files and incorporate them into your project

Get JQueryUI, JQuery Signature capture plugin and the JQuery UI Touch Punch plugin.  Each site above has a download link to get the bits you need.  We need only the following files:

Name Description
jquery-ui.css Style sheet for JQuery UI.  Here I've used version 1.9.2
jquery-ui.min.js Minified version of the JQuery UI javascript.  Here I've used version 1.9.2
jquery.signature.css Style sheet for JQuery Signature plugin.  Here I've used version v1.1.
jquery.signature.min.js Minified version of the JQuery Signature plugin.  Here I've used version v1.1.
jquery.ui.touch.js This extension changes mouse events into touch events.  Here I've used version 0.2.2.

Once you've downloaded these files, you'll want to put them into your public_html folder somewhere.  Then you want to go to your adfmf-feature.xml file and in the "Includes" section in the "Content" tab of the feature your adding this to, add an entry for each one.  This will load these files into the feature's webview when it is initialized and thus every AMX page within that feature will have access to them.  It should look like this:



Step 2:  Add the signature capture component to your page

We do this by adding an amx:Verbatim tag to the page.  Here is the verbatim tag added inside the sample:

    <amx:verbatim id="v1">
         <![CDATA[
         <script type="text/javascript">
             (function() {
                 makeSig = function() {
                     try {
                        var sigElement = document.getElementById("sig");
                        if (sigElement == null)
                           alert("sigElement not found");
                        var sigJq = $(sigElement);
                        sigJq.signature();
                        sigJq.signature({guideline: true});
                     }
                     catch (problem) {
                        alert("Problem with verbatim code: " + problem);
                     }
                 }
                 window.setTimeout(makeSig, 250);
             })();
         </script>
         <div id="sig" style="height:200px;width:99%"></div>
         ]]>
     </amx:verbatim>

Notice two things here:  First that you need to specify the div to host the signature component and also add the size you want for the component.  Second is that we needed to set a timeout to fire the code that would replace the contents of the div with the signature component.  This is because there is no hook in AMX currently that fires when the page is fully rendered.  (We'll be adding this in a future release).


Step 3:  Add the Clear and Fetch buttons

Now you need to add your own Javascript file that has some handlers for the Clear and Fetch buttons.  Here's a code example of that Javascript:

  (function () {
      // This method clears the signature area
      doClear = function () {
          var sigElement = document.getElementById("sig");
          if (sigElement == null)
              alert("sigElement not found");
          var sig = $(sigElement);
          sig.signature('clear');
          adf.mf.api.invokeMethod("mobile.MyClass", "FetchCallback", "", onInvokeSuccess, onFail);
      };

      // This method gets the signature as a JSON string.  
      doFetch = function () {
          var sigElement = document.getElementById("sig");
          if (sigElement == null)
              alert("sigElement not found");
          var sig = $(sigElement);
          var fetchData = sig.signature('toJSON');
          adf.mf.api.invokeMethod("mobile.MyClass", "FetchCallback", fetchData, onInvokeSuccess, onFail);
      };  

      function onInvokeSuccess(param) {
      };

      function onFail() {
          alert("It failed");
      };
  })();

Once you've created that Javascript file, add it via the adfmf-feature.xml includes that you used to add the 3rd party Javascript/CSS files from step 1.  Now you just add some regular AMX buttons to your page and hook them up to Java handlers.  In those Java handlers you'll use the following code to call to Javascript:

  AdfmfContainerUtilities.invokeContainerJavaScriptFunction( AdfmfJavaUtilities.getActiveContextId(), "doClear", new Object[] { });


Step 4:  Process the Fetch request in Java

This is the last step.  You simply need to handle the callback into Java when the doFetch Javascript is called.  In the Javascript code we added above, notice the following line that does the invoke to Java:

  adf.mf.api.invokeMethod("mobile.MyClass", "FetchCallback", fetchData, onInvokeSuccess, onFail);

This invokes the "FetchCallback" method in the class "mobile.MyClass" and sends it "fetchData" as the parameter.  Now you have the JSON converted data that was drawn into the signature capture on the Java side and can do whatever other processing you wish to it.  This could be simply saving it as is for future display or converting it to an image file or anything else you wish.

Note:  This signature capture example is NOT meant to meet regulatory and legal compliance for signatures!  If your software requires that you meet certain regulatory requirements for storing actual signatures then you need to consider other 3rd party integrations.  This is meant as a simple way to capture signatures or other simple drawings from a mobile device.


About

This blog is is dedicated to tips and tricks for developing, integrating, securing, and managing mobile applications using Oracle Mobile Platform. It is created and maintained by the Mobile Suite/Oracle ADF Mobile product development team.

Archive of past entries

Even More Mobile Development Blogs

Oracle A-Team Site - Mobile Related Entries

Code samples from the Community

Fusion Middleware Blogs

Search

Archives
« July 2013 »
SunMonTueWedThuFriSat
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
18
19
20
21
22
23
24
25
26
28
29
30
31
   
       
Today