Merge pull request #316 from objectbox/flutter-init-store-once

Examples: init store in main, access through provider class

Author: greenrobot-team

objectbox/example/README.md

@@ -59,27 +59,48 @@ Creating a store
 
 ### Flutter apps
 
+For example, open the `Store` in a small helper class like this:
+
 ```dart
 import 'objectbox.g.dart'; // created by `flutter pub run build_runner build`
 
-class _MyHomePageState extends State<MyHomePage> {
-  Store? _store;
-
-  @override
-  void initState() {
-    super.initState();
+class ObjectBox {
+  /// The Store of this app.
+  late final Store store;
+  
+  ObjectBox._create(this.store) {
+    // Add any additional setup code, e.g. build queries.
+  }
 
+  /// Create an instance of ObjectBox to use throughout the app.
+  static Future<ObjectBox> create() async {
     // Future<Store> openStore() {...} is defined in the generated objectbox.g.dart
-    openStore().then((Store store) {
-      _store = store;
-    });
+    final store = await openStore();
+    return ObjectBox._create(store);
   }
 }
 ```
 
-See [Flutter: read & write files](https://flutter.dev/docs/cookbook/persistence/reading-writing-files) for more info.
-If you didn't specify this path to ObjectBox, it would try to use a default directory "objectbox" in the current working
-directory, but it doesn't have permissions to write there: `failed to create store: 10199 Dir does not exist: objectbox (30)`.
+The best time to create the ObjectBox class is when your app starts. 
+We suggest to do it in your app's `main()` function:
+
+```dart
+/// Provides access to the ObjectBox Store throughout the app.
+late ObjectBox objectbox;
+
+Future<void> main() async {
+  // This is required so ObjectBox can get the application directory
+  // to store the database in.
+  WidgetsFlutterBinding.ensureInitialized();
+
+  objectbox = await ObjectBox.create();
+
+  runApp(MyApp());
+}
+```
+
+Then the `Store` remains open throughout the lifetime of the app. 
+This is typically fine and recommended for most use cases.
 
 ### Dart CLI apps
 

objectbox/example/flutter/objectbox_demo/lib/main.dart

@@ -1,29 +1,25 @@
 import 'dart:async';
 
 import 'package:flutter/material.dart';
-import 'package:intl/intl.dart';
-import 'package:objectbox/objectbox.dart';
 
-import 'objectbox.g.dart';
+import 'model.dart';
+import 'objectbox.dart';
 
 // ignore_for_file: public_member_api_docs
 
-@Entity()
-class Note {
-  int id;
+/// Provides access to the ObjectBox Store throughout the app.
+late ObjectBox objectbox;
 
-  String text;
-  String? comment;
-  DateTime date;
+Future<void> main() async {
+  // This is required so ObjectBox can get the application directory
+  // to store the database in.
+  WidgetsFlutterBinding.ensureInitialized();
 
-  Note(this.text, {this.id = 0, this.comment, DateTime? date})
-      : date = date ?? DateTime.now();
+  objectbox = await ObjectBox.create();
 
-  String get dateFormat => DateFormat('dd.MM.yyyy hh:mm:ss').format(date);
+  runApp(MyApp());
 }
 
-void main() => runApp(const MyApp());
-
 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);
 
@@ -44,60 +40,35 @@ class MyHomePage extends StatefulWidget {
   _MyHomePageState createState() => _MyHomePageState();
 }
 
-class ViewModel {
-  final Store _store;
-  final Box<Note> _box;
-  late final Stream<Query<Note>> _queryStream;
-
-  ViewModel(this._store) : _box = Box<Note>(_store) {
-    final qBuilder = _box.query()..order(Note_.date, flags: Order.descending);
-    _queryStream = qBuilder.watch(triggerImmediately: true);
-  }
-
-  void addNote(Note note) => _box.put(note);
-
-  void removeNote(Note note) => _box.remove(note.id);
-
-  void dispose() {
-    _store.close();
-  }
-}
-
 class _MyHomePageState extends State<MyHomePage> {
   final _noteInputController = TextEditingController();
   final _listController = StreamController<List<Note>>(sync: true);
-  late final ViewModel _vm;
 
   void _addNote() {
     if (_noteInputController.text.isEmpty) return;
-    _vm.addNote(Note(_noteInputController.text));
+    objectbox.noteBox.put(Note(_noteInputController.text));
     _noteInputController.text = '';
   }
 
   @override
   void initState() {
     super.initState();
 
-    openStore().then((Store store) {
-      _vm = ViewModel(store);
-
-      setState(() {});
+    setState(() {});
 
-      _listController.addStream(_vm._queryStream.map((q) => q.find()));
-    });
+    _listController.addStream(objectbox.queryStream.map((q) => q.find()));
   }
 
   @override
   void dispose() {
     _noteInputController.dispose();
     _listController.close();
-    _vm.dispose();
     super.dispose();
   }
 
   GestureDetector Function(BuildContext, int) _itemBuilder(List<Note> notes) =>
       (BuildContext context, int index) => GestureDetector(
-            onTap: () => _vm.removeNote(notes[index]),
+            onTap: () => objectbox.noteBox.remove(notes[index].id),
             child: Row(
               children: <Widget>[
                 Expanded(

objectbox/example/flutter/objectbox_demo/lib/model.dart

@@ -0,0 +1,22 @@
+import 'package:intl/intl.dart';
+import 'package:objectbox/objectbox.dart';
+
+import 'objectbox.g.dart';
+
+// ignore_for_file: public_member_api_docs
+
+@Entity()
+class Note {
+  int id;
+
+  String text;
+  String? comment;
+
+  /// Note: Stored in milliseconds without time zone info.
+  DateTime date;
+
+  Note(this.text, {this.id = 0, this.comment, DateTime? date})
+      : date = date ?? DateTime.now();
+
+  String get dateFormat => DateFormat('dd.MM.yyyy hh:mm:ss').format(date);
+}

objectbox/example/flutter/objectbox_demo/lib/objectbox.dart

@@ -0,0 +1,45 @@
+import 'model.dart';
+import 'objectbox.g.dart'; // created by `flutter pub run build_runner build`
+
+/// Provides access to the ObjectBox Store throughout the app.
+///
+/// Create this in the apps main function.
+class ObjectBox {
+  /// The Store of this app.
+  late final Store store;
+
+  /// A Box of notes.
+  late final Box<Note> noteBox;
+
+  /// A stream of all notes ordered by date.
+  late final Stream<Query<Note>> queryStream;
+
+  ObjectBox._create(this.store) {
+    noteBox = Box<Note>(store);
+
+    final qBuilder = noteBox.query()
+      ..order(Note_.date, flags: Order.descending);
+    queryStream = qBuilder.watch(triggerImmediately: true);
+
+    // Add some demo data if the box is empty.
+    if (noteBox.isEmpty()) {
+      _putDemoData();
+    }
+  }
+
+  /// Create an instance of ObjectBox to use throughout the app.
+  static Future<ObjectBox> create() async {
+    // Future<Store> openStore() {...} is defined in the generated objectbox.g.dart
+    final store = await openStore();
+    return ObjectBox._create(store);
+  }
+
+  void _putDemoData() {
+    final demoNotes = [
+      Note('Quickly add a note by writing text and pressing Enter'),
+      Note('Delete notes by tapping on one'),
+      Note('Write a demo app for ObjectBox')
+    ];
+    noteBox.putMany(demoNotes);
+  }
+}

objectbox/example/flutter/objectbox_demo_sync/lib/main.dart

@@ -1,32 +1,25 @@
 import 'dart:async';
-import 'dart:io';
 
 import 'package:flutter/material.dart';
-import 'package:intl/intl.dart';
-import 'package:objectbox/objectbox.dart';
-import 'package:objectbox_sync_flutter_libs/objectbox_sync_flutter_libs.dart';
 
-import 'objectbox.g.dart';
+import 'model.dart';
+import 'objectbox.dart';
 
 // ignore_for_file: public_member_api_docs
 
-@Entity()
-@Sync()
-class Note {
-  int id;
+/// Provides access to the ObjectBox Store throughout the app.
+late ObjectBox objectbox;
 
-  String text;
-  String? comment;
-  DateTime date;
+Future<void> main() async {
+  // This is required so ObjectBox can get the application directory
+  // to store the database in.
+  WidgetsFlutterBinding.ensureInitialized();
 
-  Note(this.text, {this.id = 0, this.comment, DateTime? date})
-      : date = date ?? DateTime.now();
+  objectbox = await ObjectBox.create();
 
-  String get dateFormat => DateFormat('dd.MM.yyyy hh:mm:ss').format(date);
+  runApp(MyApp());
 }
 
-void main() => runApp(const MyApp());
-
 class MyApp extends StatelessWidget {
   const MyApp({Key? key}) : super(key: key);
 
@@ -47,74 +40,35 @@ class MyHomePage extends StatefulWidget {
   _MyHomePageState createState() => _MyHomePageState();
 }
 
-class ViewModel {
-  final Store _store;
-  late final Box<Note> _box;
-  late final Stream<Query<Note>> _queryStream;
-
-  ViewModel(Directory dir)
-      : _store = Store(getObjectBoxModel(),
-            directory: dir.path + '-sync',
-            macosApplicationGroup: 'objectbox.demo' // replace with a real name
-            ) {
-    _box = Box<Note>(_store);
-    final qBuilder = _box.query()..order(Note_.date, flags: Order.descending);
-    _queryStream = qBuilder.watch(triggerImmediately: true);
-
-    // TODO configure actual sync server address and authentication
-    // For configuration and docs, see objectbox/lib/src/sync.dart
-    // 10.0.2.2 is your host PC if an app is run in an Android emulator.
-    // 127.0.0.1 is your host PC if an app is run in an iOS simulator.
-    final syncServerIp = Platform.isAndroid ? '10.0.2.2' : '127.0.0.1';
-    final syncClient =
-        Sync.client(_store, 'ws://$syncServerIp:9999', SyncCredentials.none());
-    syncClient.start();
-  }
-
-  void addNote(Note note) => _box.put(note);
-
-  void removeNote(Note note) => _box.remove(note.id);
-
-  void dispose() {
-    _store.close();
-  }
-}
-
 class _MyHomePageState extends State<MyHomePage> {
   final _noteInputController = TextEditingController();
   final _listController = StreamController<List<Note>>(sync: true);
-  late final ViewModel _vm;
 
   void _addNote() {
     if (_noteInputController.text.isEmpty) return;
-    _vm.addNote(Note(_noteInputController.text));
+    objectbox.noteBox.put(Note(_noteInputController.text));
     _noteInputController.text = '';
   }
 
   @override
   void initState() {
     super.initState();
 
-    defaultStoreDirectory().then((dir) {
-      _vm = ViewModel(dir);
-
-      setState(() {});
+    setState(() {});
 
-      _listController.addStream(_vm._queryStream.map((q) => q.find()));
-    });
+    _listController.addStream(objectbox.queryStream.map((q) => q.find()));
   }
 
   @override
   void dispose() {
     _noteInputController.dispose();
     _listController.close();
-    _vm.dispose();
     super.dispose();
   }
 
   GestureDetector Function(BuildContext, int) _itemBuilder(List<Note> notes) =>
       (BuildContext context, int index) => GestureDetector(
-            onTap: () => _vm.removeNote(notes[index]),
+            onTap: () => objectbox.noteBox.remove(notes[index].id),
             child: Row(
               children: <Widget>[
                 Expanded(

objectbox/example/flutter/objectbox_demo_sync/lib/model.dart

@@ -0,0 +1,23 @@
+import 'package:intl/intl.dart';
+import 'package:objectbox/objectbox.dart';
+
+import 'objectbox.g.dart';
+
+// ignore_for_file: public_member_api_docs
+
+@Entity()
+@Sync()
+class Note {
+  int id;
+
+  String text;
+  String? comment;
+
+  /// Note: Stored in milliseconds without time zone info.
+  DateTime date;
+
+  Note(this.text, {this.id = 0, this.comment, DateTime? date})
+      : date = date ?? DateTime.now();
+
+  String get dateFormat => DateFormat('dd.MM.yyyy hh:mm:ss').format(date);
+}