Location Services Control
The Location Services control provides location and time information based on the Global Positioning System (GPS) of mobile devices. The control provides latitude, longitude, altitude, accuracy, altitude accuracy, time, and location age information. You can use the control to:
- Capture the current location
- Determine the time spent at a certain location
- Asynchronously retrieve details about a user's current location
Configuring the Control
- Create a view.
- Drag the control onto the canvas. You can find the control in the Information section of the Toolbox.
- Add and configure a Button control.
- Navigate to the rules and add a rule to start looking at location as shown below.
- Finish the rule and add the next rule, when the button is clicked.
- Configure the transfer action to transfer data from the control to the text boxes as shown.
- Save the rules and the view.
- Auto-generate a form for the view.
- Check in the view and form.
- Open the form on a mobile device.
- Click the Get Location button. Note the Latitude and Longitude text boxes are populated.
Properties
You can find the control in the Information section of the Toolbox. 
| Property | Description | Can be set in runtime using rules? |
|---|---|---|
| Detail | ||
| Name | A unique identifier for the selected control. This property is required and defaults to the name of the control. | No |
| Settings | ||
| Enabled | Enables or disables the control. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Timeout | The amount of time the application tries to pick up the location of the device, measured in milliseconds. | Yes, see Configure the Set a Control's Properties Action for more information. |
Rules, Events and Actions
The control interacts with other controls through rules. When you bind properties between different controls, you can use the data to populate properties or set values. Use the following examples for when to use the control with other controls through rules:
- Enable/Disable: The Enabled property allows you to enable or disable the control through rules
- Data Transfer: You can transfer data from items listed in the context browser to the control
- Set a control’s properties: You can configure the settable properties of the control with this action. You can also use the control's context browser properties to set another control's properties.
The following events and methods are available on the control:
Rule Events:
- When [control] is Error: You can execute a rule condition or action for example when the timeout has expired then show a message to the user
- When [control] is Initializing: While you can see this event in the Rule Designer, it has been deprecated. Instead use the When the View/Form Initialize event.
- When [control] is Location Changed: You can execute a rule condition or action when the location is changed. See Considerations when you use this event.
Control Methods:
- Execute a control's Get location method: Gets the location of the device at that exact time. The method is called asynchronously, so you should always use this method with the When [control] is Location Changed event
- Execute a control's Start Watching method: Executes continuously every time the device's location changes until the Stop Watching method executes
- Execute a control's Stop Watching method: Stops the Start Watching method from executing
The following
context browser properties are available to set another control's properties:
| Property | Description | Can be set or used in runtime to set other control's properties |
|---|---|---|
| Detail | ||
| Name | A unique identifier for the control. This property is required and defaults to the name of the control. | No |
| Settings | ||
| Enabled | Enables or disables the control. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Timeout | The amount of time the application tries to pick up the location of the device, measured in milliseconds. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Location | ||
| Latitude | The North / South coordinate. Use the latitude with the longitude to specify the precise location on the surface of the earth, measured in degrees. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Longitude | The East / West coordinate. Use the longitude with the latitude to specify the precise location on the surface of the earth, measured in degrees. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Altitude | The measurement of the vertical distance in meters from sea level. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Accuracy | The measure of the accuracy in relation to the returned latitudinal and longitudinal coordinates, measured in meters. This property, along with latitude and longitude, is available on any device with GPS. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Altitude Accuracy | The accuracy of distance in relation to the altitude position, measured in meters. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Time Stamp | Date and time information. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Location Age | The amount of time when last the location was measured. This value is measured in milliseconds. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Error | ||
| Error Message | Contents of the error message. | Yes, see Configure the Set a Control's Properties Action for more information. |
| Error Code | The error code linked to the error message. | Yes, see Configure the Set a Control's Properties Action for more information. |
Considerations
- The control is also available when designing forms
- Only Apple devices return data for Altitude and Altitude Accuracy
- Latitude and Longitude coordinates display in signed degrees (decimal fractions)
- When you use the control with a Content control to display a map, there may be issues using particular mapping site URLs. See the Issues when using the Content and Location Services Controls knowledge base article for more information
- If you want to retrieve the values of the control when you use the When [control] is Location Changed rule event, you need to add an action to do so, for example to transfer the data
- The control is not a mapping control
- Where no values are retrieved, 0.0 is returned. This means no data is available and applies to latitude, longitude, accuracy, altitude accuracy and altitude
- When you use the Chrome browser, you need to configure the SmartForms runtime site to use the HTTPS protocol to allow the location service
- When you use an Android device, you need to give the K2 Workspace (Mobile) App permission to access the location service
- You can use the control with forms saved as a draft in the K2 Workspace (Mobile) app to save the data on the form to resume at a later point or to work on the form while offline. See How To: Configure Forms with Draft Functionality, Drafts in Android and Building SmartForms for Mobile Devices for more information on saving a form as a draft in the K2 Workspace (Mobile) apps.