Document how to add parameters to notifiers (#3112)

website/docs/essentials/passing_args/codegen/provider.dart

@@ -1,15 +1,32 @@
-import 'dart:convert';
-import 'package:http/http.dart' as http;
+// ignore_for_file: avoid_print
+
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 import '../../first_request/codegen/activity.dart';
 
 // Necessary for code-generation to work
 part 'provider.g.dart';
 
+FutureOr<Activity> fetchActivity() => throw UnimplementedError();
+
 /* SNIPPET START */
+// A "functional" provider
 @riverpod
 Future<Activity> activity(ActivityRef ref) async {
-  final response = await http.get(Uri.https('boredapi.com', '/api/activity'));
-  final json = jsonDecode(response.body) as Map<String, dynamic>;
-  return Activity.fromJson(json);
+  // TODO: perform a network request to fetch an activity
+  return fetchActivity();
+}
+
+// Or alternatively, a "notifier"
+@riverpod
+class ActivityNotifier2 extends _$ActivityNotifier2 {
+  /// Notifier arguments are specified on the build method.
+  /// There can be as many as you want, have any name, and even be optional/named.
+  @override
+  Future<Activity> build(String activityType) async {
+    // Arguments are also available with "this.<argumentName>"
+    print(this.activityType);
+
+    // TODO: perform a network request to fetch an activity
+    return fetchActivity();
+  }
 }

website/docs/essentials/passing_args/raw/family.dart

@@ -1,26 +1,42 @@
-import 'dart:convert';
+// ignore_for_file: unnecessary_this, avoid_print
+
+import 'dart:async';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
-import 'package:http/http.dart' as http;
 import '../../first_request/raw/activity.dart';
 
-/* SNIPPET START */
+FutureOr<Activity> fetchActivity(String activityType) =>
+    throw UnimplementedError();
 
+/* SNIPPET START */
+// A "functional" provider
 final activityProvider = FutureProvider.autoDispose
     // We use the ".family" modifier.
     // The "String" generic type corresponds to the argument type.
     // Our provider now receives an extra argument on top of "ref": the activity type.
     .family<Activity, String>((ref, activityType) async {
-  // We can use the "activityType" argument to build the URL.
-  // This will point to "https://boredapi.com/api/activity?type=<activityType>"
-  final response = await http.get(
-    Uri(
-      scheme: 'https',
-      host: 'boredapi.com',
-      path: '/api/activity',
-      // No need to manually encode the query parameters, the "Uri" class does it for us.
-      queryParameters: {'type': activityType},
-    ),
-  );
-  final json = jsonDecode(response.body) as Map<String, dynamic>;
-  return Activity.fromJson(json);
+  // TODO: perform a network request to fetch an activity using "activityType"
+  return fetchActivity(activityType);
 });
+
+// A "notifier" provider
+final activityProvider2 = AsyncNotifierProvider.autoDispose
+    // Again, we use the ".family" modifier, and specify the argument as type "String".
+    .family<ActivityNotifier, Activity, String>(
+  ActivityNotifier.new,
+);
+
+// When using ".family" with notifiers, we need to change the notifier subclass:
+// AsyncNotifier -> FamilyAsyncNotifier
+// AutoDisposeAsyncNotifier -> AutoDisposeFamilyAsyncNotifier
+class ActivityNotifier
+    extends AutoDisposeFamilyAsyncNotifier<Activity, String> {
+  /// Family arguments are passed to the build method and accessible with this.arg
+  @override
+  Future<Activity> build(String activityType) async {
+    // Arguments are also available with "this.arg"
+    print(this.arg);
+
+    // TODO: perform a network request to fetch an activity
+    return fetchActivity(activityType);
+  }
+}

website/docs/essentials/passing_args/raw/provider.dart

@@ -1,12 +1,26 @@
-import 'dart:convert';
+import 'dart:async';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
-import 'package:http/http.dart' as http;
 import '../../first_request/raw/activity.dart';
 
 /* SNIPPET START */
 
+FutureOr<Activity> fetchActivity() => throw UnimplementedError();
+
+// A "functional" provider
 final activityProvider = FutureProvider.autoDispose((ref) async {
-  final response = await http.get(Uri.https('boredapi.com', '/api/activity'));
-  final json = jsonDecode(response.body) as Map<String, dynamic>;
-  return Activity.fromJson(json);
+  // TODO: perform a network request to fetch an activity
+  return fetchActivity();
 });
+
+// Or alternatively, a "notifier"
+final activityProvider2 = AsyncNotifierProvider<ActivityNotifier, Activity>(
+  ActivityNotifier.new,
+);
+
+class ActivityNotifier extends AsyncNotifier<Activity> {
+  @override
+  Future<Activity> build() async {
+    // TODO: perform a network request to fetch an activity
+    return fetchActivity();
+  }
+}