The get_form Function

Purpose of the Function:
Use of this function allows you to generate country-specific html entry forms in one uniform way, not using ad hoc methods for each country. In addition, the formatting remains under your control (for example with css). The function helps avoid problems with offering web forms that originate from more than one server or with integrating such forms.

Complications with Varying Countries:
Country-specific forms differ in several different ways. For example, the number and types of fields can change -- e.g. Belgium forms require only account numbers; Germany forms require both account number and bank code (BLZ). Another important difference between countries is in the number of interaction steps needed before a result can be given. For example, for Switzerland forms a user needs three steps: first, choose a bank; second, choose the branch/BC-number from a list; third, enter the account number. In contrast, a Germany form requires the user to enter the account number and bank code in one step.

The 'get_form' Function Works the Same for all Countries:
The function 'get_form' is called more than once. Each time it is called, the function tells you if the function needs to be called again. If it needs to be called again, the function also delivers a description of the web form that you need to generate. If the function does not need to be called again, the function instead returns a list of parameters that need to be sent to the SOAP function 'calculate_iban' so that an iban can be calculated.

Input Parameters and Output Fields

Input Parameters:
In addition to your user id/password, the input parameters include a complex data type ('Map') named 'params'. This map contains pairs of keys and their relative values. When the function is called for the first time, you can choose

the language for the form
- key: 'language'
- value: the language-number.
  - English = 0
  - German = 1
  - Dutch = 3
  - Polish = 4
  - French = 5
  - Spanish = 6
  - Italian = 7
  - Turkish = 8
  - Croatian = 9
  - Serbian = 10
  - Slovak = 11
  - Czech = 12
  - Estonian = 13
a country
- key: 'country'
- value: the two-letter ISO country code

For subsequent calls of the function, key and value pairs should be as in the description of the form returned by the previous call of the function 'get_form' and with values as edited by your website user.

Output Fields:
In addition to the information whether the 'get_form' function needs to be called yet again, the function returns a list of fields with various attributes. If the function does not need to be called again, the returned list of fields will be the list of parameters needed for the SOAP function 'calculate_iban'. On the other hand, should another call of the function be necessary, the function will instead return a list of information needed to build a web form that should then be presented to your users. In this case, each field has the following attributes:

id: the key in the key/value pairs
type: the field type, i.e.
- text field ('text')
- button ('submit')
- drop-down-box ('select')
- static text ('static')
- hidden field ('hidden')
value: the current, possibly to be edited, content of the field
for drop-down-boxes: a list of all possible values ('optionids')
for drop-down-boxes: a list of all possible labels of the values ('options')
label: a text describing an element, which should be placed over (for text fields), next to (for drop-down-boxes) or in (for buttons or static text) the element it describes.
length: the expected maximal length of the text to be entered; This information can help determine how much horizontal space should be devoted to this field.
newline: The information if a new row should begin after this field, or if the next field should be placed directly to the right of this one.

Dialogue Example: DE

As an example, below is the a complete dialogue for Germany.

First, a request is sent to the 'get_form' function requesting a form for Germany, and dialogue in English:

1st Call of the Function

class item
{
public $key;
public $value;

public function __construct($key, $value) {
$this->key = $key;
$this->value = $value;
}
}

$client = new SoapClient('https://ssl.ibanrechner.de/soap/?wsdl',array
(
"trace" => 1,
"classmap" => array("Map"=> "Map", "item" => "item")
));

$params = array();
array_push($params, new item("country", "DE"));
array_push($params, new item("language", "2"));
$result = $client->get_form($params, 'ausername', 'apassword');

print_r($result);

This snippet of code delivers the following response:

1st Response

stdClass Object
(
[done] => no
[fields] => Array
(
[0] => stdClass Object
(
[id] => country
[type] => hidden
[value] => DE
[label] =>
[optionids] => Array ( )
[options] => Array ( )
[length] => 0
[newline] => no
)
[1] => stdClass Object
(
[id] => language
[type] => hidden
[value] => 0
[label] =>
[optionids] => Array ( )
[options] => Array ()
[length] => 0
[newline] => no
)
[2] => stdClass Object
(
[id] => step
[type] => hidden
[value] => 1
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
[3] => stdClass Object
(
[id] => _ob_blz_cb_
[type] => text
[value] =>
[label] => Bank Code
[optionids] => Array ( )
[options] => Array()
[length] => 8
[newline] => yes
)
[4] => stdClass Object
(
[id] => _ob_kontonr_cb_
[type] => text
[value] =>
[label] => Account Number
[optionids] => Array ( )
[options] => Array()
[length] => 10
[newline] => yes
)
[5] => stdClass Object
(
[id] => _ob_a_cb_
[type] => submit
[value] =>
[label] => Calculate IBAN
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => yes
)
)
)

This response should be understood in the following way: the parameter 'done' has the value 'no', so we are not yet done, and the function will have to be called again. This means that the following fields should be displayed in an HTML form. The user should then edit values using the form, and those edited values should be sent to the 'get_form' function when it is next called.

The fields are the following:

a hidden field named 'country', with the value 'DE' - this should be passed back to the function when it is called again.
a hidden field 'language', with the value '2'.
a hidden field 'step', with value '1'.
an editable text field labeled with 'Bank Code'. The 'length' is at most 8 characters, and the field id is '_ob_blz_cb_'. In addition, 'newline' has the value 'yes', so the next field should be presented in a new line.
an editable field for the account number, with properties like those of the 'Bank Code' field.
Finally, a button labeled 'Calculate IBAN'.

In the following, you can see the PHP code which gives an HTML form for each country and its respective field combination:

function show_form($fields) {
$res = '<form action="" method="post">';

foreach ($fields as $f) {
# HIDDEN:
if ($f->type == "hidden")
$res .= '<input type="hidden" name="'.$f->id.'" value="'.$f->value.'">';

# SELECT (drop-down):
else if ($f->type == "select") {
$res .= $f->label.' <select name="'.$f->id.'" size="1">';
for ($i=0; $i<count($f->options); $i++)
$res .= '<option value="'.htmlspecialchars($f->optionids[$i]).'" '.($f->value == $f->optionids[$i]?'selected="selected"':"").'>'.$f->options[$i].'</option>';
$res .= "</select>";

# TEXT (input field):
} else if ($f->type == "text") {
$res .= $f->label.' <input type="text" name="'.$f->id.'" value="'.$f->value.'"'.($f->length > 0? ' size="'.$f->length.'"':"").'>';

# SUBMIT (button):
} else if ($f->type == "submit") {
$res .= '<input type="submit" name="'.$f->id.'" value="'.$f->label.'">';

# STATIC (additional text):
} else if ($f->type == "static") {
$res .= $f->label.' '.$f->value;
}

if ($f->newline == "yes")
$res .= "<br/>";
}
return "$res</form>";
}

... $result = $client->get_form($params, 'ausername', 'apassword');

if ($result->done == "no") {
print show_form($result->fields);
} else {
print "This was the last step. Now you can call the function calculate_iban using the following parameters:<br/><br/>";
foreach ($result->fields as $f) {
print $f->id." = ".$f->value."<br/>";
}
}

2nd Call of the Function

After the user has edited the HTML form, once can use the following code, which functions in the same way for each country, to call the 'get_form' function. Here we add all the parameters found in the array '$_REQUEST' to the 'params' data structure, regardless of whether or not they are all necessary -- the 'get_form' function discards any parameters it does not need:

$params = array();
foreach (array_keys($_REQUEST) as $key) {
$item = new item($key, $_REQUEST[$key]);
array_push($params, $item);
}
...
$result = $client->get_form($params, 'ausername', 'apassword');
...

2nd Response

If the user has, for example, entered the account number 0648479930 and the bank code 50010517, then we are finished. In this case, 'done' now has the value 'yes'. The program displayed below then returns:
This was the last step. Now you can call the function calculate_iban using the following parameters:
country = DE
bankcode = 50010517
account = 0648479930
bic =
legacy_mode =

The data structure that contains this information is the following:

stdClass Object
(
[done] => yes
[fields] => Array
(
[0] => stdClass Object
(
[id] => country
[type] => hidden
[value] => DE
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
[1] => stdClass Object
(
[id] => bankcode
[type] => hidden
[value] => 50010517
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
[2] => stdClass Object
(
[id] => account
[type] => hidden
[value] => 064847930
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
[3] => stdClass Object
(
[id] => bic
[type] => hidden
[value] =>
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
[4] => stdClass Object
(
[id] => legacy_mode
[type] => hidden
[value] =>
[label] =>
[optionids] => Array ( )
[options] => Array()
[length] => 0
[newline] => no
)
)
)

The Universal Client

The following small PHP program goes through all the steps for the country and the form language that were chosen in the first call of the 'get_form' function and shows the corresponding forms.

<html>
<head>
<title>Simple universal form: IBANs for many countries</title>
</head>
<body>

<?php

$userid = "my user ID";
$password = "my password";

class item
{
public $key;
public $value;

public function __construct($key, $value)
{
$this->key = $key;
$this->value = $value;
}

}

function show_form($fields) {
$res = '<form action="" method="post">';

foreach ($fields as $f) {
# HIDDEN:
if ($f->type == "hidden")
$res .= '<input type="hidden" name="'.$f->id.'" value="'.$f->value.'">';

# SELECT (drop-down):
else if ($f->type == "select") {
$res .= $f->label.' <select name="'.$f->id.'" size="1">';
for ($i=0; $i<count($f->options); $i++)
$res .= '<option value="'.htmlspecialchars($f->optionids[$i]).'" '.($f->value == $f->optionids[$i]?'selected="selected"':"").'>'.$f->options[$i].'</option>';
$res .= "</select>";

# TEXT (input field):
} else if ($f->type == "text") {
$res .= $f->label.' <input type="text" name="'.$f->id.'" value="'.$f->value.'"'.($f->length > 0? ' size="'.$f->length.'"':"").'>';

# SUBMIT (button):
} else if ($f->type == "submit") {
$res .= '<input type="submit" name="'.$f->id.'" value="'.$f->label.'">';

# STATIC (additional text):
} else if ($f->type == "static") {
$res .= $f->label.' '.$f->value;
}

if ($f->newline == "yes")
$res .= "<br/>";
}
return "$res</form>";
}

$client = new SoapClient('https://ssl.ibanrechner.de/soap/?wsdl',array
(
"trace" => 1,
"classmap" => array("Map"=> "Map", "item" => "item")
));

if ($_REQUEST["step"] == 0) {
$result = $client->country_supported("", $userid, $password);
print '<form action="" method="post">
Land: <select name="country">';
foreach ($result->supported_countries as $c)
print '<option value="'.$c.'">'.$c.'</option>';
print '</select>
<input type="hidden" name="step" value="-1">
<input type="submit" value="Auswählen">
</form>';
} else {
if ($_REQUEST["step"] == -1) {
$params = array();
array_push($params, new item("country", $_REQUEST["country"]));
array_push($params, new item("language", "0"));
} else {
$params = array();
foreach (array_keys($_REQUEST) as $key) {
$item = new item($key, $_REQUEST[$key]);
array_push($params, $item);
}
}

$result = $client->get_form($params, $userid, $password);

if ($result->done == "no") {
print show_form($result->fields);
} else {
print "This was the last step. Now you can call the function calculate_iban using the following parameters:<br/><br/>";
foreach ($result->fields as $f) {
print $f->id." = ".$f->value."<br/>";
$par[$f->id] = $f->value;
}
$res2 = $client->calculate_iban($par["country"], $par["bankcode"], $par["account"], $userid, $password, $par["bic"], $par["legacy_mode"]);
print "<pre>"; print_r($res2); print "</pre>";
}

print "<pre>";
print_r($result);
print "</pre>";

# print "Request :\n".$client->__getLastRequest()."\n";
# print "Response:\n".$client->__getLastResponse()."\n";
}

?>
</body>
</html>

		Forgot password?	Contact us
Stay logged in		New customer? Register	Contact us