From 52da52d737bee11d868d7cd17d82e45390e47019 Mon Sep 17 00:00:00 2001
From: Moshe Dicker <dickermoshe@gmail.com>
Date: Sun, 21 Apr 2024 17:38:38 -0400
Subject: [PATCH] add backref to docs

---
 docs/lib/snippets/dart_api/manager.dart | 74 +++++++++++++++++++------
 docs/pages/docs/Dart API/manager.md     | 12 +++-
 2 files changed, 65 insertions(+), 21 deletions(-)

diff --git a/docs/lib/snippets/dart_api/manager.dart b/docs/lib/snippets/dart_api/manager.dart
index bca3f671..25c73489 100644
--- a/docs/lib/snippets/dart_api/manager.dart
+++ b/docs/lib/snippets/dart_api/manager.dart
@@ -1,6 +1,46 @@
 import 'package:drift/drift.dart';
 
-import '../setup/database.dart';
+part 'manager.g.dart';
+
+class TodoItems extends Table {
+  IntColumn get id => integer().autoIncrement()();
+  TextColumn get title => text().withLength(min: 6, max: 32)();
+  TextColumn get content => text().named('body')();
+  IntColumn get category =>
+      integer().nullable().references(TodoCategory, #id)();
+  DateTimeColumn get createdAt => dateTime().nullable()();
+}
+
+class TodoCategory extends Table {
+  IntColumn get id => integer().autoIncrement()();
+  TextColumn get description => text()();
+}
+
+// #docregion user_group_tables
+
+class Users extends Table {
+  IntColumn get id => integer().autoIncrement()();
+  TextColumn get name => text()();
+  IntColumn get groupId => integer().nullable().references(Groups, #id)();
+}
+
+class Groups extends Table {
+  IntColumn get id => integer().autoIncrement()();
+  TextColumn get name => text()();
+  @ReferenceName("administeredGroups")
+  IntColumn get admin => integer().nullable().references(Users, #id)();
+  @ReferenceName("ownedGroups")
+  IntColumn get owner => integer().references(Users, #id)();
+}
+
+// #enddocregion user_group_tables
+
+@DriftDatabase(tables: [TodoItems, TodoCategory, Groups, Users])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase(super.e);
+  @override
+  int get schemaVersion => 1;
+}
 
 extension ManagerExamples on AppDatabase {
   // #docregion manager_create
@@ -145,7 +185,7 @@ extension ManagerExamples on AppDatabase {
   }
 // #enddocregion manager_filter_forward_references
 
-// #docregion manager_filter_forward_references
+// #docregion manager_filter_back_references
   Future reverseRelationalFilter() async {
     // Get the category that has a todo item with an id of 1
     managers.todoCategory.filter((f) => f.todoItemsRefs((f) => f.id(1)));
@@ -156,7 +196,19 @@ extension ManagerExamples on AppDatabase {
       (f) => f.description("School") | f.todoItemsRefs((f) => f.id(1)),
     );
   }
-// #enddocregion manager_filter_forward_references
+// #enddocregion manager_filter_back_references
+
+// #docregion manager_filter_custom_back_references
+  Future reverseNamedRelationalFilter() async {
+    // Get all users who are administrators of a group with a name containing "Business"
+    // or who own a group with an id of 1, 2, 4, or 5
+    managers.users.filter(
+      (f) =>
+          f.administeredGroups((f) => f.name.contains("Business")) |
+          f.ownedGroups((f) => f.id.isIn([1, 2, 4, 5])),
+    );
+  }
+// #enddocregion manager_filter_custom_back_references
 }
 
 // #docregion manager_filter_extensions
@@ -216,18 +268,4 @@ Future customOrdering(AppDatabase db) async {
   // Use the custom ordering on the `TodoItems` table
   db.managers.todoItems.orderBy((f) => f.contentThenCreatedAt());
 }
-// #enddocregion manager_custom_ordering
-
-// #docregion reference_name_example
-class User extends Table {
-  IntColumn get id => integer().autoIncrement()();
-  TextColumn get name => text()();
-  @ReferenceName("users")
-  IntColumn get group => integer().nullable().references(Group, #id)();
-}
-
-class Group extends Table {
-  IntColumn get id => integer().autoIncrement()();
-  TextColumn get name => text()();
-}
-// #enddocregion reference_name_example
+// #enddocregion manager_custom_ordering
\ No newline at end of file
diff --git a/docs/pages/docs/Dart API/manager.md b/docs/pages/docs/Dart API/manager.md
index 78e8522a..6bf5cfb4 100644
--- a/docs/pages/docs/Dart API/manager.md	
+++ b/docs/pages/docs/Dart API/manager.md	
@@ -48,10 +48,16 @@ You can also filter across back references. This is useful when you have a one-t
 
 {% include "blocks/snippet" snippets = snippets name = 'manager_filter_back_references' %}
 
-The code generator will name this filterset using the name of the table that is being referenced. If there are multiple references to the same table, the code generator will print an error and wont generate the filterset.  
-Use the `@ReferenceName(...)` on the foreign key to specify a custom name for the filterset.
+The code generator will name this filterset using the name of the table that is being referenced. In the above example, the filterset is named `todoItemsRefs`, because the `TodoItems` table is being referenced.
+However, you can also specify a custom name for the filterset using the `@ReferenceName(...)` annotation on the foreign key. This may be necessary if you have multiple references to the same table, take the following example:
 
-{% include "blocks/snippet" snippets = snippets name = 'reference_name_example' %}
+{% include "blocks/snippet" snippets = snippets name = 'user_group_tables' %}
+
+We can now use them in a query like this:
+
+{% include "blocks/snippet" snippets = snippets name = 'manager_filter_custom_back_references' %}
+
+In this example, had we not specified a custom name for the reference, the code generator would have named both filtersets `userRefs` for both references to the `User` table. This would have caused a conflict. By specifying a custom name, we can avoid this issue.
 
 
 ### Ordering