GitHub - kizitonwose/CountryPickerView: A simple, customizable view for efficien...
source link: https://github.com/kizitonwose/CountryPickerView
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
CountryPickerView
CountryPickerView is a simple, customizable view for selecting countries in iOS apps.
You can clone/download the repository and run the demo project to see CountryPickerView in action. First run pod install
from the CountryPickerViewDemo directory.
Installation
Note that 2.x releases are Swift 4 compatible. For the Swift 3 compatibility, please use 1.x releases.
Cocoapods
CountryPickerView is available through CocoaPods. Simply add the following to your Podfile:
use_frameworks! target '<Your Target Name>' do pod 'CountryPickerView' end
Carthage
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
To install CountryPickerView through Carthage, simply add the following to your Cartfile:
github "kizitonwose/CountryPickerView"
Manual
- Put CountryPickerView repo somewhere in your project directory.
- In Xcode, add
CountryPickerView.xcodeproj
to your project. - On your app's target, add the CountryPickerView framework:
- as an embedded binary on the General tab.
- as a target dependency on the Build Phases tab.
Usage
If you're using Storyboards/Interface Builder you can create a CountryPickerView instance by adding a UIView to your Storyboard, and then manually changing the view's class to CountryPickerView in the "Custom Class" field of the Identity Inspector tab on the Utilities panel (the right-side panel)
You can also create an instance of CountryPickerView programmatically:
import CountryPickerView let cpv = CountryPickerView(frame: /**Desired frame**/)
To get the selected country from your CountryPickerView
instance at any time, use the selectedCountry
property.
let country = cpv.selectedCountry print(country)
This property is not optional, the default value is the user's current country, derived from the device's current Locale.
Customization
Customization options for the view itself are available directly via the CountryPickerView instance while options for the internal CountryPicker table view are available via the CountryPickerViewDataSource
protocol. Setting the CountryPickerViewDelegate
protocol is also necessary if you wish to be notified when the user selects a country from the list.
import CountryPickerView class DemoViewController: UIViewController, CountryPickerViewDelegate, CountryPickerViewDataSource { @IBOutlet weak var countryPickerView: CountryPickerView! override func viewDidLoad() { super.viewDidLoad() countryPickerView.delegate = self countryPickerView.dataSource = self /*** Direct customizations on CountryPickerView instance ***/ // Show the selected country's phone(e.g +234) code on the view countryPickerView.showPhoneCodeInView = true // Show the selected country's iso code(e.g NG) on the view countryPickerView.showCountryCodeInView = true } }
CountryPickerViewDelegate
-
Called when the user selects a country from the list or when you manually set the
selectedCountry
property of theCountryPickerView
func countryPickerView(_ countryPickerView: CountryPickerView, didSelectCountry country: Country)
-
Called before the internal UITableViewController is presented or pushed.
func countryPickerView(_ countryPickerView: CountryPickerView, willShow viewController: UITableViewController)
-
Called after the internal UITableViewController is presented or pushed.
func countryPickerView(_ countryPickerView: CountryPickerView, didShow viewController: UITableViewController)
Note: willShow
and didShow
delegate methods are optional. Also, if the UITableViewController is presented(not pushed), it is embedded in a UINavigationController.
CountryPickerViewDataSource
The datasource methods define the internal(country list) ViewController's behavior. Run the demo project to play around with the options. All methods are optional.
-
An array of countries you wish to show at the top of the list. This is useful if your app is targeted towards people in specific countries.
func preferredCountries(in countryPickerView: CountryPickerView) -> [Country]
-
The desired title for the preferred section.
func sectionTitleForPreferredCountries(in countryPickerView: CountryPickerView) -> String?
Note: You have to return a non-empty array of countries from
preferredCountries(in countryPickerView: CountryPickerView)
as well as this section title if you wish to show preferred countries on the list. Returning only the array or title will not work. -
Show ONLY the preferred countries section on the list. Default value is
false
func showOnlyPreferredSection(in countryPickerView: CountryPickerView) -> Bool
Return
true
to hide the internal list so your users can only choose from the preferred countries list. -
The desired font for the section title labels on the list. Can be used to configure the text size.
func sectionTitleLabelFont(in countryPickerView: CountryPickerView) -> UIFont
-
The desired font for the cell labels on the list. Can be used to configure the text size.
func cellLabelFont(in countryPickerView: CountryPickerView) -> UIFont
-
The desired size for the flag images on the list.
func cellImageViewSize(in countryPickerView: CountryPickerView) -> CGSize
-
The desired corner radius for the flag images on the list.
func cellImageViewCornerRadius(in countryPickerView: CountryPickerView) -> CGFloat
-
The navigation item title when the internal view controller is pushed/presented. Default value is
nil
func navigationTitle(in countryPickerView: CountryPickerView) -> String?
-
A navigation item button to be used if the internal view controller is presented(not pushed). If nil is returned, a default "Close" button is used. This method only enables you return a button customized the way you want. Default value is
nil
func closeButtonNavigationItem(in countryPickerView: CountryPickerView) -> UIBarButtonItem?
Note: Any
target
oraction
associated with this button will be replaced as this button's sole purpose is to close the internal view controller. -
Desired position for the search bar. Default value is
.tableViewHeader
func searchBarPosition(in countryPickerView: CountryPickerView) -> SearchBarPosition
Possible values are:
.tableViewHeader
,.navigationBar
and.hidden
-
Show the phone code alongside the country name on the list. e.g Nigeria (+234). Default value is
false
func showPhoneCodeInList(in countryPickerView: CountryPickerView) -> Bool
Using CountryPickerView with UITextField
A good use case for CountryPickerView
is when used as the left view of a phone number input field.
class DemoViewController: UIViewController { @IBOutlet weak var phoneNumberField: UITextField! override func viewDidLoad() { super.viewDidLoad() let cpv = CountryPickerView(frame: CGRect(x: 0, y: 0, width: 120, height: 20)) phoneNumberField.leftView = cpv phoneNumberField.leftViewMode = .always } }
This means your users do not have to worry about entering the country's phone code in the text field. This also ensures you get a valid phone code from CountryPickerView
instead of relying on your users.
Using the internal picker independently
If for any reason you do not want to show the default view or have your own implementation for showing country information, you can still use the internal picker to allow your users select countries from the list by calling the method showCountriesList(from: UIViewController)
on a CountryPickerView
instance.
It's important to keep a field reference to the CountryPickerView
instance else it will be garbage collected and any attempt to use it will result to a crash.
class DemoViewController: UIViewController { // Keep a field reference let countryPickerView = CountryPickerView() override func viewDidLoad() { super.viewDidLoad() } @IBAction func buttonPressed(_ sender: Any) { countryPickerView.showCountriesList(from: self) } }
In the example above, calling countryPickerView.showCountriesList(from: self)
will result in the internal picker view controller being presented in its own navigation stack because DemoViewController
is not a navigation controller.
If you already have a navigation stack, you can push the internal picker view controller onto that stack by calling countryPickerView.showCountriesList(from: self.navigationController!)
or do it the safe way:
if let nav = self.navigationController { countryPickerView.showCountriesList(from: nav) }
Don't forget to set a delegate to be notified when the use selects a country from the list. An example of how to use the internal picker view controller is included in the demo project.
License
CountryPickerView is distributed under the MIT license. See LICENSE for details.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK