Integration Introduction
- Integrating our DOTS Global Address Complete solution can now be completed with anyone familiar with HTML and JavaScript. We make the integration process so easy that almost anyone will be able to get it up and running in little time. Our solution is designed for web based technologies that can consume our JavaScript helper file. We have simplified the integration process down to three easy steps: Include our JavaScript and CSS in your application, field mapping and customization by setting options. This integration guide will take you through a typical HTML web form integration.
Step 1 – Include Files
- The first thing to be done on the page you want to integrate Global Address Complete is to make a reference to the JavaScript and CSS files. The JavaScript will handle all the things that should happen under the hood of the field that the Global Address Complete is connected to for the type ahead solution. And, the CSS file will help with the formatting of the field. The CSS file is just as critical as the JavaScript file for integrating this solution.
- Starting with the CSS file ACStyle.css, add it to the page using the link tag in the head section.
HTML – Include CSS
<head>
<link rel="stylesheet" type="text/css" href="https://trial.serviceobjects.com/Resources/AC/CSS/ACStyle.css" />
.
.
.
</head>
- For the JavaScript file ACScriptV1.02.js, add it using the script tag at the top inside the body. This is important because earlier versions do not have options for supporting place predict, only address suggestion.
HTML – Include JavaScript
<body>
<script type="text/javascript" src="https://trial.serviceobjects.com/Resources/AC/JS/ACScriptV1.04.js"></script>
.
.
.
Step 2 – Map Fields
- Step 2 involves mapping a field on the page to the corresponding field in the JavaScript file that we added in the previous step just as we did in the address type ahead solution. Again, we will be adding the mapping inside the script tag on the same HTML page that we have been working on but you are free to create a separate JavaScript file and add the mapping code there. If you do add it to a new JavaScript page, be sure to reference it in the HTML page the same way we did in step 1 when we referenced the ACScriptV1.02.js page.
- The key difference here is that typical use of the place predict solution usually employs only one field for typing and the same field for populating the selected suggestion. In the address type ahead solution, you will often see more fields to get populated on the selection of an address. That does not mean you can’t take advantage of all the data that comes back from a selection by any means. You can add more fields and populate them with various elements coming back from the selection.
- Here is an example of an HTML section with the input fields on a typical web form. Make note of the ID value on the input tag because that will be used in the mapping part of the script tag.
Input Fields to Map
<div id="sPlace" class="AddressInputBlock">
<div id="lPlace2" class="AddressLabels">Place</div>
<input id="iPlace" type="text" class="AddressInputs" />
</div>
- Now that we have made note of iPlace on the input tag we are ready to map. In the script tag, add the code below. Here we are mapping the iPlace input field to the searching mechanism in the referenced JavaScript. The HTL tag with iPlace is where the place suggestions will be displayed. iPlace will be mapped to Address1, this is not a typo, Address1 is used for both the standard address suggestion solution and the Place Predict solution.
Field Mapping
<script>
var fields = [
{ element: "iPlace", field: "Address1", mode: so.fieldMode.SEARCH | so.fieldMode.POPULATE }
];
</script>
Step 3 – Set Options
- In the final step is where you can customize how Global Address Complete works for your solution. Here we will continue where we left off in the last step and add the next lines of code after the ending bracket of the field assignment but still inside the script tag. To complete the setup, you will need to have a Custom Key and you will need to know if you are using trial key or live key. We will pass the Custom Key to the options variable and if we are using a trial key no additional options need to be set. If you were setting up for a live implementation adding isTrial: false would be needed in the options variable. Referencing the next screenshot, the options would look like this in that situation: var options = { key: CustomKey, isTrial: false, DoPlace: true, SearchType: “Locality” };. The other options to focus on here are DoPlace and SearchType. Setting DoPlace to true will set the component to do place predict suggestions instead of addresses. The SearchType will indicate what kind of place predict is desired. For example, maybe you just want your users to see cities. Currently there is only the one option to search on, Locality, and it will suggest city and town type of places but in the future there will be others like Point of Interest (POI), Thoroughfare and Admin Area for example. Having a typo on the SearchType option will lead to no suggestion populating in the dropdown, however, omitting the option all together will default in results associated to the Locality level SearchType.
Setting Options
var fields = [
{ element: "iPlace", field: "Address1", mode: so.fieldMode.SEARCH | so.fieldMode.POPULATE }
];
var CustomKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
var options = { key: CustomKey, DoPlace: true, SearchType: "Locality" };
var DOTSGlobalAddressComplete = new so.Address(fields, options);
- Once you have the options set your form will now be activated to suggest addresses as you type.