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.
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
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.
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:
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:
This snippet of code delivers the following response:
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:
In the following, you can see the PHP code which gives an HTML form for each country and its respective field combination:
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:
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
The data structure that contains this information is the following:
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.