-
Notifications
You must be signed in to change notification settings - Fork 3.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(ui): add firebase_ui_database (#9341)
- Loading branch information
Showing
141 changed files
with
6,507 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
# Miscellaneous | ||
*.class | ||
*.log | ||
*.pyc | ||
*.swp | ||
.DS_Store | ||
.atom/ | ||
.buildlog/ | ||
.history | ||
.svn/ | ||
migrate_working_dir/ | ||
|
||
# IntelliJ related | ||
*.iml | ||
*.ipr | ||
*.iws | ||
.idea/ | ||
|
||
# The .vscode folder contains launch configuration and tasks you configure in | ||
# VS Code which you may wish to be included in version control, so this line | ||
# is commented out by default. | ||
#.vscode/ | ||
|
||
# Flutter/Dart/Pub related | ||
# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock. | ||
/pubspec.lock | ||
**/doc/api/ | ||
.dart_tool/ | ||
.packages | ||
build/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
# This file tracks properties of this Flutter project. | ||
# Used by Flutter tool to assess capabilities and perform upgrades etc. | ||
# | ||
# This file should be version controlled and should not be manually edited. | ||
|
||
version: | ||
revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
channel: stable | ||
|
||
project_type: package |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
## 1.0.0-dev.0 | ||
|
||
- Bump "firebase_ui_database" to `1.0.0-dev.0`. | ||
|
||
## 0.0.1 | ||
|
||
* TODO: Describe initial release. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
Copyright 2017, the Chromium project authors. All rights reserved. | ||
Redistribution and use in source and binary forms, with or without | ||
modification, are permitted provided that the following conditions are | ||
met: | ||
|
||
* Redistributions of source code must retain the above copyright | ||
notice, this list of conditions and the following disclaimer. | ||
* Redistributions in binary form must reproduce the above | ||
copyright notice, this list of conditions and the following | ||
disclaimer in the documentation and/or other materials provided | ||
with the distribution. | ||
* Neither the name of Google Inc. nor the names of its | ||
contributors may be used to endorse or promote products derived | ||
from this software without specific prior written permission. | ||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | ||
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | ||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,170 @@ | ||
# Firebase UI for Realtime Database | ||
|
||
Firebase UI enables you to easily integrate your application UI with your Realtime database. | ||
|
||
## Installation | ||
|
||
```sh | ||
flutter pub add firebase_database | ||
flutter pub add firebase_ui_database | ||
``` | ||
|
||
## Usage | ||
|
||
Import the Firebase UI for Realtime Database package. | ||
|
||
```dart | ||
import 'package:firebase_ui_database/firebase_ui_database.dart'; | ||
``` | ||
|
||
### Infinite scrolling | ||
|
||
Infinite scrolling is the concept of continuously loading more data from a database | ||
as the user scrolls through your application. This is useful when you have a large | ||
datasets, as it enables the application to render faster as well as reducing network | ||
overhead for data the user might never see. | ||
|
||
Firebase UI for Realtime Database provides a convenient way to implement infinite scrolling | ||
using the Realtime Database database with the `FirebaseDatabaseListView` widget. | ||
|
||
At a minimum, the widget accepts a Realtime Database query and an item builder. As the user scrolls | ||
down (or across) your list, more data will be automatically fetched from the database (whilst | ||
respecting query conditions such as ordering). | ||
|
||
To get started, create a query and provide an item builder. For this example, we'll display | ||
a list of users from the `users` collection: | ||
|
||
```dart | ||
final usersQuery = FirebaseDatabase.instance.ref('users').orderByChild('name'); | ||
FirebaseDatabaseListView( | ||
query: usersQuery, | ||
itemBuilder: (context, snapshot) { | ||
Map<String, dynamic> user = snapshot.value as Map<String, dynamic>; | ||
return Text('User name is ${user['name']}'); | ||
}, | ||
); | ||
``` | ||
|
||
The `FirebaseDatabaseListView` widget is built on-top of Flutter's own [`ListView`](https://api.flutter.dev/flutter/widgets/ListView-class.html) | ||
widget, and accepts the same parameters which we can optionally provide. For example, to change the scroll-direction to horizontal: | ||
|
||
```dart | ||
FirebaseDatabaseListView( | ||
scrollDirection: Axis.horizontal, | ||
// ... | ||
); | ||
``` | ||
|
||
### Controlling page size | ||
|
||
By default, the widget will fetch 10 items from the collection at a time. This can be changed by providing a `pageSize` parameter: | ||
|
||
```dart | ||
FirebaseDatabaseListView( | ||
pageSize: 20, | ||
// ... | ||
); | ||
``` | ||
|
||
In general, it is good practice to keep this value as small as possible to reduce network overhead. If the height (or width) | ||
of an individual item is large, it is recommended to lower the page size. | ||
|
||
### Loading and error handling | ||
|
||
By default, the widget will display a loading indicator while data is being fetched from the database, and ignore any errors which might be thrown | ||
(such as permission denied). You can override this behavior by providing a `loadingBuilder` and `errorBuilder` parameters to the widget: | ||
|
||
```dart | ||
FirebaseDatabaseListView( | ||
loadingBuilder: (context) => MyCustomLoadingIndicator(), | ||
errorBuilder: (context, error, stackTrace) => MyCustomError(error, stackTrace), | ||
// ... | ||
); | ||
``` | ||
|
||
### Advanced configuration | ||
|
||
In many cases, the `FirebaseDatabaseListView` widget is enough to render simple lists of collection data. | ||
However, you may have specific requirements which require more control over the widget's behavior | ||
(such as using a [`GridView`](https://api.flutter.dev/flutter/widgets/GridView-class.html)). | ||
|
||
The `FirebaseDatabaseQueryBuilder` provides the building blocks for advanced configuration at the expense of | ||
requiring more boilerplate code. The widget does not provide any underlying list implementation, instead | ||
you are expected to provide this yourself. | ||
|
||
Much like the `FirebaseDatabaseListView` widget, provide a query and builder: | ||
|
||
```dart | ||
final usersQuery = FirebaseDatabase.instance.ref('users').orderByChild('name'); | ||
FirebaseDatabaseQueryBuilder( | ||
query: usersQuery, | ||
builder: (context, snapshot, _) { | ||
// ... TODO! | ||
}, | ||
); | ||
``` | ||
|
||
The main difference to note here is that the `builder` property returns a `FirebaseQueryBuilderSnapshot`, rather | ||
than an individual document. The builder returns the current state of the entire query, such as whether | ||
data is loading, an error has occurred and the documents. | ||
|
||
This requires us to implement our own list based implementation. Firstly, let's handle the loading and error | ||
states: | ||
|
||
```dart | ||
FirebaseDatabaseQueryBuilder( | ||
query: usersQuery, | ||
builder: (context, snapshot, _) { | ||
if (snapshot.isFetching) { | ||
return const CircularProgressIndicator(); | ||
} | ||
if (snapshot.hasError) { | ||
return Text('Something went wrong! ${snapshot.error}'); | ||
} | ||
// ... | ||
}, | ||
); | ||
``` | ||
|
||
Next, we now need to return a list-view based implementation for our application to display the data. For example, | ||
to display a grid of users, we can use the [`GridView`](https://api.flutter.dev/flutter/widgets/GridView-class.html) widget: | ||
|
||
```dart | ||
FirebaseDatabaseQueryBuilder( | ||
query: usersQuery, | ||
builder: (context, snapshot, _) { | ||
// ... | ||
return GridView.builder( | ||
itemCount: snapshot.docs.length, | ||
itemBuilder: (context, index) { | ||
// if we reached the end of the currently obtained items, we try to | ||
// obtain more items | ||
if (snapshot.hasMore && index + 1 == snapshot.docs.length) { | ||
// Tell FirebaseDatabaseQueryBuilder to try to obtain more items. | ||
// It is safe to call this function from within the build method. | ||
snapshot.fetchMore(); | ||
} | ||
final user = snapshot.docs[index].value as Map<String, dynamic>; | ||
return Container( | ||
padding: const EdgeInsets.all(8), | ||
color: Colors.teal[100], | ||
child: const Text("User name is ${user['name']}"), | ||
); | ||
}, | ||
); | ||
}, | ||
); | ||
``` | ||
|
||
With more power comes more responsibility: | ||
|
||
1. Within the `itemBuilder` of our `GridView`, we have to manually ensure that we call the `fetchMore()` method on the snapshot when more data is required. | ||
1. The `FirebaseDatabaseQueryBuilder` does not provide a list-view based handler, instead you must provide your own implementation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
include: package:flutter_lints/flutter.yaml | ||
|
||
# Additional information about this file can be found at | ||
# https://dart.dev/guides/language/analysis-options |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
# Miscellaneous | ||
*.class | ||
*.log | ||
*.pyc | ||
*.swp | ||
.DS_Store | ||
.atom/ | ||
.buildlog/ | ||
.history | ||
.svn/ | ||
migrate_working_dir/ | ||
|
||
# IntelliJ related | ||
*.iml | ||
*.ipr | ||
*.iws | ||
.idea/ | ||
|
||
# The .vscode folder contains launch configuration and tasks you configure in | ||
# VS Code which you may wish to be included in version control, so this line | ||
# is commented out by default. | ||
#.vscode/ | ||
|
||
# Flutter/Dart/Pub related | ||
**/doc/api/ | ||
**/ios/Flutter/.last_build_id | ||
.dart_tool/ | ||
.flutter-plugins | ||
.flutter-plugins-dependencies | ||
.packages | ||
.pub-cache/ | ||
.pub/ | ||
/build/ | ||
|
||
# Web related | ||
lib/generated_plugin_registrant.dart | ||
|
||
# Symbolication related | ||
app.*.symbols | ||
|
||
# Obfuscation related | ||
app.*.map.json | ||
|
||
# Android Studio will place build artifacts here | ||
/android/app/debug | ||
/android/app/profile | ||
/android/app/release |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
# This file tracks properties of this Flutter project. | ||
# Used by Flutter tool to assess capabilities and perform upgrades etc. | ||
# | ||
# This file should be version controlled. | ||
|
||
version: | ||
revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
channel: stable | ||
|
||
project_type: app | ||
|
||
# Tracks metadata for the flutter migrate command | ||
migration: | ||
platforms: | ||
- platform: root | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: android | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: ios | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: linux | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: macos | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: web | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
- platform: windows | ||
create_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
base_revision: f1875d570e39de09040c8f79aa13cc56baab8db1 | ||
|
||
# User provided section | ||
|
||
# List of Local paths (relative to this file) that should be | ||
# ignored by the migrate tool. | ||
# | ||
# Files that are not part of the templates will be ignored by default. | ||
unmanaged_files: | ||
- 'lib/main.dart' | ||
- 'ios/Runner.xcodeproj/project.pbxproj' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
# firebase_ui_database_example | ||
|
||
A new Flutter project. | ||
|
||
## Getting Started | ||
|
||
This project is a starting point for a Flutter application. | ||
|
||
A few resources to get you started if this is your first Flutter project: | ||
|
||
- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) | ||
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) | ||
|
||
For help getting started with Flutter development, view the | ||
[online documentation](https://docs.flutter.dev/), which offers tutorials, | ||
samples, guidance on mobile development, and a full API reference. |
29 changes: 29 additions & 0 deletions
29
packages/firebase_ui_database/example/analysis_options.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
# This file configures the analyzer, which statically analyzes Dart code to | ||
# check for errors, warnings, and lints. | ||
# | ||
# The issues identified by the analyzer are surfaced in the UI of Dart-enabled | ||
# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be | ||
# invoked from the command line by running `flutter analyze`. | ||
|
||
# The following line activates a set of recommended lints for Flutter apps, | ||
# packages, and plugins designed to encourage good coding practices. | ||
include: package:flutter_lints/flutter.yaml | ||
|
||
linter: | ||
# The lint rules applied to this project can be customized in the | ||
# section below to disable rules from the `package:flutter_lints/flutter.yaml` | ||
# included above or to enable additional rules. A list of all available lints | ||
# and their documentation is published at | ||
# https://dart-lang.github.io/linter/lints/index.html. | ||
# | ||
# Instead of disabling a lint rule for the entire project in the | ||
# section below, it can also be suppressed for a single line of code | ||
# or a specific dart file by using the `// ignore: name_of_lint` and | ||
# `// ignore_for_file: name_of_lint` syntax on the line or in the file | ||
# producing the lint. | ||
rules: | ||
# avoid_print: false # Uncomment to disable the `avoid_print` rule | ||
# prefer_single_quotes: true # Uncomment to enable the `prefer_single_quotes` rule | ||
|
||
# Additional information about this file can be found at | ||
# https://dart.dev/guides/language/analysis-options |
Oops, something went wrong.