Merge pull request #126 from FlutterFlow/pooja/generated-code-1

Generated Code - Models & FFAppState

Author: pinkeshmars

docs/ff-concepts/adding-customization/custom-actions.md

@@ -72,15 +72,15 @@ app's `HomePage`.
 In our previous example, we enabled the **Return Value** of the Custom Action to return a
 `List<Product>` when the search keyword is valid. With this change the code will change from
 
-```
+```js
 Future executeSearch(String searchItem) async {
   // Add your function code here!
 }
 ```
 
 to
 
-```
+```js
 Future<List<ProductStruct>> executeSearch(String searchItem) async {
 // Add your function code here!
 }

docs/ff-concepts/adding-customization/custom-files.md

@@ -40,7 +40,7 @@ To do so, you can edit *main.dart* file by following the steps below:
    dart` file. For this 
    example, here's code in a custom action named 'setStatusbarColor'.
 
-```dart
+```js
 // Automatic FlutterFlow imports
 import '/backend/backend.dart';
 import '/flutter_flow/flutter_flow_theme.dart';
@@ -88,7 +88,7 @@ You might want to lock the device orientation in portrait or landscape mode to p
 To set the device orientation in landscape-only mode, [create a custom action](custom-actions.md) with the 
 following code and [add it to a `main.dart`](#edit-maindart) file.
 
-```dart
+```js
 // Automatic FlutterFlow imports
 import '/backend/backend.dart';
 import '/flutter_flow/flutter_flow_theme.dart';
@@ -123,7 +123,7 @@ If you want to ensure that your app appropriately manages its lifecycle and hand
 To do so, [create a custom action](custom-actions.md) with the following code and [add it to a `main.dart`](#edit-maindart) file.
 
 
-```dart
+```js
 // Automatic FlutterFlow imports
 import '/backend/backend.dart';
 import '/flutter_flow/flutter_flow_theme.dart';
@@ -136,21 +136,22 @@ import 'package:flutter/material.dart';
 
 Future onAppBackground() async {
 // Add your function code here!
-WidgetsBinding.instance.addObserver(AppLifecycleObserver());
+   WidgetsBinding.instance.addObserver(AppLifecycleObserver());
 }
 
 class AppLifecycleObserver with WidgetsBindingObserver {
 @override
-void didChangeAppLifecycleState(AppLifecycleState state) {
-if (state == AppLifecycleState.resumed) {
+   void didChangeAppLifecycleState(AppLifecycleState state) {
+      if (state == AppLifecycleState.resumed) {
 // Do something when app is resumed
-print('App is in foreground');
-} else if (state == AppLifecycleState.paused) {
+         print('App is in foreground');
+      } else if (state == AppLifecycleState.paused) {
 // Do something when app is paused
-print('App is in background');
-}
-}
+         print('App is in background');
+      }
+   }
 }
+
 ```
 <figure>
     ![img_5.png](imgs/img_5.png)

docs/generated-code/directory-structure.md

@@ -0,0 +1,128 @@
+---
+title: Directory Structure 
+slug: /generated-code/project-structure
+sidebar_position: 1
+---
+
+# Directory Structure
+
+When you download the code generated by FlutterFlow, you'll notice many additional files and folders beyond what you see in FlutterFlow's Code Viewer. These files make up the complete project structure, organized according to a specific architecture. Understanding this structure is like having a detailed map, guiding you through the code and making it easier to navigate and customize your FlutterFlow project later. So, let's dive in and explore this directory structure.
+
+## Folder Structure
+
+```
+assets/
+lib/
+- actions/actions.dart
+- auth/
+    - firebase_auth/
+    - auth_manager.dart
+    - base_auth_user_provider.dart
+- backend/
+    - api_requests/
+        - api_calls.dart
+        - api_manager.dart
+        - get_streamed_response.dart
+    - cloud_functions/
+    - firebase/
+    - firebase_dynamic_links/firebase_dynamic_links.dart
+    - supabase/
+    - schema/
+        - enums/enums.dart
+        - structs/
+            - address_struct.dart
+            - cart_struct.dart
+            - ...
+        - util/
+            - firestore_util.dart
+            - schema_util.dart
+        - carts_record.dart 
+        - ...
+        - index.dart
+    - backend.dart
+- pages/ ---// empty in this project
+- cart/
+    - cart_counter/
+        - cart_counter_model.dart
+        - cart_counter_widget.dart
+    ...
+- components/
+    - square_leading_model.dart
+    - square_leading_widget.dart
+    - styled_button_model.dart
+    - styled_button_widget.dart
+- custom_code/
+    - actions/
+        - execute_search.dart
+        ...
+- flutter_flow/  ---//FF generated files
+    - custom_functions.dart
+    - flutter_flow_animations.dart
+    - flutter_flow_....dart
+    - nav/
+- app_constants.dart
+- app_state.dart
+- index.dart
+- main.dart
+pubspec.yaml
+```
+### Pages & Components
+
+FlutterFlow follows a layer-first approach to keep your app organized as it grows. Authentication and backend methods are neatly organized into their own sections **[auth](#auth)** and **[backend](#backend)**. Each page you create in FlutterFlow will generate its own folder, containing the `widget` file and the corresponding `model` file. Shared components are placed in subfolders under `components/`.
+
+If you've created nested folders in the FlutterFlow UI, these will directly translate into corresponding folders in the exported code. This gives you even more control to group and organize different features as you like. For instance, you could have separate folders for `products`, `user profile`, and `orders`. In the example above, `cart` is a folder explicitly created to hold all cart related pages and components.
+
+### assets/
+The assets/ directory is where you store static files that your app uses, such as images, fonts, and other resources. These files can be accessed in your code through asset paths and are bundled with your app when it's built.
+
+### lib/
+The `lib/` directory contains all the Dart code that drives your Flutter app. This is where the main structure of your application resides. It's organized into several subdirectories to keep the codebase clean and manageable:
+
+### actions/
+The actions folder contains app-level **Action Blocks**. Each Action Block is created as a separate function within this directory. For example, in the case of eCommerce demo app, the `addToWishlist` function is an app-level Action Block that is included in the `actions.dart` file.
+
+```dart
+Future addToWishlist(
+    BuildContext context, {
+        required String? productId}) async {
+    // Add productId to wishlist object
+    FFAppState().addToLocalWishlist(productId!);
+    FFAppState().update(() {});
+}
+```
+
+### auth/
+Contains files and folders related to authentication logic, including integrations with Firebase or other authentication services.
+
+### backend/
+The `backend/` directory is responsible for handling all the backend logic and integrations for your Flutter app. This includes API requests, cloud functions, database interactions, and managing data schemas. Each subdirectory within backend/ serves a specific purpose:
+
+- **api_requests/**: The api_requests/ directory handles all communication between your app and external services via APIs. It centralizes and organizes the code for making and managing HTTP requests and responses.
+
+- **cloud_functions/**: This directory is used to store functions that interact with cloud-based services, such as Firebase Cloud Functions. These functions are used for operations that need to be performed on the server side, such as complex calculations, data processing, or sending notifications.
+
+- **schema/**: The schema/ directory is crucial for defining the structure of data used throughout your app. It contains the following subdirectories and files:
+  - **enums/:** Stores enumeration types used across the app. 
+  - **structs/:** These are used to represent custom data types like `Address` or `Cart`. 
+  - **util/:** Contains utility functions like `firestore_util.dart` and `schema_util.dart`.
+
+### custom_code/
+Stores custom Dart code that doesn’t fit within the standard FlutterFlow structure. This could include unique actions, widgets, or other custom functionalities.
+
+### flutter_flow/
+This directory is generated by FlutterFlow and contains various utility files that support the app's operation, such as custom functions, generated themes, and navigation. 
+
+### app_constants.dart
+This class is used to store constant values that are used throughout the application.
+
+### app_state.dart
+This file is responsible for managing the app states created in the FlutterFlow app.
+
+### main.dart
+The primary entry point of the app. This file runs the Flutter app and sets up the initial configuration, such as setting the home page and initializing the app’s state.
+
+### pubspec.yaml
+This file is the configuration file for your Flutter project. It defines the dependencies, assets, and other project settings. It also specifies which versions of Dart and Flutter your project uses, along with any third-party packages or plugins your app relies on.
+
+
+This structure makes it easier to manage and scale your app!

docs/generated-code/ff-app-state.md

@@ -0,0 +1,153 @@
+---
+title: FFAppState
+---
+
+# FFAppState
+
+The `FFAppState` class in FlutterFlow acts as a central hub for managing the application's global state. It's designed as a singleton, meaning there's only one instance of this class throughout the app's lifecycle. This class extends [**ChangeNotifier**](https://api.flutter.dev/flutter/foundation/ChangeNotifier-class.html), allowing widgets to listen and react to state changes.
+
+It includes methods for initializing and updating the app's persisted state and also defines various state variables with corresponding getters and setters for manipulating these values.
+
+Here is a basic template of the class, taken from the eCommerce app's generated code:
+
+```js
+class FFAppState extends ChangeNotifier {
+  static FFAppState _instance = FFAppState._internal();
+
+  factory FFAppState() {
+    return _instance;
+  }
+
+  FFAppState._internal();
+
+  static void reset() {
+    _instance = FFAppState._internal();
+  }
+
+  void update(VoidCallback callback) {
+    callback();
+    notifyListeners();
+  }
+
+   // App State variable of primitive type with a getter and setter
+    bool _enableDarkMode = false;
+
+    bool get enableDarkMode => _enableDarkMode;
+
+    set enableDarkMode(bool value) {
+    _enableDarkMode = value;
+   }
+
+}
+```
+
+The `_enableDarkMode` is an App State variable created by developer that creates its own corresponding getter and setter. 
+
+## Updating FFAppState
+When updating the FFAppState from the Action Flow Editor, you will be presented with several **[update type](../resources/data-representation/app-state.md#update-type)** options such as **Rebuild All Pages**, **Rebuild Current Page**, and **No Rebuild**. Let's see how the generated code changes when these options are selected.
+
+### Rebuild Current Page
+When a developer chooses to update App State with the update type set to **Rebuild Current Page**, the corresponding `setter` is called. Immediately after, `setState((){});` is invoked, which updates only the current page. 
+
+Here's an example of the generated code when we update the App State `enableDarkMode` in the `onInitialization` action trigger of the `ProductListPage`.
+
+```js
+SchedulerBinding.instance.addPostFrameCallback((_) async {
+  FFAppState().enableDarkMode = !(FFAppState().enableDarkMode ?? true);
+  setState(() {});
+});
+```
+
+### Rebuild All Pages
+
+In this case, the update type is set to **Rebuild All Pages**, meaning that the `setter` is called, followed by the `update()` method. This method internally calls `notifyListeners()`, which is crucial for updating any widgets that depend on this variable.
+
+```js
+SchedulerBinding.instance.addPostFrameCallback((_) async {
+  FFAppState().enableDarkMode = !(FFAppState().enableDarkMode ?? true);
+  FFAppState().update(() {});
+});
+```
+
+:::tip[Updating App State from Custom Code]
+When updating App State variables from custom code, such as Custom Actions, it's crucial to call the update function to ensure that the changes are reflected across all pages. For example, you should use:
+
+```js
+FFAppState().update(() => FFAppState().enableDarkMode = !(FFAppState().enableDarkMode ?? true));
+```
+:::
+
+### No Rebuild
+Only the setter is called with no setState or update method invoked afterward. This means that only the variable is updated, with no state changes occurring after the data update.
+
+## watch\<FFAppState\>
+
+When you add an [**Update App State**](../resources/data-representation/app-state.md#update-app-state-action) action via the Action Flow Editor, the corresponding pages will include this line within the build method:
+
+```js
+ @override
+Widget build(BuildContext context) {
+    context.watch<FFAppState>();
+    ...
+```
+By using `context.watch<FFAppState>()`, the widget effectively subscribes to any changes in the `FFAppState` class. Whenever there's a change in the `FFAppState` object, this widget automatically rebuilds to reflect those changes. This ensures that your widget always displays the most current data and state of the app, maintaining an up-to-date and responsive user interface.
+
+## Managing AppState\<List\>
+When you add an App State variable of `List` type in FlutterFlow, several utility functions are automatically generated to help you manage this list. These functions include a getter, a setter, and methods for adding, removing, and updating items in the list. This setup ensures that you can easily interact with the list while keeping the app state consistent and responsive. Below is an explanation of these generated functions using the specific example of a LatLngList.
+
+```js
+
+late LoggableList<LatLng> _LatLngList =
+    LoggableList([LatLng(37.4071594, -122.0775312), LatLng(40.7358633, -73.9910835)]);
+
+List<LatLng> get LatLngList => _LatLngList?..logger = () => debugLogAppState(this);
+
+set LatLngList(List<LatLng> value) {
+    if (value != null) {
+        _LatLngList = LoggableList(value);
+    }
+
+    debugLogAppState(this);
+}
+
+void addToLatLngList(LatLng value) {
+    LatLngList.add(value);
+}
+
+void removeFromLatLngList(LatLng value) {
+    LatLngList.remove(value);
+}
+
+void removeAtIndexFromLatLngList(int index) {
+    LatLngList.removeAt(index);
+}
+
+void updateLatLngListAtIndex(
+    int index,
+    LatLng Function(LatLng) updateFn,
+) {
+    LatLngList[index] = updateFn(_LatLngList[index]);
+}
+
+void insertAtIndexInLatLngList(int index, LatLng value) {
+    LatLngList.insert(index, value);
+}
+```
+
+These functions are automatically generated to provide a convenient and consistent way to manage list-type App State variables, making it easier to maintain the app's state:
+
+- The list `LatLngList` is initialized as a private variable `_LatLngList` of type `LoggableList`, which helps in managing the list with additional logging capabilities.
+- The get `LatLngList` method allows other parts of the app to access the `LatLngList`.
+- The set `LatLngList` method allows you to replace the entire `LatLngList` with a new one. When a new list is assigned, it updates the private variable `_LatLngList` and logs this change using `debugLogAppState`.
+- The `addToLatLngList` function appends a new `LatLng` object to the LatLngList, dynamically updating the list as the app runs.
+- The `removeFromLatLngList` function removes a specific `LatLng` object from the `LatLngList`, ensuring the list remains accurate and up-to-date.
+- The `removeAtIndexFromLatLngList` function removes a `LatLng` object from the list based on its index position.
+- The `updateLatLngListAtIndex` function allows you to update a `LatLng` object at a specific index by applying an update function (`updateFn`) to it.
+- The `insertAtIndexInLatLngList` function inserts a new `LatLng` object into the `LatLngList` at a specific index, shifting the existing items as necessary.
+
+
+
+
+:::info[How to create App State variables]
+To learn more about creating and using App State variables in FlutterFlow's UI, check out the[ **App State**](../resources/data-representation/app-state.md) guide.
+:::