Charcoal is a declarative library that simplifies the creation of modern filtering experiences. It allows you in a flexible way to represent complex filtering flows in just a few steps. When building Charcoal we have taken major steps to ensure every UI element is refined to provide a great experience to your users, taking in account things such as accessibility and customization.
At FINN, filtering is one of the key elements of our native apps and we believe we are not alone on this, this is why we have taken the time and effort to share our countless hours of iterations and redesigns to share with you what we believe is one of the best filtering experiences, say hi to Charcoal.
Charcoal /ˈtʃɑːkəʊl/: a porous black solid, consisting of an amorphous form of carbon, obtained as a residue when wood, bone, or other organic matter is heated in the absence of air. Used among other things as an effective component of filtering.
Charcoal is available through CocoaPods. To install
the core module of the framework, simply add the following line to your
pod "Charcoal", git: "https://github.com/finn-no/charcoal-ios"
You will also need to include the FinniversKit dependency in your Podfile.
pod "FinniversKit", git: "https://github.com/finn-no/FinniversKit"
For using FINN-specific configuration in addition to core functionality:
pod 'Charcoal/FINN', git: "https://github.com/finn-no/charcoal-ios"
Add Charcoal to your project through Xcode by navigating to
File > Swift Packages > Add Package Dependency and
Add this line to your
Package.swift. We may not always update the version string below in this
README, so make sure to
check the list of available tags and select the newest one.
.package(name: "Charcoal", url: "https://github.com/finn-no/charcoal-ios.git", from: "10.0.0")
Don't forget to add
Charcoal as a dependency to your intended target!
let container = FilterContainer( rootFilters: [ // Multi-level list filter Filter(title: "Area", key: "area", subfilters: [ Filter(title: "Oslo", key: "area", value: "Oslo"), Filter(title: "Bergen", key: "area", value: "Bergen"), ]), // Range slider with number inputs Filter.range( title: "Price", key: "price", lowValueKey: "price_from", highValueKey: "price_to", config: RangeFilterConfiguration( minimumValue: 1000, maximumValue: 100000, valueKind: .incremented(1000), hasLowerBoundOffset: false, hasUpperBoundOffset: true, unit: .currency, usesSmallNumberInputFont: false ) ), // Map filter Filter.map( title: "Map", key: "map", latitudeKey: "latitude", longitudeKey: "longitude", radiusKey: "radius", locationKey: "location" ) ], freeTextFilter: Filter.freeText(key: "query"), inlineFilter: Filter.inline(title: "", key: "inline", subfilters: inlineFilters), numberOfResults: 100 )
CharcoalViewController, set optional delegates and data sources for handling selection changes, responding to user interactions with the map and free text search filters, etc.:
let viewController = CharcoalViewController() viewController.mapDataSource = mapDataSource viewController.searchLocationDataSource = searchLocationDataSource viewController.freeTextFilterDataSource = freeTextFilterService viewController.freeTextFilterDelegate = freeTextFilterService viewController.selectionDelegate = self viewController.textEditingDelegate = self
viewController.filterContainer = filterContainer
nameof the query item is the filter key and
valueis the selected filter value:
let selection = Set([ URLQueryItem(name: "area", value: "Oslo"), URLQueryItem(name: "price_from", value: "10000") ]) viewController.set(selection: selection)
This project has a
Gemfile that specify some development dependencies, one of those is
pr_changelog which is a tool that helps you to generate changelogs from the Git history of the repo. You install this by running
To get the changes that have not been released yet just run:
If you want to see what changes were released in the last version, run:
$ pr_changelog --last-release
You can always run the command with the
--help flag when needed.
Some of the UI elements in Charcoal are taken from FinniversKit, a framework which holds all the UI elements of the FINN iOS app.
bundle install(dependencies will be installed in
.envfile or adding it to
.bash_profile). Don't forget to run
source .env(for whichever file you set the environment variables in) if you don't want to restart your shell.
bundle exec fastlane verify_environment_variableto see if it is configured correctly.
bundle exec fastlane verify_ssh_to_githubto see if ssh to GitHub is working.
bundle exec fastlane make_charcoal_version. Follow instructions, you will be asked for confirmation before all remote changes.
Charcoal is available under the MIT license. See the LICENSE file for more info.
|Last commit: 14 hours ago|