Example only
This section walks you through an example integration, demonstrating how easy it is to add Pro API to your Web pages. This example shows how you can integrate Pro API functionality into a company intranet site.
The example shows the entire process; from installation of Pro API and configuring the server, through to modifying the Web pages with sample code.
This example uses a fictitious company called Welly Good that sells Wellington boots. It shows how to integrate Pro API into their internal sales order system.
These Web pages enable a trained operator to take and process orders over the telephone (or from returned order forms).
The operator takes the customer's delivery details and manually enters them into the address fields of the intranet site.
This has the disadvantage that manually entering the address can result in delivery address errors. It also takes some time to enter all the customer's details in this way.
Integrating Pro API onto a Web page involves the following steps:
These instructions relate to installing and configuring the Pro API program. For this example, we have chosen to install the Pro API program onto the Web server, but you may choose to keep them separate for improved scalability and reliability.
When installing Pro API, we should ensure that:
For this example we will use C#.NET for the integration. In your own situation, you should install the integration language that matches the code that you are using for development.
We should install the dataset(s) appropriate to the countries that our fictitious Web site supports. For the purposes of this demonstration, we can install any dataset and additional dataset for which we have a valid license.
Now, we should configure the product and the integration code to suit our needs. For this, we should configure the layout that we want to use for the address data; configure the integration code to use that layout; and configure the list of countries that are displayed when Pro API starts.
We should configure a layout for every active country that can be used. Each layout should match the address fields on the Web page that we want to fill in (in terms of the number of lines and address content).
When the layout has been created, we must configure the integration code to use the new layout. By default, the integration code uses the " ( Standard Layout )", so we should change this to our new layout, by following these instructions:
Go to the installed integration code.
Open the settings file containing the layout specification, appropriate to the coding language, in a text editor, such as Notepad.
The following files are available:
web.xml JSP
constants.inc PHP
web.config C#.NET
Find the line which specifies the layout values. By default, this line will refer to the "( Standard Layout )".
For example, for C#.NET, this line is:
<add key="com.qas.proweb.layout" value"( Standard Layout )"/>
Change "( Standard Layout )" to the name of the layout we want to use.
When we use Intranet Rapid Addressing, the interface offers a drop-down list of available countries for us to search. By default, the list consists of 20 countries. We should edit this list of countries to suit the needs of our integration. To change this to our new list, we should follow these instructions:
Go to the installed integration code.
Open the 'country list' file, appropriate to the coding language, in a text-editor, such as Notepad.
This file has the following name, depending on the coding language being used:
countries.ok.inc PHP and JSP
countries.net.inc C#.NET
We should remove countries that are not installed.
Alternatively, if we only want to use one country, we can remove the drop-down <select> control from each of the Rapid Addressing pages, and replace it with a hidden field set to the country of our choice.
In C#.NET, the following code specifies that only the GBR dataset is used:
<input type="hidden" name="<% constants::DATA_ID %>" value="GBR" />
We should test Pro API to check that everything is working as we would expect. To do this, we should:
When we are happy that everything is working as expected, we are ready to proceed to the next section.
In this section, the following updates need to be made:
These three tasks have already been implemented in the sample page, RapidIndex.htm, so we could use the code in this page and modify it to suit our fictional Web site.
On the page requiring address capture, we want to add an HTML button near to the address fields that the operator will be using.
To add this button to the intranet page, we should follow these instructions:
In our intranet page, we should scroll down to the address fields that we want to fill, and just above or beside it, add an HTML button, which calls 'popupPro' when it is clicked. For example:
<button onclick="popupPro();">Find address</button>
Save the intranet page and view the changes.
The intranet page will now feature a Find address button near to the address fields.
The next step is to attach a function to the button. To do this, we should follow these instructions:
In RapidIndex.htm, navigate to the <script> section that lists the popupPro function.
// Pop-up the Pro API window for rapid address searching
function popupPro()
{
// specify the initial country in DataId & function to call in Callback
var ProPopup = window.open(
"RapidSearch.aspx?DataID=&Callback=handleProClose",
"ProPopup",
"scrollbars=no,resizable=yes,width=725,height=560");
}
Copy this section of code and then open the intranet page into which we want to place this function.
Paste the section of code into a <script type="text/javascript"> block in the intranet page.
Now, we need to edit the page path to point to the sample code.
Insert the relative path of the integration code from the Web site. For example, if the site is in a directory called "boots", and the integration code is installed into its default directory of "proweb", then:
var ProPopup = window.open(
"../proweb/RapidSearch.aspx?DataID=&Callback=handleProClose", "ProPopup",
"scrollbars=no,resizable=yes,width=725,height=560");
line function
If we want to specify a data mapping for the initial country search, we need to enter the three-letter data mapping identifier for the country after the DataId= part of the code.
Save the intranet page.
Now the Find address button will call popupPro when it is clicked.
The next step is to control how the returned address is handled. When a formatted address is returned, this function is called and should paste the address into the fields on the intranet page. To do this, we should follow these instructions:
Open RapidIndex.htm and navigate to the <script> section that lists the handleProClose function in the HTML.
// Handle the returned final address - populate the appropriate address fields
// String[] asAddress - array of address lines
function handleProClose(asAddress)
{
var aFields = document.getElementsByName("Address");
for (i = 0; i < aFields.length; i++)
{
aFields[i].value = (i < asAddress.length) ? asAddress[i]: "";
}
aFields[0].focus();
}
Copy this section of code and then open the intranet page into which we want to place this function.
Paste the section of code into the <script> block of the intranet page.
Modify the code so that the address lines are pasted into the correct fields. For example, if the address fields that we want to fill are all named "DeliveryAddress", then we should edit the document.getElementsByName statement appropriately.
var aFields = document.getElementsByName("DeliveryAddress");
If, instead, we have a number of fields named "Street" followed by fields named "Zip" and "Country", then our code could like this:
for (i = 0; i < aFields.length; i++)
{
aFields[i].value = (i < asAddress.length) ? asAddress[i] : "";
}
document.getElementById("Zip").value = (i < asAddress.length) ? asAddress[i++] : "";
document.getElementById("Country").value = (i < asAddress.length) ? asAddress[i++] : "";
Save and close the intranet page.
Now, with our Web page updated, we are ready to capture addresses and return them to our customer address fields.