zhuorantan / locationpicker

A ready for use and fully customizable location picker for your app

LocationPicker

A ready for use and fully customizable location picker for your app.

• Features
• Installation
  • Cocoapods
  • Carthage
  • Swift Package Manager
• Quick Start
  • Programmatically
  • Storyboard
• Customization
  • Methods
  • Boolean
  • Text
  • Color
  • Image
  • Other
• Callback
  • Closure
  • Delegate and Data Source
  • Override
• Location Item
  • Storage
  • Equatable
  • Properties
  • Initialization
• Change Log
• Contribute
• License

Features

• Easy to use - A fully functional location picker can be integrated to your app within 5 lines of codes. LocationPicker can be subclassed in storyboard or programmatically.
• Comprehensive - LocationPicker provides Closure, Delegate and Data Source, Override for callback to suit your need.
• All kinds of locations to pick - Users can pick locations from their current location, search results or a list of locations provided by your app.
• Fully customizable - LocationPicker provides a great deal of customizability allowing all text to be customized along with the colors and icons. Original UI elements like UISearchBar, UITableView, MKMapItem are also accessible if you want to do some deep customization.
• Permission worry free - LocationPicker requests location access for you.

Installation

Cocoapods

CocoaPods is a dependency manager for Cocoa projects.

You can install it with the following command:

$ gem install cocoapods

To integrate LocationPicker into your Xcode project using CocoaPods, specify it in your Podfile:

platform :ios, '8.0'
use_frameworks!

target 'YourApp' do
    pod 'LocationPickerViewController'
end

Carthage

Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate LocationPicker into your Xcode project using Carthage, specify it in your Cartfile:

github "JeromeTan1997/LocationPicker"

Swift Package Manager

Swift Package Manager is a tool for managing the distribution of Swift code.

Swift Package Manager is currently only available with the Swift 3 development snapshots.

To integrate LocationPicker into your Xcode project using Swift Package Manager, specify it in your Packages.swift:

import PackageDescription

let package = Package(
    name: "Your Project Name",
    targets: [],
    dependencies: [
        .Package(url: "https://github.com/JeromeTan1997/LocationPicker.git", versions: "2.0.0" ..< Version.max)
    ]
)

Quick Start

Programmatically

Import LocationPicker

import LocationPicker

NOTE: If you installed via Cocoapods:

import LocationPickerViewController

Showing LocationPicker via navigation controller is very simple, just create one, add a completion closure and push it.

let locationPicker = LocationPicker()
locationPicker.pickCompletion = { (pickedLocationItem) in
    // Do something with the location the user picked.
}
navigationController!.pushViewController(locationPicker, animated: true)

To present LocationPicker, it needs to be nested inside a navigation controller so that it can be dismissed.

let locationPicker = LocationPicker()
locationPicker.pickCompletion = { (pickedLocationItem) in
    // Do something with the location the user picked.
}
locationPicker.addBarButtons()
// Call this method to add a done and a cancel button to navigation bar.

let navigationController = UINavigationController(rootViewController: customLocationPicker)
presentViewController(navigationController, animated: true, completion: nil)

Storyboard

1. Drag a View Controller to your Storyboard.
2. In the Identity inspector, Entry LocationPicker both in Class and Module field. NOTE: If you installed via Cocopods, the Module field should be LocationPickerViewController
3. Create a segue and add a Identifier to it.
4. Add the following codes in the source view controller.

override func prepareForSegue(segue: UIStoryboardSegue, sender: AnyObject?) {
    if segue.identifier == "Your Identifier" {
        let locationPicker = segue.destinationViewController as! LocationPicker
        locationPicker.pickCompletion = { (pickedLocationItem) in
            // Do something with the location the user picked.
        }
    }
}

That's all you need to have a fully functional location picker in your app. How easy!

Note: To use current location, don't forget to add NSLocationWhenInUseUsageDescription to your info.plist

Customization

Methods

func addBarButtons

This method provides 3 optional parameter. doneButtonItem and cancelButtonItem can be set as the customized UIBarButtonItem object. doneButtonOrientation is used to determine how to align these two buttons. If none of the parameters is provided, two system style buttons would be used, and the done button would be put on the right side.

After this method is called, these two buttons can be accessed via barButtonItems property.

func setColors

This method aims to set colors more conveniently. themColor will be set to currentLocationIconColor, searchResultLocationIconColor, alternativeLocationIconColor, pinColor. primaryTextColor and secondaryTextColor can also be set by this method.

func setLocationDeniedAlertControllerTitle

This method provides the text of locationDeniedAlertController simultaneously.

If this method is not called, the alert controller will be presented like this

Grant button will direct user to the Settings where location access can be changed.

Boolean

Property name	Default	Target	Remark
allowArbitraryLocation	false		Allows the selection of locations that did not match or exactly match search results
mapViewZoomEnabled	true	mapView.zoomEnabled	Whether the map view can zoom in and out
mapViewShowsUserLocation	true	mapView.showsUserLocation	Whether the map view shows user's location
mapViewScrollEnabled	true	mapView.scrollEnabled	Whether user can scroll the map view
isRedirectToExactCoordinate	true		Whether redirect to the exact coordinate after queried
alternativeLocationEditable	false	tableViewDataSource.tableView(tableView: UITableView, canEditRowAtIndexPath indexPath: NSIndexPath)	Whether user can delete the provided locations in table view
forceReverseGeocoding	false		Whether to force reverse geocoding or not. If this property is set to true, the location will be reverse geocoded

Note: If alternativeLocationEditable is set to true, please adopt Location Deletion callback to delete the location from database or memory.

Text

Property name	Default	Target	Remark
currentLocationText	"Current Location"	currentLocationCell.locationNameLabel.text	The text that indicates the user's current location
searchBarPlaceholder	"Search for location"	searchBar.placeholder	The text that ask user to search for locations
locationDeniedAlertTitle	"Location access denied"	alertController.title	The text of the alert controller's title
locationDeniedAlertMessage	"Grant location access to use current location"	alertController.message	The text of the alert controller's message
locationDeniedGrantText	"Grant"	alertAction.title	The text of the alert controller's Grant button
locationDeniedCancelText	"Cancel"	alertAction.title	The text of the alert controller's Cancel button

Color

Property name	Default	Target	Remark
tableViewBackgroundColor	UIColor.whiteColor()	tableView.backgroundColor	The background color of the table view
currentLocationIconColor	UIColor(hue: 0.447, saturation: 0.731, brightness: 0.569, alpha: 1)	UIImage()	The color of the icon showed in current location cell, the icon image can be changed via property currentLocationIconImage
searchResultLocationIconColor	UIColor(hue: 0.447, saturation: 0.731, brightness: 0.569, alpha: 1)	UIImage()	The color of the icon showed in search result location cells, the icon image can be changed via property searchResultLocationIconImage
alternativeLocationIconColor	UIColor(hue: 0.447, saturation: 0.731, brightness: 0.569, alpha: 1)	UIImage()	The color of the icon showed in alternative location cells, the icon image can be changed via property 'alternativeLocationIconImage'
pinColor	UIColor(hue: 0.447, saturation: 0.731, brightness: 0.569, alpha: 1)	UIImage()	The color of the pin showed in the center of map view, the pin image can be changed via property pinImage
primaryTextColor	UIColor(colorLiteralRed: 0.34902, green: 0.384314, blue: 0.427451, alpha: 1)	Multiple	The text color of search bar and location name label in location cells
secondaryTextColor	UIColor(colorLiteralRed: 0.541176, green: 0.568627, blue: 0.584314, alpha: 1)	Multiple	The text color of location address label in location cells

Image

Property name	Target	Remark
currentLocationIconImage	currentLocationCell.iconView.image	The image of the icon showed in current location cell, this image's color won't be affected by property currentLocationIconColor
searchResultLocationIconImage	searchResultLocationCell.iconView.image	The image of the icon showed in search result location cells, this image's color won't be affected by property searchResultLocationIconColor
alternativeLocationIconImage	alternativeLocationCell.iconView.image	The image of the icon showed in alternative location cells, this image's color won't be affected by property alternativeLocationIconColor

Other

Property name	Type	Default	Remark
alternativeLocations	[LocationItem]?	nil	Locations that show under current location and search result locations
locationDeniedAlertController	UIAlertController?	nil	Alert controller that appear when user request current location but denied the app's location permission
defaultLongitudinalDistance	Double	1000	Longitudinal distance of the map view shows when user select a location and before zoom in or zoom out
searchDistance	Double	10000	Distance in meters that is used to search locations

Note:

• Alternative locations can also be provided via Data Source.
• You don't need to set the locationDeniedAlertController if you are satisfied with the alert controller included in LocationPicker. You can change the text of the default alert controller via func setLocationDeniedAlertControllerTitle. If you want to do something other than presenting an alert controller, you can adopt Permission Denied Handler callback.

Callbacks

LocationPicker provides three different types of callbacks, they are Closure, Delegate and Data Source and Override, you can choose whichever you like. In most cases, using closures is the most convenient way. If you are already subclassing LocationPicker, override may be the best choice.

Closure

Location Pick

This completion closure is used to get user's final decision. It would be executed only once for every LocationPicker object when it is about to be dismissed.

locationPicker.pickCompletion = { (pickedLocationItem) in
    // Do something with the location the user picked.
}

Location Selection

This completion closure is used to get user's every location selection. It would be executed every time user chooses a location in the list or drag the map view.

locationPicker.selectCompletion = { (selectedLocationItem) in
    // Do something with user's every selection.
}

Location Deletion

If alternativeLocations is not empty and alternativeLocationEditable is set to true, this closure will be executed when user delete a location item in the table view.

locationPicker.deleteCompletion = { (deletedLocationItem) in
    // Delete the location.
}

Permission Denied Handler

By default, when user request current location but denied the app's location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this closure.

locationPicker.locationDeniedHandler = { (locationPicker) in
    // Ask user to grant location access of this app.
}

Delegate and Data Source

To use a delegate or data source, the following steps need to be taken:

1. Conform to LocationPickerDelegate or LocationPickerDataSource

class YourViewController: LocationPickerDelegate, LocationPickerDataSource

2. Set delegate or dataSource to this class

locationPicker.delegate = self
locationPicker.dataSource = self

3. Implement methods in delegate or dataSource

Location Pick

This delegate method is used to get user's final decision. It would be called only once for every LocationPicker object when it is about to be dismissed.

func locationDidPick(locationItem: LocationItem) {
    // Do something with the location the user picked.
}

Location Selection

This delegate method is used to get user's every location selection. It would be called every time user chooses a location in the list or drag the map view.

func locationDidSelect(locationItem: LocationItem) {
    // Do something with user's every selection.
}

Alternative Locations

This data source method is used to provide locations that show under current location and search result locations. Instead of using delegate, you can also just set the alternativeLocations property.

func numberOfAlternativeLocations() -> Int {
    // Get the number of locations you need to add to the location list.
    return count
}
func alternativeLocationAtIndex(index: Int) -> LocationItem {
    // Get the location item for the specific index.
    return locationItem
}

Location Deletion

If alternativeLocations is not empty and alternativeLocationEditable is set to true, this data source method will be called when user delete a location item in the table view.

func commitAlternativeLocationDeletion(locationItem: LocationItem) {
    // Delete the location.
}

Permission Denied Handler

By default, when user request current location but denied the app's location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this delegate method.

func locationDidDeny(locationPicker: LocationPicker) {
    // Ask user to grant location access of this app.
}

Override

If you prefer to subclass LocationPicker, these methods can be overridden to achieve the same result as closure and delegate.

Location Pick

This method is used to get user's final decision. It would be called only once for every LocationPicker object when it is about to be dismissed.

override func locationDidPick(locationItem: LocationItem) {
    // Do something with the location the user picked.
}

Location Selection

This method is used to get user's every location selection. It would be called every time user chooses a location in the list or drag the map view.

Note: If you override these methods, the corresponding closure and delegate method won't be executed.

override func locationDidSelect(locationItem: LocationItem) {
    // Do something with user's every selection.
}

Location Deletion

If alternativeLocations is not empty and alternativeLocationEditable is set to true, this method will be called when user delete a location item in the table view.

override func alternativeLocationDidDelete(locationItem: LocationItem) {
    // Delete the location.
}

Permission Denied Handler

By default, when user request current location but denied the app's location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this method.

override func locationDidDeny(locationPicker: LocationPicker) {
    // Ask user to grant location access of this app.
}

Location Item

LocationItem is a encapsulation class of MKMapItem to save you from importing MapKit everywhere in your project. To make it more convenient to use, it equips with several computing properties to access the MKMapItem.

Storage

LocationItem is conformed to NSCoding, which means LocationItem object can be encoded to NSData object and decoded back.

let locationData = NSKeyedArchiver.archivedDataWithRootObject(locationItem)
let locationItem = NSKeyedUnarchiver.unarchiveObjectWithData(locationData) as! LocationItem

Equatable

The hash value of LocationItem is "\(coordinate.latitude), \(coordinate.longitude)".hashValue, so objects that have the same latitude and longitude are equal.

Properties

Property name	Type	Target	Remark
name	String	mapItem.name	The name of the location
coordinate	(latitude: Double, longitude: Double)?	mapItem.placemark.coordinate	The coordinate of the location and converted to tuple. If the user is offline or there is no search result and the allowArbitraryLocation property of LocationPicker is set to true, this property will be nil
addressDictionary	[NSObject: AnyObject]?	mapItem.placemark.addressDictionary	The address dictionary of the location
formattedAddressString	String?	addressDictionary?["FormattedAddressLines"]	The address text formatted according to user's region

If you want to access other properties of MKMapItem object, just call locationItem.mapItem.

Initialization

init(mapItem: MKMapItem)

Since LocationItem is just the encapsulation of MKMapItem, of course you can create a LocationItem with a MKMapItem object.

init(coordinate: (latitude: Double, longitude: Double), addressDictionary: [String: AnyObject])

You can also initialize with the coordinate and address dictionary.

If you don't want to store LocationItem objects as NSData, you can just store the coordinate and address dictionary, and use this method to initialize.

init(locationName: String)

A location can be created with only a name. In this case, the value of property coordinate would be nil.

Change Log

CHANGELOG.md

Contribute

• If you encounter any bugs or other problems, please create issues or pull requests.
• If you want to add more features to LocationPicker, you are more than welcome to create pull requests.
• If you are good at English, please correct my English.
• If you like the project, please star it and share with others.
• If you have used LocationPicker in your App, please tell me by creating an issue.

License

The MIT License (MIT)

Copyright (c) 2016 Jerome Tan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

locationpicker's Issues

Change the scope of variables and methods

Please, make all of LocationPickerViewController varibles and methods open not public.

This is really annoying to changed this code manually if you want to override this class.

Obj-C example

does there exist an Obj-C version of this project?

Add LocationItem flag isCurrentLocation = true

There is no way to know that selected location is a current user's location. pickedLocationItem.mapItem.isCurrentLocation always returns false.

[LocationItem] Fatal Crash in Release Build

LocationItem initialization seems to crash on iOS 11, perhaps when location or internet is disabled. Here's a stacktrace

0	LocationPickerViewController	_hidden#211 line 141specialized LocationItem.init(coder : NSCoder) -> LocationItem
1	LocationPickerViewController	hidden#211 line 0_hidden#165
2	Foundation	_decodeObjectBinary + 1720
4	Foundation	+[NSKeyedUnarchiver unarchiveObjectWithData:] + 88
5	interview	hidden#5816 line 22_hidden#5770
6	interview	hidden#5816 line 0_hidden#5742
7	LocationPickerViewController	_hidden#71 line 340specialized LocationPicker.tableView(UITableView, numberOfRowsInSection : Int) -> Int
8	LocationPickerViewController	hidden#71 line 0_hidden#432
9	UIKit	-[UITableView _numberOfRowsInSection:] + 68
40	UIKit	UIApplicationMain + 236

Line 141 of LocationItem is this one:

let addressDictionary = aDecoder.decodeObject(forKey: "addressDictionary") as! [String: AnyObject]

I suspect a force downcast would cause the crash but I am not sure what would cause this.

issue with Carthage

I was trying to include this library into my project through Carthage, but the command of 'carthage update' returned the following error message:
(carthage version 0.16.2)

Failed to read file or folder at /private/var/folders/lw/4h75rrkj6c74_htcv9nkk2rw0000gn/T/carthage-archive.Be2knk/__MACOSX/LocationPicker.framework: Error Domain=com.antitypical.Result Code=0 "the DTSDKName key in its plist file is missing" UserInfo={com.antitypical.Result.function=readFailed, NSLocalizedDescription=the DTSDKName key in its plist file is missing, com.antitypical.Result.line=776, com.antitypical.Result.file=/tmp/carthage20160413-39362-hmnet1/Source/CarthageKit/Project.swift}

Location

Did not mean to do this, sorry

Compatibility with Objective-C

Hello Jerome,

Thanks for making such a great framework and sharing it with the world.

I am currently working on an Objective-C project and I was wondering if you could make your framework compatible with Objective-C.

Thank you.

Exclude info.plist from Compile Sources

Got the following error

Build system information
error: unexpected duplicate task: CopyPlistFile /DerivedData/Build/Products/Release-iphonesimulator/LocationPickerViewController/LocationPickerViewController.framework/Info.plist /Pods/LocationPickerViewController/LocationPicker/Info.plist (in target 'LocationPickerViewController')

@JeromeTan1997 So please exclude Info.plist from Compile Sources

Preselection feature

Hey @JeromeTan1997 ,

Is there a way to preselect a location?
Something like that:

let locationPicker = LocationPicker()
locationPicker.pickedLocationItem = myItem

or

locationPicker.pickedAddress = "Central Park"

locationPicker.pinImage = UIImage(...) not working?

I tried changing the pin image in the locationPicker (subclassing), but when I set the pinImage to a custom image it doesn't seem to change the image.

how to control Done and Cancel

Hi, I tried to find out how to control this 2 buttons but I could not find out how to do it

can you please give me an example to how to deal with it

thank you

Customize BarButtonItems with addBarButtons func

Hi,

I'm trying and failing to customize the "cancel" and "done" bar button items's text.

I have tried doing this but it does not work.

locationPicker.barButtonItems?.doneButtonItem.title = "newDone"

I also tried this with no luck:

let doneButton = locationPicker.barButtonItems?.doneButtonItem
doneButton?.title = "newDone"
let cancelButton = locationPicker.barButtonItems?.cancelButtonItem
cancelButton?.title = "newCancel"
locationPicker.addBarButtons(doneButtonItem: doneButton, cancelButtonItem: cancelButton, doneButtonOrientation: .right)

Could you provide an example on how to do it the right way?
Thank you!

Demo not working

Hello, I tried to run the demo but seems like it miss locationPicker.framework file. could you please fix it

thank you

Use MKLocalSearchCompleter instead of MKLocalSearchRequest

https://medium.com/@ishabazz/location-search-using-mapkit-works-ae94f3c3dbd7

Can localsearch request be replaced by local search completer, it offers better completion even Apple uses MKLocalSearchCompleter in their maps according to the answer for the SO question. https://stackoverflow.com/questions/43249382/mklocalsearch-doesnt-provide-the-same-results-as-search-in-native-apple-maps-ap

Swift 4 Compiler Error

HI, could you push the 3.4 tag to access your swift 4.2 Migration from Cocoapods ?

Localization question

Hi there, awesome location picker!

How can I change the language the addresses are written in. All addresses are in English, but I would like them to be in Spanish.

Thank you

Even searchDistance is limited, cities can be searched and selected globally

Hi zhuorantan,

Thanks for your framework. It really fits our needs.
Unfortunately there is one thing we experienced which is not working correctly.
I'd like to limit the searchDistance with the provided parameter. It works fine except for searching for city names like London, New York, Frankfurt,...

Do you think you could fix this behavior or maybe there is something I oversaw.

Thank you for any help you can provide!

Here's a screenshot:

LocationItem

open override func isEqual(_ object: Any?) -> Bool {
        guard let object = object else { return false }
        return (object as AnyObject).hash == hashValue
    }

Compilation error on XCode 10.2

Compilation error on XCode 10.2
Class: LocationItem
In method: open override func isEqual(_ object: Any?) -> Bool

Error:
Value of type 'AnyObject' has no member 'hashValue'

I want example in Objective-C

I want example in Objective-C

Can we disable the change of location from the map?

Hi,
Can we disable the change of location from the map?
We just wanted to allow user to set the current actual location?

Doesn't layout properly on iPad in Landscape Mode

Offline usage

Hey, thanks for sharing this framework. I was hoping to add offline support and was wondering what your thoughts are at the moment?

FEATURE: History of searched locations

First of, I would like to thank you for the amazing work you have done so far!

There is just one thing that I and maybe some other people are still missing, which is a support for history of searched locations.

It could be placed right bellow 'Current location' and have exactly the same behavior.

Let me know what do you think about it.

Thank you in advance!

Info.plist error

http://stackoverflow.com/questions/41695645/framework-did-not-have-a-cfbundleidentifier-in-its-info-plist-using-swift-and-co

how to avoid this?

get location name with google api key

Hello,

get location name with google api key and set google map with google api key?

MapKit location search getting throttled

When a user types quickly or when a search text is deleted (by holding the delete key to delete a letter at a time), MapKit may throttle the search causing the error MKErrorDomain error 3 which is MKErrorLoadingThrottled.

StackOverflow reference: http://stackoverflow.com/questions/23505097/ios-app-getting-throttled-from-local-searches

A couple of solutions comes to mind:

1. Delay the search so that it occurs a short time after an inactivity of user input
2. Use Google Places Autocomplete instead of MapKit (or provide the option to use either)

Map moves automatically

Hi,

I find LocationPicker very easy to use however facing an issue.

The place mark moves randomly. Please see attached. How to fix this?

Thanks
Ashish

LocationCell labels text not visible when RTL

Hello,
Thanks for the great library.
I face an issue when changing the device to RTL language
LocationCell labels (locationNameLabel , locationAddressLabel) text not visible (app is fully localized ).
Please someone advice, please

Incompatible with Swift 5

I am getting a compiler error using Swift 5:

{path to project}/Pods/LocationPickerViewController/LocationPicker/LocationItem.swift:122:24: value of type 'AnyObject' has no member 'hashValue'

This is the function causing problems:

open override func isEqual(_ object: Any?) -> Bool { guard let object = object else { return false } return (object as! NSObject).hashValue == hashValue }

Since this class subclasses from NSObject, can we use the default NSObject isEqual definition instead? Thanks for looking into this.

Storyboard approach causes the entire navigation controller to be dismissed

The documentation fails to mention that when using storyboards, the LocationPicker controller should be embedded in its own navigation controller as well if 'Done' and 'Cancel' buttons are used. Otherwise, the 'parent' navigation controller is dismissed due to the call to dismissViewControllerAnimated.

Alternatively, the code could check whether LocationPicker is the root view controller and if not, call navigationController.popViewControllerAnimated instead.

The sizes of the search images is way too big

The image describes all that is needed to be described.

FYI, that is the case even if I don't use any custom images.