Old README for reference:
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.
Why 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.
- Out-of-the-box implementations of various filters
- Simple configuration and easy to use public API
- All-in-one solution for handling of complex filtering flows
- Beautiful design, UI animations and accessibility support
- Haptic feedback
Charcoal is available through CocoaPods. To install
the core module of the framework, simply add the following line to your Podfile:
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
specify https://github.com/finn-no/charcoal-ios.
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!
- Setup
import Charcoal
let charcoalConfiguration = CustomImplementationOfCharcoalConfiguration()
Charcoal.setup(charcoalConfiguration)- Create filter container with a list of filters, for example:
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(unit: "kr"),
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
)- Create
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- Assign an instance of filter container to your view controller:
viewController.filterContainer = filterContainer- If needed, pre-select some of the filters by using a set of
URLQueryItem's, wherenameof the query item is the filter key andvalueis 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 bundle install.
To get the changes that have not been released yet just run:
$ pr_changelog
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.
- Install dependencies listed in Gemfile with
bundle install(dependencies will be installed in./bundler) - Fastlane will use the GitHub API, so make sure to create a personal access token here and place it within an environment variable called
CHARCOAL_GITHUB_ACCESS_TOKEN.- When creating a token, you only need to give access to the scope
repo. - There are multiple ways to make an environment variable, for example by using a
.envfile or adding it to.bashrc/.bash_profile). Don't forget to runsource .env(for whichever file you set the environment variables in) if you don't want to restart your shell. - Run
bundle exec fastlane verify_environment_variableto see if it is configured correctly.
- When creating a token, you only need to give access to the scope
- Run
bundle exec fastlane verify_ssh_to_githubto see if ssh to GitHub is working.
- Run
bundle exec fastlane make_charcoal_version. Follow instructions, you will be asked for confirmation before all remote changes. - After the release has been created you can edit the description on GitHub by using the printed link.
Charcoal is available under the MIT license. See the LICENSE file for more info.