DE ♦ EN

Die Funktion get_form

Zweck der Funktion:
Mit dieser Funktion können Sie für Ihre Website länderspezifische HTML-Eingabeformulare generieren, ohne die Länder unterschiedlich behandeln zu müssen. Außerdem ist die Formatierung (z. B. mit CSS) unter Ihrer Kontrolle. Da Sie - unterstützt durch diese Funktion - die HTML-Formulare auf Ihrem eigenen Server generieren, gibt es auch keine Probleme mit Web-Formularen, die von unterschiedlichen Servern kommen und miteinander interagieren müssen.

Das Problem mit unterschiedlichen Ländern:
Länderspezifische Formulare unterscheiden sich nicht nur in der Anzahl und Art der Felder (z. B.: nur Kontonummer für Belgien, Kontonummer + BLZ für Deutschland etc.), sondern auch in der Anzahl der Interaktionsschritte (z. B. Schweiz: Benutzer wählt erst die Bank, dann die Filiale/BC-Nummer aus einer Liste, dann gibt er die Kontonummer ein - im Gegensatz zu Deutschland: der Benutzer gibt Kontonummer und Bankleitzahl ein, und damit sind schon alle benötigten Parameter vorhanden).

Wie die Interaktion - für alle Länder gleich - funktioniert:
Sie rufen die Funktion mehrmals auf. Jedesmal sagt Ihnen die Funktion, ob ein weiterer Aufruf nötig sein wird. Wenn ja, liefert sie außerdem eine Beschreibung des von Ihnen zu generierenden Web-Formulars. Wenn kein weiterer Aufruf nötig ist, liefert sie stattdessen eine Liste der Parameter, die Sie an die SOAP-Funktion 'calculate_iban' senden müssen, um eine IBAN zu berechnen.

Parameter und Rückgabewerte

Eingabe:
Neben Ihrer Benutzer-ID/Passwort gibt es einen komplexen Datentyp ('Map') namens 'params' als Parameter, der Paare von Schlüsseln und zugehörigen Werten enthält. Beim ersten Aufruf können Sie mit zwei solchen Paaren die von Ihnen gewünschte Sprache für das Formular sowie das Land festlegen:

  1. Formularsprache:

    • Schlüssel: 'language'
    • Wert: eine der folgenden Sprachen-Nummern.

      • Englisch = 0
      • Deutsch = 1
      • Niederländisch = 3
      • Polnisch = 4
      • Französisch = 5
      • Spanisch = 6
      • Italienisch = 7
      • Türkish = 8
      • Kroatisch = 9
      • Serbisch = 10
      • Slowakisch = 11
      • Tschechisch = 12
      • Estnisch = 13

  2. Land:

    • Schlüssel: 'country'
    • Wert: der ISO-Ländercode mit zwei Buchstaben, wie in der IBAN.

Bei Folgeaufrufen übergeben Sie in dieser Datenstruktur die Felder und zugehörigen Werte, die Sie bei dem vorigen Aufruf von der Funktion 'get_form' zurückerhalten haben und die ggf. durch Ihre Website-Benutzer editiert wurden.

Rückgabe:
Die Funktion liefert neben der Information, ob ein weiterer Aufruf von get_form notwendig sein wird, eine Liste von Feldern mit diversen Attributen zurück. Wenn kein weiterer Aufruf nötig sein wird, wird die Feldliste für die Liste der Parameter für die SOAP-Funktion calculate_iban verwendet. Sie können ihr also entnehmen, wie Sie die Funktion calculate_iban aufrufen müssen, um Ihre gewünschte IBAN zu berechnen. Sollte dagegen ein weiterer Aufruf nötig sein, gibt Ihnen diese Liste die nötigen Informationen zum Aufbau eines Web-Formulars, das Sie dann Ihrem Benutzer präsentieren können. Jedes Feld hat dabei folgende Attribute:

  • id: der Schlüssel im Schlüssel-Wert-Paar
  • type: der Feld-Typ, d.h.

    • Textfeld ('text')
    • Button ('submit')
    • Drop-Down-Box ('select')
    • statischer Text ('static')
    • verstecktes Feld ('hidden')

  • value: der derzeitige, möglicherweise zu editierende, Inhalt des Feldes
  • für Drop-Down-Boxen: eine Liste aller möglichen Werte ('optionids')
  • für Drop-Down-Boxen: eine Liste aller möglichen Beschriftungen der Werte ('options')
  • label: ein Text, der als Erklärung neben/über (für Textfelder/Drop-Down-Boxen) oder auf (für Knöpfe/statischen Text) dem Element angezeigt werden sollte.
  • length: die zu erwartende maximale Länge des einzugebenden Textes; damit können Sie entscheiden, wieviel horizontalen Platz Sie diesem Feld einräumen sollten.
  • newline: die Information, ob Sie nach diesem Feld eine neue Zeile beginnen sollten oder ob das nächste Feld rechts neben diesem Feld plazieren werden sollte.

Einfacher Beispiel-Dialog: DE

Als einfaches Beispiel hier der komplette Dialog für Deutschland.

Zunächst wird ein Request an die Funktion get_form geschickt, in der nach dem Formular für Deutschland und auf deutsch gefragt wird:

1. Aufruf

class item
{
  public $key;
  public $value;

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


$client = new SoapClient('https://ssl.ibanrechner.de/soap2/?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", "1"));
$result = $client->get_form($params, 'einbenutzername', 'einpasswort');

print_r($result);

Dieses Stückchen Code liefert die folgende Antwort:

1. Antwort

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] => 1
                    [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] => Bankleitzahl
                    [optionids] => Array (  )
                    [options] => Array()
                    [length] => 8
                    [newline] => yes
                )
            [4] => stdClass Object
                (
                    [id] => _ob_kontonr_cb_
                    [type] => text
                    [value] =>
                    [label] => Kontonummer
                    [optionids] => Array (  )
                    [options] => Array()
                    [length] => 10
                    [newline] => yes
                )
            [5] => stdClass Object
                (
                    [id] => _ob_a_cb_
                    [type] => submit
                    [value] =>
                    [label] => IBAN berechnen
                    [optionids] => Array (  )
                    [options] => Array()
                    [length] => 0
                    [newline] => yes
                )
        )
)

Diese Antwort ist wie folgt zu verstehen: "done" hat den Wert "no", wir sind also noch nicht fertig. Das heißt, die folgenden Felder sollten in einem HTML-Formular dargestellt werden und dann, wenn der Benutzer Gelegenheit hatte, ihre Werte zu editieren, in einem zweiten Aufruf noch einmal an die Funktion get_form übergeben werden.

Die Felder im einzelnen sind:

  • ein verstecktes Feld namens "country" mit dem Wert "DE" - das soll einfach durchgereicht werden.
  • ein verstecktes Feld "language" mit dem Wert "1" für "deutsch"
  • ein verstecktes Feld "step" mit Wert "1"
  • ein editierbares Textfeld, mit "Bankleitzahl" bezeichnet, Länge maximal 8 Stellen, Feld-ID ist "_ob_blz_cb_". Außerdem ist "newline" gleich "yes", also sollte das nächste Feld in einer neuen Zeile präsentiert werden.
  • ein editierbares Feld für die Kontonummer mit Eigenschaften, die denen des BLZ-Feldes ähneln.
  • schließlich ein Knopf, der mit "IBAN berechnen" beschriftet ist.

Im folgenden sehen Sie PHP-Code, der für jedes Land und jede derartig beschriebene Feldkombination ein HTML-Formular erzeugt:


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, 'einbenutzername', 'einpasswort');

if ($result->done == "no") {
  print show_form($result->fields);
 } else {
  print "Das war der letzte Schritt. Jetzt k&ouml;nnen wir die Funktion calculate_iban mit folgenden Parametern aufrufen:<br/><br/>";
  foreach ($result->fields as $f) {
    print $f->id." = ".$f->value."<br/>";
  }
 }

2. Aufruf

Nachdem der Benutzer Gelegenheit hatte, das HTML-Formular zu bearbeiten, kann man mit dem folgenden Code, der für beliebige Länder gleich funktioniert, den neuen Aufruf der Funktion get_form durchführen. Hier werfen wir einfach alle Parameter aus dem Array $_REQUEST in die Datenstruktur "params", obwohl nicht alle nötig wären (solche, die die Funktion get_form nicht erwartet, ignoriert sie einfach):

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

2. Antwort

Wenn der Benutzer beispielsweise die Kontonummer 0648479930 und die Bankleitzahl 50010517 eingegeben hat, sind wir jetzt schon fertig, "done" hat also jetzt den Wert "yes". Das unten gezeigte Programm gibt dann aus:
Das war der letzte Schritt. Jetzt können wir die Funktion calculate_iban mit folgenden Parametern aufrufen:
country = DE
bankcode = 50010517
account = 0648479930
bic =
legacy_mode =

Die Datenstruktur, die diese Informationen enthält, sieht wie folgt aus:

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
                )
        )
)

Universeller Client

Das folgende kleine PHP-Programm geht für das Land und die Formularsprache, die im ersten Aufruf von get_form gewählt wird, durch alle Schritte und zeigt die jeweiligen Formulare an:

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

<?php

$userid = "meine Benutzer-ID";
$password = "mein Passwort";

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&auml;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 "Das war der letzte Schritt. Jetzt k&ouml;nnen wir die Funktion calculate_iban mit folgenden Parametern aufrufen:<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>