Region and Country Bias: Creators can limit or prevent address selection for specific countries and regions.
It is the customer/creator's responsibility to obtain an API key for the Google Places or Canada Post services. API Keys are owned by the customer and should not be exposed to end-users.
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Field Text
Settings
Description
Label Text
The Label Text field conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.
Use user-friendly labels to make your module accessible. It's best practice to use brief and descriptive labels (one or two words). Use title case for short entries and sentence case for long entries.
Placeholder Text
A short prompt telling end-users the expected value of an input field. For example: Enter your Social Security Number. Placeholder Text displays inside the input field until the end-user begins an entry.
Contextual Help
Settings
Description
Tooltip
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line.
Default State Options
Settings
Description
Disable User Input
When set to ON, end-users can’t interact with or edit the Express View's input field or element. When end-users hover over the field, their cursor changes to alert them to the status change.
By default, the Disable User Input toggle is set to (OFF).
Read Only View
When set to ON, the component is display-only. If another component pushes content to the field, the end-user sees that content. Otherwise, end-users see the word None.
If the service type is set to Canada Post, Read Only View hides or suppresses the Country Option drop-down. This action occurs even if the Show Country Option setting is (ON). The Country Option drop-down does not contain submission data to display.
By default, the Use Read-Only View/Read Only View toggle is set to (OFF).
Hide Field
Hides the component from displaying in Express View.By default, this setting is (OFF).
Formatting
Settings
Description
Address Display Options
These settings enable end-users to see or enter their address information. If your end-user uses the search field and selects a suggested address, this field auto-fills from the address data returned by the address service API. Any end-user edits made to this field are only saved in this field's submission data and do not affect data returned by the address service API.
By default, end-users can edit checked fields. Enable Disable User Input to require users to use the search field to populate the Address Display fields. To prevent users from using the Search field, enable Hide Search in Advanced Settings.
By default, the following options are set to (OFF).
Show Street
Set to (ON) to display the address field in Express View. Street Address includes building number and street address values.
Show Street 2
Set to (ON) to display the secondary street address field in Express View. Secondary street address information might include building floor and office space values.
Show City
Set to (ON) to display the City field in Express View.
Show State
Set to (ON) to display the State field in Express View. State information might include individual U.S. state locations, territories, or sub-regions of a country.
Show Zip
Set to (ON) to display the Zip code field in Express View.
Show Country
Set to (ON) to display the Country field in Express View.
No Matching Results Text
Enter a custom message to display when an address service API has no matching search results based on the end-user's search.
Loading Results Text
The value in this field displays to the end-user when the Address Search component retrieves results from an address service.
Hide Search
Set to (ON) to hide the address search function. The Address Search component will not communicate with the Address Service API and perform an address lookup. Instead, the address fields you select display in Express View. Your end-user can then manually type in their address details.
By default, this setting is (OFF).
Data Panel
Data Storage
Settings
Description
Store Data in Database
The Store Data in Database setting affects how data persists through your application. When set to (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:
Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.
Triggering a module save event using a Button component with an Action Type of Save.
Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.
By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.
Set the toggle to (OFF) when you don’t want to store the values from this field in the database.
When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.
Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.
Data Source
Settings
Description
Place Service
Select an address API service to search the end-user's input.
Changing the Service Type removes all service-specific settings that do not apply to the new service. For example, if your Address Search component is set up for Google Places, changing it to Canada Post clears all Google Places-specific settings.
Google Places
The default selection. Displays the configuration settings for the Google Places API. To use this service, set up access in Services Administration.
For more information on configuring the Address Search component for Google Places, see the Google Places Address Service section of this article.
Canada Post
Select Canada Post to enable the configuration settings for the Canada Post API. To use this service, set up access in Services Administration.
For more information on configuring the Address Search component for Canada Post, see the Canada Post Address Service section of this article.
Google Places Address Service
By default, the Address Search component displays the Google Places service.
Settings
Description
Select API
Displays the list of Google Places services implemented in Services Administration. By default, the first available Address Service is selected. If no services are available, a warning displays in the component's configuration window.
In Express View, if no address service is selected, the console returns the status code error: 404 (Not Found). The console log also warns you to select a valid service.
Address Services must have the same name in Services Administration when promoting Address Search configurations between environments.
Enable to influence or restrict the values the Google Places API returns.
To restrict suggested results based on country, use the following format: country:[2-letter ISO 3166 country code]. For example, entering country:US|country:CA would restrict results to the United States and Canada. To see a complete list of ISO 3166 country codes, visit the following link: en.wikipedia.org/wiki/List_of_ISO_3166_country_codes. You can also influence suggested results based on state, city, or other values.
Region Bias Location
Enter the coordinates of a region. The coordinates tell the Google Places API what regional results to suggest first. For example, entering 37.76999, -122.44696 tells the API to suggest addresses near San Francisco, CA, before suggesting any others.
Region Bias Radius (meters)
Enter the maximum radius Google Places API can search based on the Region Bias Location.
Store Address in Short Format
Set to (ON) to abbreviate response data to a shorter format. For example, New York becomes NY, and United States becomes US.
This setting only affects the address element fields (street, street2, city, state, zip, and country).
Address Search includes the following Google Places API response data: geometry, types, and place_id. This data is available to view in the Express View console or with the Record Collections Viewer. Additional record data is also available in the address_components array.
Canada Post Address Service
The Canada Post API service is similar to Google Places, but its primary focus is on locating addresses in Canadian provinces.
Settings
Description
Select API
Displays the list of Canada Post services implemented in Services Administration. By default, the first available Address Service is selected. If no services are available, a warning appears in the component's configuration window.
Select the default country where you want the Canada Post API to return addresses. The default selection is Canada.
Show Country Option
Enables the country selection field for end-users. A drop-down menu with a list of countries supported by the Canada Post API displays in Express View. This drop-down menu defaults to the Default Country setting value.
Actions Panel
Triggers
Settings
Description
Trigger
Enter a Property ID of a component to trigger. When an end-user performs an action on this component, the trigger fires. For example, assign a Decisions component to trigger a Button component's visibility when an end-user selects an address using the Search field.
The trigger setting fires in the following cases:
The end-user un-focuses on any address field (Street, Street 2, City, State, Zip, or Country).
The end-user selects an address using the address search field.
The end-user clears the address field using the (x)Clear button.
On Keypress
When an end-user performs a keystroke in this component, the triggered component fires. For example, assign a Decisions component to trigger a Button component's visibility when an end-user presses the Enter key on their keyboard.
The On Keypress setting fires in the following cases:
The end-user performs a keystroke inside address fields (Street, Street 2, City, State, Zip, or Country).
The end-user selects an address using the address search field.
The end-user clears the address field using the (x)Clear button.
Validation Panel
User Input
Settings
Description
Required
When set to (ON), the end-user must enter a value in the component's visible fields. When set to (OFF), the input is optional.
By default, Required is set to (OFF).
Required Error Message
A custom error message displays below each visible and required address field. The error message displays when the end-user tries to save or submit the module without completing the required field.
Required Error Messages display for each visible and required address field. Error Messages also display underneath the component.
Updated CSS styling applies to all components that reference this custom class name.
Adding an Address Search Component
In this example, configure an Address Search component using the Google Places API to collect your end-user's address data. Let's assume the end-user lives in the United States. That way, you don't need to include the Country field. Also, add Placeholder text so your end-user knows to use the search field.
These instructions assume that you have an open module saved with a title.
1.
In the Module Builder, drag and drop an Address Search component onto your canvas.
In the Placeholder Text field, enter Search for your address.
5.
Set the Show Street, Show Street 2, Show City, and Show State to (ON).
6.
Navigate to the component's Data settings.
7.
From the Select API drop-down, select Test Google Places API or a Google Places API configured for the environment.
Test Google Places API is a preconfigured address service for the Training environment. To learn how to implement address service into the Address Search component, visit our Enabling Address Search Using Address Services article.
In Express View, if no address service is selected, the console returns the status code error: 404 (Not Found). The console log also warns you to select a valid service.
Google Places Response Data
Google Places also returns data that includes: geometry, place_id, and location types. The Google Places API returns the following response when searching for the Unqork address:
Short Format Data
Enable the Short Format Data (Google Places) setting to store record data in an abbreviated format. This setting only affects the address element fields (street, street2, city, state, zip, and country). The Google Places API returns the following response when searching for the Unqork address:
address_components Data
For detailed location data, refer to the address_components array. The address_components array is useful when viewing international locations that don't follow the strict US-centric format:
City, State
Zip Code, Country
The address_component location data includes the long_name key, short_name key, and types array for each address field.
Canada Post Response Data
The Canada Post API returns the following response when searching for the address 85 5th Ave Frnt 1, New York, NY:
Region and Country Bias: Creators can limit or prevent address selection for specific countries and regions.
It is the customer/creator's responsibility to obtain an API key for the Google Places or Canada Post services. API Keys are owned by the customer and should not be exposed to end-users.
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Field Text
Settings
Description
Label Text
The Label Text field conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.
Use user-friendly labels to make your module accessible. It's best practice to use brief and descriptive labels (one or two words). Use title case for short entries and sentence case for long entries.
Placeholder Text
A short prompt telling end-users the expected value of an input field. For example: Enter your Social Security Number. Placeholder Text displays inside the input field until the end-user begins an entry.
Default State Options
Settings
Description
Hide Field
Hides the component from displaying in Express View.By default, this setting is (OFF).
Disable User Input
When set to ON, end-users can’t interact with or edit the Express View's input field or element. When end-users hover over the field, their cursor changes to alert them to the status change.
By default, the Disable User Input toggle is set to (OFF).
Read Only View
When set to ON, the component is display-only. If another component pushes content to the field, the end-user sees that content. Otherwise, end-users see the word None.
If the service type is set to Canada Post, Read Only View hides or suppresses the Country Option drop-down. This action occurs even if the Show Country Option setting is (ON). The Country Option drop-down does not contain submission data to display.
By default, the Use Read-Only View/Read Only View toggle is set to (OFF).
Contextual Help
Settings
Description
Tooltip
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line.
Formatting
Settings
Description
Address Display Options
These settings enable end-users to see or enter their address information. If your end-user uses the search field and selects a suggested address, this field auto-fills from the address data returned by the address service API. Any end-user edits made to this field are only saved in this field's submission data and do not affect data returned by the address service API.
By default, end-users can edit checked fields. Enable Disable User Input to require users to use the search field to populate the Address Display fields. To prevent users from using the Search field, enable Hide Search in Advanced Settings.
By default, the following options are set to (OFF)
Show Street
Set to (ON) to display the address field in Express View. Street Address includes building number and street address values.
Show Street 2
Set to (ON) to display the secondary street address field in Express View. Secondary street address information might include building floor and office space values.
Show City
Set to (ON) to display the City field in Express View.
Show State
Set to (ON) to display the State field in Express View. State information might include individual U.S. state locations, territories, or sub-regions of a country.
Show Zip
Set to (ON) to display the Zip code field in Express View.
Show Country
Set to (ON) to display the Country field in Express View.
No Matching Results Text
Enter a custom message to display when an address service API has no matching search results based on the end-user's search.
Loading Results Text
The value in this field displays to the end-user when the Address Search component retreives results from an address service.
Hide Search
Set to (ON) to hide the address search function. The Address Search component will not communicate with the Address Service API and perform an address lookup. Instead, the address fields you select display in Express View. Your end-user can then manually type in their address details.
By default, this setting is (OFF).
Data Panel
Data Source
Settings
Description
Place Service
Select an address API service to search the end-user's input.
Changing the Service Type removes all service-specific settings that do not apply to the new service. For example, if your Address Search component is set up for Google Places, changing it to Canada Post clears all Google Places-specific settings.
Google Places
The default selection. Displays the configuration settings for the Google Places API. To use this service, set up access in Services Administration.
For more information on configuring the Address Search component for Google Places, see the Google Places Address Service section of this article.
Canada Post
Select Canada Post to enable the configuration settings for the Canada Post API. To use this service, set up access in Services Administration.
For more information on configuring the Address Search component for Canada Post, see the Canada Post Address Service section of this article.
Google Places Address Service
By default, the Address Search component displays the Google Places service.
Settings
Description
Select API
Displays the list of Google Places services implemented in Services Administration. By default, the first available Address Service is selected. If no services are available, a warning displays in the component's configuration window.
In Express View, if no address service is selected, the console returns the status code error: 404 (Not Found). The console log also warns you to select a valid service.
Address Services must have the same name in Services Administration when promoting Address Search configurations between environments.
Enable to influence or restrict the values the Google Places API returns.
To restrict suggested results based on country, use the following format: country:[2-letter ISO 3166 country code]. For example, entering country:US|country:CA would restrict results to the United States and Canada. To see a complete list of ISO 3166 country codes, visit the following link: en.wikipedia.org/wiki/List_of_ISO_3166_country_codes. You can also influence suggested results based on state, city, or other values.
Region Bias Location
Enter the coordinates of a region. The coordinates tell the Google Places API what regional results to suggest first. For example, entering 37.76999, -122.44696 tells the API to suggest addresses near San Francisco, CA, before suggesting any others.
Region Bias Radius (meters)
Enter the maximum radius Google Places API can search based on the Region Bias Location.
Store Address in Short Format
Set to (ON) to abbreviate response data to a shorter format. For example, New York becomes NY, and United States becomes US.
This setting only affects the address element fields (street, street2, city, state, zip, and country).
Address Search includes the following Google Places API response data: geometry, types, and place_id. This data is available to view in the Express View console or with the Record Collections Viewer. Additional record data is also available in the address_components array.
Canada Post Address Service
The Canada Post API service is similar to Google Places, but its primary focus is on locating addresses in Canadian provinces.
Settings
Description
Select API
Displays the list of Canada Post services implemented in Services Administration. By default, the first available Address Service is selected. If no services are available, a warning appears in the component's configuration window.
Select the default country where you want the Canada Post API to return addresses. The default selection is Canada.
Show Country Option
Enables the country selection field for end-users. A drop-down menu with a list of countries supported by the Canada Post API displays in Express View. This drop-down menu defaults to the Default Country setting value.
Data Storage
Settings
Description
Store Data in Database
The Store Data in Database setting affects how data persists through your application. When set to (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:
Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.
Triggering a module save event using a Button component with an Action Type of Save.
Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.
By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.
Set the toggle to (OFF) when you don’t want to store the values from this field in the database.
When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.
Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.
Actions Panel
Triggers
Settings
Description
Trigger
Enter a Property ID of a component to trigger. When an end-user performs an action on this component, the trigger fires. For example, assign a Decisions component to trigger a Button component's visibility when an end-user selects an address using the Search field.
The trigger setting fires in the following cases:
The end-user un-focuses on any address field (Street, Street 2, City, State, Zip, or Country).
The end-user selects an address using the address search field.
The end-user clears the address field using the (x)Clear button.
On Keypress
When an end-user performs a keystroke in this component, the triggered component fires. For example, assign a Decisions component to trigger a Button component's visibility when an end-user presses the Enter key on their keyboard.
The On Keypress setting fires in the following cases:
The end-user performs a keystroke inside address fields (Street, Street 2, City, State, Zip, or Country).
The end-user selects an address using the address search field.
The end-user clears the address field using the (x)Clear button.
Validation Panel
Settings
Description
Required
When set to (ON), the end-user must enter a value in the component's visible fields. When set to (OFF), the input is optional.
By default, Required is set to (OFF).
Required Error Message
A custom error message displays below each visible and required address field. The error message displays when the end-user tries to save or submit the module without completing the required field.
Required Error Messages display for each visible and required address field. Error Messages also display underneath the component.
Updated CSS styling applies to all components that reference this custom class name.
Adding an Address Search Component
In this example, configure an Address Search component using the Google Places API to collect your end-user's address data. Let's assume the end-user lives in the United States. That way, you don't need to include the Country field. Also, add Placeholder text so your end-user knows to use the search field.
These instructions assume that you have an open module saved with a title.
1.
Drag and drop an Address Search component onto your canvas.
In the Placeholder Text field, enter Search for your address.
5.
Set the Show Street, Show Street 2, Show City, and Show State to (ON).
6.
From the component's configuration menu, select Data.
7.
From the Select API drop-down, select Test Google Places API.
Test Google Places API is a preconfigured address service for the Training environment. To learn how to implement address service into the Address Search component, visit our Enabling Address Search Using Address Services article.
8.
Click Save & Close.
9.
Save your module.
Now you're ready to test your Address Search component. Preview your module and search for an address. Your module should work as shown below:
Structure of an Address Search Component's Data
Address Search component data is stored as an object. In the address object, location data is stored in key/value pairs. Address Search returns the full, unaltered address from the Address Service in the formatted key. All other address response data is specific to the Google Places or Canada Post API. Address Service APIs return all location data regardless of the Address Display Field (Street, Street2, Zip, Country) selections.
In Express View, if no address service is selected, the console returns the status code error: 404 (Not Found). The console log also warns you to select a valid service.
Google Places Response Data
Google Places also returns data that includes: geometry, place_id, and location types. The Google Places API returns the following response when searching for the Unqork address:
Short Format Data
Enable the Short Format Data (Google Places) setting to store record data in an abbreviated format. This setting only affects the address element fields (street, street2, city, state, zip, and country). The Google Places API returns the following response when searching for the Unqork address:
address_components Data
For detailed location data, refer to the address_components array. The address_components array is useful when viewing international locations that don't follow the strict US-centric format:
City, State
Zip Code, Country
The address_component location data includes the long_name key, short_name key, and types array for each address field.
Canada Post Response Data
The Canada Post API returns the following response when searching for the address 85 5th Ave Frnt 1, New York, NY:
In Express View, if no address service is selected, the console returns the status code error: 404 (Not Found). The console log also warns you to select a valid service.
Google Places Response Data
Google Places also returns data that includes: geometry, place_id, and location types. The Google Places API returns the following response when searching for the Unqork address:
Short Format Data
Enable the Short Format Data (Google Places) setting to store record data in an abbreviated format. This setting only affects the address element fields (street, street2, city, state, zip, and country). The Google Places API returns the following response when searching for the Unqork address:
address_component Data
For detailed location data, refer to the address_components array. The address_components array is useful when viewing international locations that don't follow the strict US-centric format:
City, State
Zip Code, Country
The address_component location data includes the long_name key, short_name key, and types array for each address field.
Canada Post Response Data
The Canada Post API returns the following response when searching for the address 85 5th Ave Frnt 1, New York, NY:
(
Google Places
Address Search component onto your canvas.
Data
