Tutorial sobre el Modo Scripting

Para una mejor comprensión de este tutorial es preciso algún conocimiento de programación igual que otra documentación avanzada del SiteKiosk Object Model. Tenga en cuenta que el ejemplo presentado aquí está cubierto por el módulo SiteCafe, aunque sólo disponible en versiones antiguas de SiteKiosk.

Nota de traducción:
Aunque este tutorial, al igual que la documentación de SiteKiosk Object Model, sólo está disponible en inglés, le animamos a estudiarlo para aprender cómo configurar su propio dispositivo de pago basado en un servidor propio.

Step 1: General information and database structure
Step 2: Scripts on the server side and development of the necessary PHP scripts
Step 3: Creating the required user dialog boxes and overview of scripting device
Step 4: Creating the necessary JavaScripts (SiteKiosk Object Model)
Step 5: Possible implementations and expansions

1. Step 1: General information and database structure

1.1 Goal of this tutorial / requirements

The goal this tutorial tries to achieve is to enable you to set up your own server-account payment device in a few easy steps.
This tutorial relies on the free tools MySQL, phpMyAdmin, and a Web server that includes PHP support (PHP Version >= 4.1.0). For this example, we assume that the server has been configured and is up and running. What you will also need is SiteKiosk version 5.0.32 or higher (available for free download).

The tutorial requires that you have some basic knowledge of PHP and SQL as well as a sound knowledge of HTML and JavaScript. It would also be advantageous if you had experience experimenting with the SiteKiosk Object Model).

We will now turn to the structure of the device and the task it is supposed to fulfill.

1.2 Setting our goal (what to we want to achieve?)
We want to create a payment device that will prompt the user to enter her name and password in a dialog box.
The dialog box will then contact a server and transmit information on the current account balance as well as a few other specific information such as the user's full name and her own Start Page to SiteKiosk.
The dialog box establishes contact with the server using the new HTTP Post Object of the SiteKiosk Object Model.

1.3 Creating the database structure
Let us start with the database that will provide the information for the device.
We will try and keep the tables as simple as possible.
We will start by creating a new database using phpMyAdmin and give it the appropriate name of "NoCoinSys.".
Although you can, of course, choose any name you like, make sure you decide on one that will not confuse you when we deal with the examples. Otherwise, you may end up using information from the wrong database or table.

Table: ncs_user - user information

CREATE TABLE ncs_user (

pk int(11) NOT NULL auto_increment,

name varchar(80) default NULL,

last_name varchar(80) NOT NULL default '',

login_id varchar(30) NOT NULL default '',

password varchar(30) NOT NULL default '',

startpage varchar(255) default NULL,

PRIMARY KEY (pk),

UNIQUE KEY pk(pk)

);

The table "ncs_user" contains our user information. You can conveniently enter the SQL command into the SQL field in phpMyAdmin.
In order to initiate the login process we will demand the "login_id" as well as the field "password". Provided this user exists, we will then send her full name as well as the specified Start Page to SiteKiosk. You will learn more about this in the second part of the tutorial.

Table: ncs_account - user account

CREATE TABLE ncs_account (

pk int(11) NOT NULL default '0',

value float NOT NULL default '0',

PRIMARY KEY (pk),

UNIQUE KEY pk(pk)

);

The user account with its attribute "pk" refers to the attribute "pk" of the user information.
The attribute "value" provides the actual information on the user's current balance. Please note that SiteKiosk will always transmit the balance information with four decimal place accuracy, which ensures that the transactions will be more precise.

So far, we have developed an understanding for the general structure of the database and outlined the structure of the database we want to use. The user will later on be able to save her Start Page on the server in order to look at it on our terminals. In addition, the user will also possess an account where her current balance will be stored.

2. Step 2: Scripts on the server side and development of the necessary PHP scripts

2.1 Goal definition for step 2
This part of the tutorial deals with the creation of a PHP script which will examine the user information sent from the terminal in order to send back extended user information or to report an error.
Since JavaScript provides an easy way for you to analyze the issued page, the values that are sent back will be separated by the pipe symbol "|".

In order to make things easier for the JavaScript, we will start off by responding with a wrong value (negative numbers) caused by an unsuccessful attempt to log on. If the login attempt was successful, you will find a positive number instead, e.g.

A sample return value from the server

1|Authentication successful|50|John|Doe|http://www.sitekiosk.es/

The value is made up of the following elements:
Error Code|Message|Credit|First Name|Last Name|Start Page
This information will help the JavaScript to initialize the account later on. Should the logon attempt fail, we will leave out everything after "Message" and set the "Error Code" to a negative value.

2.2 The PHP script
Let us now finally turn to the PHP script.
The first thing we have to do is to initialize the database by means of the commands

mySQL initialization

$link = mysql_connect("SQLServerURL", "SQLUser", "SQLPassword");

mysql_select_db("NoCoinSys");

We must not forget to adjust "SQLServerURL", "SQLUser", and "SQLPassword" to the settings used by the server.
Having done so, we can now turn to the actual problem, which is to check the user information and the fields sent by the script.
We will tackle this problem by making an SQL request which will retrieve user name and password directly from the table "ncs_user."

Checking the transmitted account

$sql = "SELECT * FROM ncs_user WHERE

login_id='" . $_POST["login_name"] . "' AND

password='" . $_POST["login_password"] . "'";

$res = mysql_query($sql);

We will post "$_POST["login_name"]" and "$_POST["login_password"]" to this page using our JavaScript.
Thus, all that remains for us to do in order to tell whether this user exists and if the entered password is valid is to check the number of records provided through "$res":

Transmitting user information (possibly an error)

if (@mysql_num_rows($res) == 1)

{

$userobj = mysql_fetch_object($res);

$sql = "SELECT * FROM ncs_account

WHERE pk='" . $userobj->pk . "'";

$res = mysql_query($sql);

if (@mysql_num_rows($res) == 1)

{

$accountobj = mysql_fetch_object($res);

print "1|Authentication successful|"

. $accountobj->value . "|"

. $userobj->name . "|"

. $userobj->last_name . "|"

. $userobj->startpage;

}

else

print "-3|Error: No account found";

}

else

print "-2|Error: Authentication unsuccessful";

We admit that this seems like a lot to swallow all at once, but you will see why this information is essential.
As mentioned before, line 1 checks on the number of records that have to be exactly equal to one in order for us to find a valid user.
The "@" sign preceding the command is only there for suppressing potential error messages from PHP that might confuse our JavaScript.

Next, we will go to line 3 and include the information about this one user in the variable "$userobj." In the following line, we will create the SQL query which will retrieve our account from the correct table. Consequently, the two attributes called "pk" have to be identical for the same user in both tables.
The examination of the number of records remains the same for this account as well. If we have been successful so far, we can now say that such a user exists and that she has an account balance which we can transmit to the script.

print "1|Authentication successful|"

. $accountobj->value . "|"

. $userobj->name . "|"

. $userobj->last_name . "|"

. $userobj->startpage;

This format is in accordance with the one we specified beforehand. We will subsequently be able to evaluate this line in the script.
This format makes it very easy for us to deal with errors: we will receive one line containing the error code as well as the error number (negative). For example:

print "-3|Error: No account found";

2.3 Implementing the "SetMoney" Function
Let us take a closer look at the script again. What is it capable of doing so far?
We can transmit the login data to the page and, in return, we receive the user's full name and current balance as well as the Start Page. Unfortunately, payment module devices do not function in such a simplistic way. What is more, we cannot yet set a new account balance, either. For instance, when dealing with devices on the server side, you may come across the problem that the connection will be disrupted before logout and that, therefore, the current balance on the server will remain unaltered.

In order to prevent this from happening we have implemented devices into SiteKiosk that you can use to withdraw amounts every single minute. These devices access an account within SiteKiosk and make withdrawals from an (external) account once every minute. In doing so, they always set the account balance stored on the server to the new value. This will always keep your loss as low as possible in the event of a complete system failure.
As a consequence, we would need the script to provide a new function that allows us to alter the account balance on the server.
What we need to do is slightly modify the script because every time we call it now, it will prompt us to provide login information.

We will have to insert a new field into the form that the JavaScript posted in order to be able to distinguish between the regular login and the SetMoney function. This field has to contain information about the action that had just been executed by the script.
Let us call it "action." Before we can send back the user information, we have to make sure to insert another "if" condition which is supposed to check what action has just been executed:

[...]

$sql = "SELECT * FROM ncs_account

WHERE pk='" . $userobj->pk . "'";

$res = mysql_query($sql);

if (@mysql_num_rows($res) == 1)

{

if ($_POST["action"] == "login")

{

$accountobj = mysql_fetch_object($res);

print "1|Authentication successful|"

. $accountobj->value . "|"

. $userobj->name . "|"

. $userobj->last_name . "|"

. $userobj->startpage;

}

[...]

Now inquire if the user simply wants to set her new account balance:

[...]

else if ($_POST["action"] == "setmoney")

{

$sql = "UPDATE $accountable SET value='" .

ereg_replace(",", ".", $_POST["MoneyBack"]).

"' WHERE pk='" . $userobj->pk . "'";

$res = mysql_query($sql);

if ($res)

print "1|Account successfully set|" .

ereg_replace(",", ".", $_POST["MoneyBack"]);

else

print "-1|Error: Internal Error";

}

[...]

The following line needs some more explanation:

ereg_replace(",", ".", $_POST["MoneyBack"])

While most scripting and programming languages save numerical values using a ".", the functions the payment module employs always go back one Currency value containing a comma (at least on German operating systems).
Since it replaces this comma by a dot, this line ensures that the value can be saved in the database by means of the SQL inquiry.

2.4 Conclusion of step 2
Now we have set up the server in such a way that we can manage our user account system with the help of the JavaScript part, which we are about to develop in the following.
The server is now capable of transmitting to the script the information about the user, the current account balance as well as the Start Page. In addition, you can use the variable "$_POST["action"]" to specify that you want to set the current balance to the new value which can be found in the variable "$_POST["MoneyBack"]."

View the complete userpost.php script here.

3. Step 3: Creating the required user dialog boxes and overview of scripting device

We will need a small HTML dialog box within the SiteKiosk browser which will prompt the user to enter her user name and password.
After that, we will take a closer look at the ScriptDevice and learn more about the logic behind the SiteKiosk payment devices.

3.1 Input dialog box for the user
It will be best if we start with the HTML dialog box.
This box must contain two text INPUT fields, a button the user can press to submit the form, and another field in which the user can find her full name after the successful completion of the form:

HTML Login Dialog

<tr>

<td>

<table>

<td style='color: white;'>Name:

<td style='color: white;'>Password:

<td>

<tr>

</table>

</td>

</tr>

</table>

And that concludes this part. The user can now enter her name and password and submit this information.

3.2 A quick overview of the SiteKiosk ScriptDevice
SiteKiosk offers an extensive library of scripts (SiteKiosk Object Model) which makes it possible to develop a payment device (for instance, for the purposes of this tutorial).
Let us take an in-depth look into these scripting and testing devices as well as their functions and attributes:

ScriptDevice

DeviceName [String, read only]

Testmode [Boolean, read only]

AccountEnabled [Boolean]

Balance [Currency, read only]

Volatile [Boolean]

RetransferEnabled [Boolean]

Credit(Currency Value, Boolean bDirect)

Debit(Currency Value, Boolean bDirect)

The first two attributes are irrelevant for our example. Let us, therefore, move on to the other ones.
"AccountEnabled" allows the payment module's internal account to be used with this payment device. If enabled, the payment module will also perform transactions on the account used by the device.
"Balance" contains the amount currently available for the device. The amount is read only and can be altered by the functions "Credit" and "Debit."
"Volatile" describes the device's behavior. If this value is true, the account balance of the device can change spontaneously just like our example suggests if, for example, the connection to the server has been severed.
"RetransferEnabled". If this value is set to true, the device will manage the retransfer of amounts all by itself. For more information, read on about Events.
As the name already suggests, the function "Credit" credits amounts to an account, whereas the function "Debit" debits amounts from an account. The parameter "bDirect" indicates whether the amount is supposed to end up on the payment module account or on the account of the device.

The following events will be received by the ScriptDevice:

ScriptDevice

OnSiteCashDebit(Currency AmountPayed, Currency NewBalance)

Boolean OnCheckRetransfer(Currency Amount)

Boolean OnRetransfer(Currency Amount)

The event "OnSiteCashDebit" will receive every debiting process coming in from the payment module. This is why it is ideal for our purposes because the payment module makes a deduction every single minute and, thereby, allows our device to inform the server about the new account balance.
Prior to retransferring the amounts, "OnCheckRetransfer" will inquire from all devices if they agree to the transaction. Since there is nothing that speaks against this in our case, the value is set to "return true;".
"OnRetransfer" will then perform the actual retransfer.

Since we also have to be able to make inquiries to the server, why should we not have the HTTP post object do the job for us.
This object provides the great advantage of relying entirely on a script and, thereby, saves you the pain of compiling cumbersome forms. What is more, the fact that it passes the emitted page on to you in the form of a variable makes this object extremely powerful.

SiteKiosk

Network()

This command retrieves the network object we want to use to create a post object:

SiteKiosk.Network

CreateHTTPPost()

This concludes the creation of our HTTP post object, and we can now access the provided functions and events:

HTTP Post

AddParameter(String Name, String Value)

Submit(String strURL)

OnPostComplete(HResult Success, String ReturnValue)

"AddParameter" adds a new parameter to the form we want to send. It is called "Name" and carries the value "Value."
Use "Submit" and the desired URL to send the form on its way.
The event "OnPostComplete" will fire as soon as the server has responded. If the parameter "Success" is higher than or equal to zero, the request has been successful. If the values are lower, an error has occurred (server timeout or similar error). The string "ReturnValue" contains the returned page that we have to analyze.

3.3 Practical procedure
The information above will suffice for the creation of our script device.
All we have to think about now is what we actually want our device to do on the client-script side and base the definition of our functions on these considerations.

As we want the user to submit the form with her information, we already know what the function "FormSubmit" has to be like. This function will read out the INPUT fields and provide the necessary data for our server script.
The server will then send its response including the user information "OnPostComplete."
We evaluate the user information with the function "ParseReturnValues.".
We said earlier that we wanted to make a deduction from the server's account once every minute while the user is surfing. We achieve this goal by having our script attach itself to the event "OnSiteCashDebit" because it will then be able to inform the server about the changed account balance.
The user will be given the chance to log out and, thereby, recredit the minute she just started to the account stored on the server (event "OnRetransfer").

3.4 Conclusion of 3
We have come to an understanding of the required components of the SiteKiosk Object Model and have gained some insight into the behavior of the payment devices. We now know that it is possible to control the logout behavior of the devices and that the devices have an account of their own at their disposal.
We have also got to know the HTTP post object and are aware of the fact that it can be a powerful tool for controlling SiteKiosk when it is used in connection with Web servers.
Our device is now completely defined so that we can move on to creating the script itself.

4. Step 4: Creating the necessary JavaScripts (SiteKiosk Object Model)

We have now gathered all the information we need to proceed to the last part of this tutorial: the JScript controlling our device.
So, let us get started.

4.1 General functions

Initialization

var PostObj = new Object();

var UserObj = new Object();

var ServerPage = "http://YOUR.SERVER/page.php";

var openposts = 0;

function InitDialog()

{

window.external.InitScriptInterface();

ScriptDevice.AccountEnabled = true;

ScriptDevice.RetransferEnabled = true;

ScriptDevice.OnCheckRetransfer = OnCheckRetransfer;

ScriptDevice.OnRetransfer = OnRetransfer;

ScriptDevice.OnSiteCashDebit = OnSiteCashDebit;

PostObj = SiteKiosk.Network.CreateHTTPPost();

PostObj.OnPostComplete = OnPostComplete;

}

</script>

[...]

For the purposes of our example, we require two global objects and two global variables:
"PostObj" will be assigned to a new HTTP post object in InitDialog.
After logging in, we will save our user information to "UserObj."
"ServerPage" contains the URL for the PHP script we know from part 2, and using "openposts"› we will count the attempts to debit amounts from our server once every minute. After the third unsuccessful attempt to log on, we will log out the user because otherwise we cannot be sure that we are not dealing with an unauthorized attempt to access the server.

FormSubmit
Try and remember something we mentioned earlier: the logout dialog box features a button that, when clicked on, calls the function "FormSubmit":

FormSubmit()

function FormSubmit()

{

PostObj.OnPostComplete = OnPostComplete;

PostObj.AddParameter("login", "SiteKiosk");

PostObj.AddParameter("action", "login");

PostObj.AddParameter("login_name", edtLoginName.value);

PostObj.AddParameter("login_password", edtLoginPassword.value);

UserObj.name = edtLoginName.value;

UserObj.password = edtLoginPassword.value;

PostObj.Submit(ServerPage);

The first few lines assign the event once again because we will use the same object both for logging out and the minute-by-minute withdrawal. These processes differ from one another in that we cannot treat them in the same way (if we go over the server-sided script in our minds, we will realize that there are two different ways for us to contact the server: Login and SetMoney).
The other elements of the function set the parameters we will evaluate on the server and send the form to the URL of the server.

OnPostComplete

OnPostComplete()

function OnPostComplete(success, returnvalue)

{

ParseReturnValue(returnvalue, false);

PostObj = SiteKiosk.Network.CreateHTTPPost();

PostObj.OnPostComplete = OnPostComplete;

}

This function is only there for calling the evaluation function and for reinitializing the PostObj in order to prevent potential overlaps.

ParseReturnValue
This function will evaluate the page we received from the server.
It is invoked by two functions: OnPostComplete and OnREPostComplete. The latter function is primarily used by the server for error emission.
Let us take a closer look at the first part of the function.

ParseReturnValue(value, is_retransfer)

function ParseReturnValue(value, is_retransfer)

{

var RetArr = value.split("|");

if (is_retransfer == false)

{

if (RetArr[2] != null)

{

UserObj.RetVal = RetArr[2];

UserObj.RetName = RetArr[3];

UserObj.RetLastName = RetArr[4];

UserObj.RetStartPage = RetArr[5];

}

else

UserObj.RetVal = 0;

}

else

UserObj.RetVal = 0;

[...]

According to the definition of our return value, we can split up the value into an array using "value.split("|")." This array will either contain the user information or the error returned by the server.
In case the user only wants to log on rather than log out, we will have to provide our "UserObj" with the user information given in the array.
Next, we will fill the values that were transmitted in any event even if an error has occurred:

[...]

UserObj.ReturnValue = value;

UserObj.RetCode = parseInt(RetArr[0]);

UserObj.RetMsg = RetArr[1];

if (UserObj.RetCode < 0)

alert(UserObj.RetMsg);

else if (UserObj.RetVal > 0 && is_retransfer == false)

{

LogInfo.innerHTML = "Successfully logged in as:
"\

+ UserObj.RetName + " " + UserObj.RetLastName + "";

trName.style.display = "none";

trPW.style.display = "none";

trOK.style.display = "none";

CreditDebit(UserObj.RetVal, true);

if (UserObj.RetStartPage != "")

SiteKiosk.WindowList.MainWindow.SiteKioskWindow.\

SiteKioskWebBrowser.Navigate(UserObj.RetStartPage, true);

}

Now, we will check if there was an error (row 5). If this is the case, the server will show an info box with the error message.
However, if everything went according to plan, we will switch from logon view to the message that the user managed to log on successfully, and we will also display her name.
The transmitted amount will be credited (row 16), and the user will be taken to the Start Page she specified:

SiteKiosk.WindowList.MainWindow.SiteKioskWindow.\

SiteKioskWebBrowser.Navigate(UserObj.RetStartPage, true);

Although this construction may seem a little unusual, it provides the only possibility to access the SiteKiosk browser from a non-skin window.

CreditDebit
A slightly altered function of the regular testing mode dialog box that ships with SiteKiosk represents the "core" of our payment device:

CreditDebit(fValue, bCredit)

function CreditDebit(fValue, bCredit)

{

fValue = parseFloat(fValue);

if (bCredit)

ScriptDevice.Credit(fValue, false);

else

ScriptDevice.Debit(fValue, false);

}

The third row contains a conversion of the string we received from the server into a float. This conversion is necessary because, otherwise, we could not credit the internal JScript number into the SiteKiosk payment module.
The amount will subsequently either be credited to or debited from the account of the ScriptDevice.

OnSiteCashDebit
As mentioned earlier, we will have our device refresh the account balance on the server once every minute using this function.
Should this process fail three times in a row, we will log out the user (reset the account balance to zero) and notify her that something went wrong:

OnSiteCashDebit(payedamount, newbalance)

function OnSiteCashDebit(payedamount, newbalance)

{

if (openposts < 3)

{

if (UserObj.name != null)

{

PostObj.OnPostComplete = OnSCDPostComplete;

PostObj.AddParameter("login", "SiteKiosk");

PostObj.AddParameter("action", "setmoney");

PostObj.AddParameter("MoneyBack", newbalance);

PostObj.AddParameter("login_name", UserObj.name);

PostObj.AddParameter("login_password", UserObj.password);

PostObj.Submit(ServerPage);

++openposts;

}

else

return false;

}

else

{

OnREPostComplete(true, "");

ScriptDevice.Debit(ScriptDevice.Balance, false);

alert("The server timed out, please call\

support personnel!");

openposts = 0;

}

In the first part, the PostObj is assigned a new function which is supposed to be invoked at the end of the search process: OnSCDPostComplete, which is actually only there for decrementing the counter of the open posts per return value.
In addition, the parameter "action" will deliver a message from the PostObj, which is set to "setmoney", telling the server that we want our balance to be credited to the server account.
Once submitted, this information will increase the counter by one to make it possible for us to check precisely during the next transaction process how many posts have not come back yet.
Afterwards, in the second part, we will know that something went wrong on the server and will, therefore, log out the user by invoking the function OnREPostComplete. We will, furthermore, also deduct the current credit balance and notify the user about the error.

OnSCDPostComplete

OnSCDPostComplete(success, returnvalue)

function OnSCDPostComplete(success, returnvalue)

{

openposts--;

}

4.2 Logout procedure
Now, we have already reached the final part of our tutorial: teaching our payment device how to log out all by itself and how to transmit the exact remaining credit amount to the server.

OnCheckRetransfer
As we have already learned in theory, our payment device will have to respond to two events when logging out: OnCheckRetransfer and OnRetransfer.
OnCheckRetransfer is fairly simple to understand. If the device consents to the logout procedure, the return value will be "true." Otherwise, it will be "false." This allows us to keep better control of the logout procedure and cancel it if necessary.
Our device always consents to the logout procedure:

OnCheckRetransfer(amount)

function OnCheckRetransfer(amount)

{

return true;

}

OnRetransfer
The actual logout procedure will follow after the successful verification of the data. We want to deal with the response from the server in a separate function: OnREPostComplete.
With the help of the server function "setmoney" we will set the account balance to the remaining amount:

OnRetransfer(amount)

function OnRetransfer(amount)

{

PostObj.OnPostComplete = OnREPostComplete;

PostObj.AddParameter("login", "SiteKiosk");

PostObj.AddParameter("action", "setmoney");

PostObj.AddParameter("MoneyBack", ScriptDevice.Balance + amount);

PostObj.AddParameter("login_name", UserObj.name);

PostObj.AddParameter("login_password", UserObj.password);

PostObj.Submit(ServerPage);

ScriptDevice.Debit(ScriptDevice.Balance, false);

return true;

}

Row 11 will then submit the form and the user will be logged out because we will set the account of our device to zero.
This function has to return "true" because otherwise SiteKiosk will not realize that logging out succeeded.

OnREPostComplete
With this function we react to the successful logout (server responded). We will now reinitialize our objects and give the user an opportunity to log on again:

OnREPostComplete(success, value)

function OnREPostComplete(success, returnvalue)

{

ParseReturnValue(returnvalue, true);

PostObj = SiteKiosk.Network.CreateHTTPPost();

PostObj.OnPostComplete = OnPostComplete;

edtLoginName.value = "";

edtLoginPassword.value = "";

LogInfo.innerHTML = "";

UserObj = new Object();

trName.style.display = "block";

trPW.style.display = "block";

trOK.style.display = "block";

}

In row 3, we will call up ParseReturnValue again to have the server issue any errors that may have occurred.
We will then reset the variables and bring back the logon table to its initial state.

4.3 Conclusion of step 4
We have now developed a fully functional payment device.
This device will react to all of the given events, it will make minute-by-minute withdrawals of the amount the payment module specified and leave it up to the user to decide when she wants to log out.
The user will be notified about any server failures and logged out for the time being.

Click here for a complete example of a ServerPayed HTML page.

There are, of course, many different ways for you to implement this dialog box into SiteKiosk.

5. Step 5: Possible implementations and extensions

5.1 Many roads lead to Rome
For reasons of simplicity, we used the scripting & testing device dialog box (defined in the skin definition) to test the implementation of the device.
The advantage this dialog box has over other approaches is that it will be displayed the entire time and, therefore, save you the concern of saving the user information.
However, there are many other ways to achieve the same goal in SiteKiosk.
For instance, you could call a dialog box from within the skin which serves the same purpose. All you would have to do in this case is pass on our "UserObj" to the dialog box by means of the dialog function "AttachDispatch" (cf. documentation of the SiteKiosk Object Model).
You may also want to consider the possibility of opening a dialog box from within a payment dialog box or having the dialog box itself serve as an input mask. As you see, the possibility are almost endless.

5.2 Possible extensions
The complete HTTP post object looks like this:

HTTP Post Object

String Referer;

AddParameter(String Name, String Value);

SetAuthInfo(String Name, String Password);

Submit(String bstrURL);

Abort();

OnPostComplete(HResult Success, String ReturnValue);

This architecture offers you quite a few possibilities. For instance, you could address your server solely by means of HTTPS and a password request (in order to do so, you would have to call "ScriptDevice.SetAuthInfo(USER, PASSWORD)" within the script).
This would provide a tremendous security advantage because otherwise someone might quite easily jump into the connection to alter her own account balance in her favor (which, by the way, is highly unlikely because, first of all, the user would have to seek her way out of SiteKiosk and read the files stored on the terminal, but ... you never know).

In order to introduce yet another security feature, you might also want to check in the server-sided script whether the account balance that is to be set is higher than the previous balance because - if this were the case - the transaction should not take place.

Let us take a look at the complete ScriptDevice:

ScriptDevice

DeviceName [String, read only]

Testmode [Boolean, read only]

AccountEnabled [Boolean]

Balance [Currency, read only]

Volatile [Boolean]

RetransferEnabled [Boolean]

Credit(Currency Value, Boolean bDirect)

Debit(Currency Value, Boolean bDirect)

OnSiteCashDebit(Currency AmountPayed, Currency NewBalance);

Boolean OnCheckRetransfer(Currency Amount);

Boolean OnRetransfer(Currency Amount);

Boolean OnLogoutButtonPressed();

OnPropertyChange();

OnBalanceChange(Currency NewBalance);

As you can see, a few events that have not been mentioned before have been added to the original setup.
"OnLogoutButtonPressed" will be invoked right after the user has pressed the logout button, i.e. even before the retransfer.
"OnPropertyChange" - One of the following attributes will have changed: AccountEnabled, RetransferEnabled or Volatile.
Whenever "OnBalanceChange" fires, the internal account balance will have changed.

We hope that this tutorial managed to provide you with a good overview of the new scripting functions we have implemented in SiteKiosk.