Guide to iCody’s Callback Scripting

With Version 1.7, the icody:-scripting-callback-API was introduced to iCody. This interfaces allows any app or even website to use iCody as an universal barcode reader as long as the icody:-protocol is supported by them.

The icody:-protocol bases on a URL call following this scheme:

icody://<function type>?callback=<callback function call>

Explanations:

<function type>
scan
<callback function call>

The function call must be build as a valid URL and shall be URL encoded like a valid GET parameter. It will be called after a successful scan of iCody using the openURL method call.

Within the function call several placeholders are allowed and will be replaced by iCody before processing the callback:

###barcode### the value of the scanned barcode

###type### the barcode type as a string value

###typeID### the unique barcode type ID (might be zero, depending on the input device)

###location### the scan location if activated

###date### scan date and time

Example: Filemaker GO

To use iCody with Filemaker GO you have to build two scripts in Filemaker where the first script processes the call of iCody and is typically connected to a button and the second one processes the callback call of iCody and is connected with a field which is filled by this script.

One can go two ways to use iCody callback in Filemaker GO: The easy one, where only one value is obtained through callback, and the complicated one, where the values for Type, location and scan date are passed as well. Here below, the easy way is shown.

1. Script

script1a

script1b

The URL value in this example shows the following value (with and without URL encoding):

icody://scan?callback=fmp7script%3A//%24/" & Get ( FileName ) & "%3Fscript%3Dscan%26param%3D%23%23%23barcode%23%23%23
icody://scan?callback=fmp7script://$/" & Get ( FileName ) & "?script=scan&param=###barcode###

This call uses the fmp7script:-URI which is also supported by Filemaker GO. The function parameter “script=scan” names the callback script which is described below. To this script, the follwing part “&param=###barcode###” passes the value .

Important 1: With Filemaker 12, the URL-scheme has changed: When using these versions, please replace the fmp7script:// part with fmp://.

Important 2: The part “& Get( FileName ) &” adds the file name of the fm7 file into the callback. Without that, the callback won’t work. Of course one can add also a clearly written value here. But this part is a Filemaker function call and does not belong to the callback URL itself. Nevertheless, if the file name contains whitespaces or special chars, it has to be URL encoded as well. In the resulting URL, everything what comes behind callback= has to be URL encoded!

Important 3: The script name shall not contain any whitespaces, even not if escaped.

Now you can link the script to any button you want:

script1c

2. Script:

The second script takes the scanned barcode value out of the callback and writes it into the specified field:

script2

Using the function “Get ( ScriptParameter )” the parameter passed back with the callback call is retrieved and this value is set into the field with the label “Inventar::Laufende_Nummer”.

Example: Website

The following code example shows the implementation of a callback using a php script. A Live-Demo can be seen here.


<?php
$barcode = $_REQUEST['barcode'];
$type = $_REQUEST['type'];
$date = $_REQUEST['date'];
$location = $_REQUEST['location'];
echo '<' . '?xml version="1.0" encoding="UTF-8" ?' . '>';
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<base href="mobile/">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, minimum-scale=1.0, maximum-scale=1.6">
<meta name="apple-mobile-web-app-capable" content="YES">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>iCody Scripting</title>
</head>
<body>
	<h1>iCody Scripting Sample</h1>
	<table width="100%%" border="0" cellspacing="0" cellpadding="3">
		<caption>
		    <h3 align="left">Values</h3>
		  </caption>
		  <tr>
		    <th scope="row"><div align="left">Barcode:</div></th>
		    <td><input id="textField" type="text" name="" value="<?php echo $barcode;?>"></td>
		  </tr>
		  <tr>
		    <th scope="row"><div align="left">Type:</div></th>
		    <td><input id="textField2" type="text" name="" value="<?php echo $type;?>"></td>
		  </tr>
		  <tr>
		    <th scope="row"><div align="left">Date:</div></th>
		    <td><input id="textField3" type="text" name="" value="<?php echo $date;?>"></td>
		  </tr>
		  <tr>
		    <th scope="row"><div align="left">Location:</div></th>
		    <td><input id="textField4" type="text" name="" value="<?php echo $location;?>"></td>
		  </tr>
		  <tr>
		    <th scope="row"><p>&nbsp;</p></th>
		    <td><input id="scan" type="button" name="" value="Scan Barcode" onclick="window.location='icody://scan?callback=http%3A//www.appthology.net/icodyscripting%3Fbarcode%3D%23%23%23barcode%23%23%23%26type%3D%23%23%23type%23%23%23%26date%3D%23%23%23date%23%23%23%26location%3D%23%23%23location%23%23%23';">´>L;</td>
		  </tr>
	</table>
</body>
</html>