{"id":20245890,"url":"https://github.com/finn-no/charcoal-ios","last_synced_at":"2025-04-05T05:09:22.946Z","repository":{"id":33266683,"uuid":"128935627","full_name":"finn-no/charcoal-ios","owner":"finn-no","description":"A modern way to filter things in your iOS apps","archived":false,"fork":false,"pushed_at":"2024-11-21T11:54:03.000Z","size":464277,"stargazers_count":119,"open_issues_count":0,"forks_count":7,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T04:11:59.225Z","etag":null,"topics":["filtering","ios","library"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finn-no.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-10T13:18:04.000Z","updated_at":"2024-11-21T11:42:53.000Z","dependencies_parsed_at":"2023-01-15T00:15:47.695Z","dependency_job_id":"31073052-a07a-4d5a-b259-cdb8c36a8e73","html_url":"https://github.com/finn-no/charcoal-ios","commit_stats":null,"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finn-no%2Fcharcoal-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finn-no%2Fcharcoal-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finn-no%2Fcharcoal-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finn-no%2Fcharcoal-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finn-no","download_url":"https://codeload.github.com/finn-no/charcoal-ios/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289429,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filtering","ios","library"],"created_at":"2024-11-14T09:24:47.488Z","updated_at":"2025-04-05T05:09:22.923Z","avatar_url":"https://github.com/finn-no.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Deprecated! This repository is no longer maintained**\n\nOld README for reference:\n\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/finn-no/FilterKit/blob/master/GitHub/Charcoal.png\" width=\"100%\" /\u003e\u003c/p\u003e\n\n[![CI Status](https://circleci.com/gh/finn-no/charcoal-ios.png?style=shield)](https://circleci.com/gh/finn-no/charcoal-ios)\n[![Version](https://img.shields.io/cocoapods/v/Charcoal.svg?style=flat)](http://cocoadocs.org/docsets/Charcoal)\n[![License](https://img.shields.io/cocoapods/l/Charcoal.svg?style=flat)](http://cocoadocs.org/docsets/Charcoal)\n[![Platform](https://img.shields.io/cocoapods/p/Charcoal.svg?style=flat)](http://cocoadocs.org/docsets/Charcoal)\n[![Documentation](https://img.shields.io/cocoapods/metrics/doc-percent/Charcoal.svg?style=flat)](http://cocoadocs.org/docsets/Charcoal)\n![Swift](https://img.shields.io/badge/%20in-swift%205.0-orange.svg)\n\n## Description\n\n**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.\n\nAt 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**.\n\n**Why Charcoal?**\n\n_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._\n\n## Features\n\n- [x] Out-of-the-box implementations of various filters\n- [x] Simple configuration and easy to use public API\n- [x] All-in-one solution for handling of complex filtering flows\n- [x] Beautiful design, UI animations and accessibility support\n- [x] Haptic feedback\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/GitHub/demo.gif\"/\u003e\n\u003c/p\u003e\n\n## Installation\n\n### CocoaPods\n\n**Charcoal** is available through [CocoaPods](http://cocoapods.org). To install\nthe core module of the framework, simply add the following line to your `Podfile`:\n\n```ruby\npod \"Charcoal\", git: \"https://github.com/finn-no/charcoal-ios\"\n```\n\nYou will also need to include the FinniversKit dependency in your Podfile.\n```ruby\npod \"FinniversKit\", git: \"https://github.com/finn-no/FinniversKit\"\n```\n\nFor using FINN-specific configuration in addition to core functionality:\n\n```ruby\npod 'Charcoal/FINN', git: \"https://github.com/finn-no/charcoal-ios\"\n```\n\n### Swift Package Manager\n#### Xcode\nAdd **Charcoal** to your project through Xcode by navigating to `File \u003e Swift Packages \u003e Add Package Dependency` and\nspecify `https://github.com/finn-no/charcoal-ios`.\n\n#### Manual – `Package.swift`\nAdd this line to your `Package.swift`. We may not always update the version string below in this `README`, so make sure to\ncheck the list of [available tags](https://github.com/finn-no/charcoal-ios/tags) and select the newest one.\n\n```swift\n.package(name: \"Charcoal\", url: \"https://github.com/finn-no/charcoal-ios.git\", from: \"10.0.0\")\n```\n\nDon't forget to add `Charcoal` as a dependency to your intended target!\n\n## Usage\n\n1. Setup\n\n```swift\nimport Charcoal\n\nlet charcoalConfiguration = CustomImplementationOfCharcoalConfiguration()\nCharcoal.setup(charcoalConfiguration)\n```\n\n2. Create filter container with a list of filters, for example:\n\n```swift\nlet container = FilterContainer(\n    rootFilters: [\n        // Multi-level list filter\n        Filter(title: \"Area\", key: \"area\", subfilters: [\n            Filter(title: \"Oslo\", key: \"area\", value: \"Oslo\"),\n            Filter(title: \"Bergen\", key: \"area\", value: \"Bergen\"),\n        ]),\n        // Range slider with number inputs\n        Filter.range(\n            title: \"Price\",\n            key: \"price\",\n            lowValueKey: \"price_from\",\n            highValueKey: \"price_to\",\n            config: RangeFilterConfiguration(\n                minimumValue: 1000,\n                maximumValue: 100000,\n                valueKind: .incremented(1000),\n                hasLowerBoundOffset: false,\n                hasUpperBoundOffset: true,\n                unit: .currency(unit: \"kr\"),\n                usesSmallNumberInputFont: false\n            )\n        ),\n        // Map filter\n        Filter.map(\n            title: \"Map\",\n            key: \"map\",\n            latitudeKey: \"latitude\",\n            longitudeKey: \"longitude\",\n            radiusKey: \"radius\",\n            locationKey: \"location\"\n        )\n    ],\n    freeTextFilter: Filter.freeText(key: \"query\"),\n    inlineFilter: Filter.inline(title: \"\", key: \"inline\", subfilters: inlineFilters),\n    numberOfResults: 100\n)\n```\n\n2. Create `CharcoalViewController`, set optional delegates and data sources for\nhandling selection changes, responding to user interactions with the map and free\ntext search filters, etc.:\n\n```swift\nlet viewController = CharcoalViewController()\nviewController.mapDataSource = mapDataSource\nviewController.searchLocationDataSource = searchLocationDataSource\nviewController.freeTextFilterDataSource = freeTextFilterService\nviewController.freeTextFilterDelegate = freeTextFilterService\nviewController.selectionDelegate = self\nviewController.textEditingDelegate = self\n```\n\n3. Assign an instance of filter container to your view controller:\n\n```swift\nviewController.filterContainer = filterContainer\n```\n\n4. If needed, pre-select some of the filters by using a set of `URLQueryItem`'s,\nwhere `name` of the query item is the filter key and `value` is the selected\nfilter value:\n\n```swift\nlet selection = Set([\n    URLQueryItem(name: \"area\", value: \"Oslo\"),\n    URLQueryItem(name: \"price_from\", value: \"10000\")\n])\nviewController.set(selection: selection)\n```\n\n## Changelogs\n\nThis 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`.\n\nTo get the changes that have not been released yet just run:\n\n```\n$ pr_changelog\n```\n\nIf you want to see what changes were released in the last version, run:\n\n```\n$ pr_changelog --last-release\n```\n\nYou can always run the command with the `--help` flag when needed.\n\n## Dependencies\n\nSome of the UI elements in **Charcoal** are taken from [FinniversKit](https://github.com/finn-no/FinniversKit),\na framework which holds all the UI elements of the FINN iOS app.\n\n## Creating a new release\n\n### Setup\n- Install dependencies listed in Gemfile with `bundle install` (dependencies will be installed in `./bundler`)\n- Fastlane will use the GitHub API, so make sure to create a personal access token [here](https://github.com/settings/tokens) and place it within an environment variable called **`CHARCOAL_GITHUB_ACCESS_TOKEN`**.\n  - When creating a token, you only need to give access to the scope `repo`.\n  - There are multiple ways to make an environment variable, for example by using a `.env` file or adding it to `.bashrc`/`.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.\n  - Run `bundle exec fastlane verify_environment_variable` to see if it is configured correctly.\n- Run `bundle exec fastlane verify_ssh_to_github` to see if ssh to GitHub is working.\n\n### Make release\n- Run `bundle exec fastlane make_charcoal_version`. Follow instructions, you will be asked for confirmation before all remote changes.\n- After the release has been created you can edit the description on GitHub by using the printed link.\n\n## License\n\n**Charcoal** is available under the MIT license. See the [LICENSE](https://github.com/finn-no/charcoal-ios/blob/master/LICENSE.md) file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinn-no%2Fcharcoal-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinn-no%2Fcharcoal-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinn-no%2Fcharcoal-ios/lists"}