Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cgossain/firebaseresultscontroller
An NSFetchedResultsController replacement for FirebaseDatabase on iOS, written in Swift.
https://github.com/cgossain/firebaseresultscontroller
batch-processing diff diffing diffing-data firebase firebase-realtime-database realtime-updates uitableview
Last synced: 7 days ago
JSON representation
An NSFetchedResultsController replacement for FirebaseDatabase on iOS, written in Swift.
- Host: GitHub
- URL: https://github.com/cgossain/firebaseresultscontroller
- Owner: cgossain
- License: mit
- Created: 2017-02-17T00:45:38.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-06T18:09:42.000Z (over 3 years ago)
- Last Synced: 2024-03-15T10:21:34.292Z (8 months ago)
- Topics: batch-processing, diff, diffing, diffing-data, firebase, firebase-realtime-database, realtime-updates, uitableview
- Language: Swift
- Homepage:
- Size: 133 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FirebaseResultsController
[](https://travis-ci.org/[email protected]/FirebaseResultsController)
[](http://cocoapods.org/pods/FirebaseResultsController)
[](http://cocoapods.org/pods/FirebaseResultsController)
[](http://cocoapods.org/pods/FirebaseResultsController)
FirebaseResultsController is a controller used to manage the results of a query attached to a Firebase Realtime Database.
It offers additional filtering and sorting capabilities, diffing support (using LCS algoritm), and realtime content updates. These features come together to facilitate building data driven UITableView's.
## Example
This project includes a simple demo application that demonstrates how to use a FirebaseResultsController to power an instance of UITableView.
### Prerequisites
To run the example project, clone the repo, and run `pod install` from the Example directory first.
You'll also need to create a Firebase account, and follow the instructions to create a demo project. Once your demo project has been created in your Firebase account, you'll need to download the project's corresponding `GoogleService-Info.plist` and add it the demo project. The Firebase framework automatically detects this file when the app launches, and will configure the environment accordingly.
P.S You can just copy your `GoogleService-Info.plist` directly to the `Example/FirebaseResultsController/` directory, and the Xcode project should automatically pick it up.
## Installation
FirebaseResultsController is available through [CocoaPods](http://cocoapods.org). To install
it, simply add the following line to your Podfile:
```ruby
pod "FirebaseResultsController"
```
## Usage Instructions
### FirebaseFetchRequest
To describe a fetch operation, you need to first create a FirebaseFetchRequest. You create a FirebaseFetchRequest with a Firebase DatabaseQuery instance. A DatabaseQuery already provides support for filtering and sorting, but only to a certain extent. If the built in behaviour is not enough, you can specify an NSPredicate, and an array of NSSortDescriptor's that can be applied to the final fetched data.
```
let query: DatabaseQuery = ... // some Firebase query
let fetchRequest = FirebaseFetchRequest(query: query)
fetchRequest.predicate = ... // optional NSPredicate that is applied to fetched data
fetchRequest.sortDescriptors = ... // optional array of NSSortDescriptor's applied to fetched data
```
### FirebaseResultsController
The FirebaseResultsController is the main class used to fetch the data. You create it with a FirebaseFetchRequest, and optionally a `sectionNameKeyPath` on result objects that returns the section name.
```
let controller = FirebaseResultsController(fetchRequest: fetchRequest, sectionNameKeyPath: )
```
You must call `performFetch()` at least once to begin receiving data. Afterwards, if you change the predicate or sort descriptors on the controller's fetch request, you must call `performFetch()` again (i.e. filtering via a search bar).
```
controller.fetchRequest.predicate = ... // updated predicate
controller.fetchRequest.sortDescriptors = ... // updated sort descriptors
controller.performFetch() // reconfigures the controller for the updated fetch request
```
Calling `performFetch()` will attach observers for the specified database query. This automatically provides realtime updates to the controller's content. To enabled diffing these realtime updates, you need to specify a `changeTracker` which is an object that conforms to the `FirebaseResultsControllerChangeTracking` protocol.
```
controller.changeTracker = ... // object that conforms to FirebaseResultsControllerChangeTracking
```
For Example:
```
extension ViewController: FirebaseResultsControllerChangeTracking {
func controller(_ controller: FirebaseResultsController, didChangeContentWith changes: FetchResultChanges) {
tableView.beginUpdates()
// apply section changes
changes.enumerateSectionChanges { (section, sectionIndex, type) in
switch type {
case .insert:
self.tableView.insertSections(IndexSet(integer: sectionIndex), with: .fade)
case .delete:
self.tableView.deleteSections(IndexSet(integer: sectionIndex), with: .fade)
default:
break
}
}
// apply row changes
changes.enumerateRowChanges { (anObject, indexPath, type, newIndexPath) in
switch type {
case .insert:
tableView.insertRows(at: [newIndexPath!], with: .fade)
case .delete:
tableView.deleteRows(at: [indexPath!], with: .fade)
case .update:
self.configureCell(tableView.cellForRow(at: indexPath!)!, with: anObject)
case .move:
tableView.moveRow(at: indexPath!, to: newIndexPath!)
}
}
tableView.endUpdates()
}
}
```
### Composing Results (Beta)
You can use the ComposedFirebaseResultsController to compose multiple FirebaseResultsController together.
```
let controller1 = FirebaseResultsController(fetchRequest: fetchRequest1, sectionNameKeyPath: )
let controller2 = FirebaseResultsController(fetchRequest: fetchRequest2, sectionNameKeyPath: )
let controller3 = FirebaseResultsController(fetchRequest: fetchRequest3, sectionNameKeyPath: )
let controllers = [controller1, controller2, controller3]
let composedResultsController = ComposedFirebaseResultsController(controllers: controllers, composedQuery: )
```
The ComposedFirebaseResultsController maps index paths between the internal controllers and the external aggregated results. It also exposes a similar API to the FirebaseResultsController.
## Contribution
Create a fork of the project into your own repository. Make all your necessary changes and create a pull request with a description on what was added or removed and details explaining the changes in lines of code. If approved, project owners will merge it.
## Author
Christian Gossain, [email protected]
## License
FirebaseResultsController is released under the MIT license. See [LICENSE](https://github.com/cgossain/FirebaseResultsController/blob/master/LICENSE) for details.