Skip to content

Commit 2902212

Browse files
PoojaB26PoojaB26
committed
Add custom files +common custom code props
1 parent 7c8af6e commit 2902212

File tree

15 files changed

+329
-1
lines changed

15 files changed

+329
-1
lines changed

‎docs/ff-concepts/navigation-routing/_category_.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
{
2-
"label": "Navigation & Routing"
2+
"label": "Navigation & Routing",
3+
"position": 4
34
}

‎docs/ff-concepts/writing-custom-code/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Writing Custom Code",
3+
"position": 6
4+
}

‎docs/ff-concepts/writing-custom-code/custom-files.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Custom Files
3+
sidebar_position: 4
4+
---
5+
# Custom Files
6+
7+
We allow you to add a custom code directly into the `*main.dart*` file of your app. This means that you can easily implement specific functionalities and customize your app as per your requirements without downloading the entire project and manually modifying the file.
8+
9+
By default, the file you want to edit is in 'read-only' mode. However, using our editor, you can add a code snippet in the form of [custom actions](/customizing-your-app/custom-functions/custom-actions).
10+
11+
:::warning[Please note]
12+
You can only add custom actions that have no arguments (including *BuildContext*).
13+
:::
14+
15+
## Edit *main.dart*
16+
17+
The *main.dart* is a critical file in your project, as it serves as the entry point for the application. This file contains the `main()` function, which is responsible for starting the application by running the code that builds the UI and initializes any other necessary components.
18+
19+
You can edit the *main.dart* file to include anything in `main()` function that we don't yet support. For example, initializing third-party plugins or libraries and setting up system-level configurations, such as changing the status bar color or orientation.
20+
21+
Let's see an example of how you can add a code in *main.dart* file to change the status bar color for the mobile app. Here's how it looks:
22+
23+
<figure>
24+
![img_3.png](imgs%2Fimg_3.png)
25+
<figcaption class="centered-caption">Changing the status bar color for the mobile device</figcaption>
26+
</figure>
27+
28+
To do so, you can edit *main.dart* file by following the steps below:
29+
30+
2. Create a [custom action](/customizing-your-app/custom-functions/custom-actions#adding-custom-action) for the code you want to include in a *main.dart* file. For this example, here's code in a custom action named 'setStatusbarColor'.
31+
32+
```dart
33+
// Automatic FlutterFlow imports
34+
import '/backend/backend.dart';
35+
import '/flutter_flow/flutter_flow_theme.dart';
36+
import '/flutter_flow/flutter_flow_util.dart';
37+
import '/custom_code/actions/index.dart'; // Imports other custom actions
38+
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
39+
import 'package:flutter/material.dart';
40+
// Begin custom action code
41+
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!
42+
43+
import 'package:flutter/services.dart';
44+
45+
Future setStatusbarColor() async {
46+
// Add your function code here!
47+
48+
// Set status bar color
49+
SystemChrome.setSystemUIOverlayStyle(
50+
SystemUiOverlayStyle(
51+
statusBarColor: Colors.redAccent, // <-- see here
52+
statusBarIconBrightness:
53+
Brightness.dark, //<-- For Android see here (dark icons)
54+
statusBarBrightness: Brightness.light, //<-- For iOS see here (dark icons)
55+
),
56+
);
57+
}
58+
```
59+
60+
2. Now click on **Custom Functions** from the [*Navigation Menu*](/getting-started/ui-builder/navigation-menu) (left side of your screen) and open the **Custom Files > main.dart**.
61+
5. Determine where to place the code (i.e., **Initial Action** or **Final Action**), click the **+** button, and select the custom action.
62+
8. Click **Save**.
63+
64+
<div class="video-container"><iframe src="https://www.loom.
65+
com/embed/e8e12fad4fce42bba29080f83a1f4b74?sid=3f01f3b7-38f0-4f01-8bec-6442db66fe07" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe></div>
66+
67+
68+
## More examples
69+
70+
Let's see some more examples of adding code to the *main.dart* file to solidify understanding and use it in real-world scenarios.
71+
72+
### Example 1: Lock device orientation
73+
74+
You might want to lock the device orientation in portrait or landscape mode to prevent it from rotating the screen automatically when the user tilts or rotates the device. This is useful in scenarios where the layout of the app is designed to work only in one specific orientation or when you want to ensure that the app is always displayed in a consistent manner.
75+
76+
To set the device orientation in landscape-only mode, [create a custom action](/customizing-your-app/custom-functions/custom-actions#adding-custom-action) with the following code and [add it to a *main.dart*](/customizing-your-app/custom-functions/custom-files#edit-main.dart) file.
77+
78+
```dart
79+
// Automatic FlutterFlow imports
80+
import '/backend/backend.dart';
81+
import '/flutter_flow/flutter_flow_theme.dart';
82+
import '/flutter_flow/flutter_flow_util.dart';
83+
import '/custom_code/actions/index.dart'; // Imports other custom actions
84+
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
85+
import 'package:flutter/material.dart';
86+
// Begin custom action code
87+
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!
88+
89+
import 'package:flutter/services.dart';
90+
91+
Future setLandscapeMode() async {
92+
// Add your function code here!
93+
await SystemChrome.setPreferredOrientations([
94+
DeviceOrientation.landscapeLeft,
95+
DeviceOrientation.landscapeRight,
96+
]);
97+
}
98+
```
99+
100+
<figure>
101+
![img_4.png](imgs%2Fimg_4.png)
102+
<figcaption class="centered-caption">Edit main.dart file to lock the device orientation</figcaption>
103+
</figure>
104+
105+
106+
### Example 2: Getting app lifecycle callback
107+
108+
If you want to ensure that your app appropriately manages its lifecycle and handles any necessary actions when it transitions between different states, such as 'resumed' and 'paused,' you can add the `AppLifecycleObserver` in the *main.dart* file.
109+
110+
To do so, [create a custom action](/customizing-your-app/custom-functions/custom-actions#adding-custom-action) with the following code and [add it to a *main.dart*](/customizing-your-app/custom-functions/custom-files#edit-main.dart) file.
111+
112+
113+
```dart
114+
// Automatic FlutterFlow imports
115+
import '/backend/backend.dart';
116+
import '/flutter_flow/flutter_flow_theme.dart';
117+
import '/flutter_flow/flutter_flow_util.dart';
118+
import '/custom_code/actions/index.dart'; // Imports other custom actions
119+
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
120+
import 'package:flutter/material.dart';
121+
// Begin custom action code
122+
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!
123+
124+
Future onAppBackground() async {
125+
// Add your function code here!
126+
WidgetsBinding.instance.addObserver(AppLifecycleObserver());
127+
}
128+
129+
class AppLifecycleObserver with WidgetsBindingObserver {
130+
@override
131+
void didChangeAppLifecycleState(AppLifecycleState state) {
132+
if (state == AppLifecycleState.resumed) {
133+
// Do something when app is resumed
134+
print('App is in foreground');
135+
} else if (state == AppLifecycleState.paused) {
136+
// Do something when app is paused
137+
print('App is in background');
138+
}
139+
}
140+
}
141+
```
142+
<figure>
143+
![img_5.png](imgs%2Fimg_5.png)
144+
<figcaption class="centered-caption">Edit main.dart file to get lifecycle callback</figcaption>
145+
</figure>

‎docs/ff-concepts/writing-custom-code/customization.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Add Code Customization
3+
sidebar_position: 1
4+
toc_max_heading_level: 4
5+
6+
---
7+
8+
# Code Customization
9+
10+
While FlutterFlow provides a wide range of pre-built components and functionalities, there may be
11+
times when you need to extend your app with custom logic or features that are not readily available.
12+
This
13+
is where writing custom code comes into play. We provide the following features to accommodate
14+
these needs:
15+
16+
* **Custom Functions:** Write custom Dart functions to perform specific tasks or calculations.
17+
* **Custom Actions:** Implement custom actions that can be triggered by user interactions or
18+
other action triggers.
19+
* **Custom Widgets:** Create custom Flutter widgets to achieve unique UI designs or behaviors.
20+
* **Custom Files:** Ability to edit some parts of the `main.dart` file.
21+
22+
:::tip[Why Write Custom Code?]
23+
24+
- **Extend Functionality:** Add features that are not included in the standard FlutterFlow
25+
components.
26+
- **Custom Integrations:** Integrate with third-party packages or APIs / databases that require
27+
specific handling.
28+
- **Unique UI Elements:** Create unique user interface elements that require custom rendering or
29+
interactions.
30+
:::
31+
32+
## Common Properties
33+
34+
There are several properties and settings that are common to each type of custom code in
35+
FlutterFlow. Most of these common properties are highlighted in the diagram below. For more
36+
information about some of these properties, see the details provided below.
37+
38+
![custom-code-common.png](imgs%2Fcustom-code-common.png)
39+
40+
### Code Copilot
41+
42+
Code Copilot is an AI-assisted feature that helps you generate code snippets,
43+
functions, or entire blocks of code based on natural language descriptions of what you want to
44+
achieve. It simplifies the app-building process by allowing you to describe the functionality you
45+
need, such as 'calculate the total price of items in a cart', and then the Copilot generates the
46+
necessary code.
47+
48+
This can significantly speed up the building process and reduce the need for in-depth programming
49+
knowledge, making it especially useful for custom functions and actions.
50+
51+
**Limitation:** The prompts are limited to 100 characters currently.
52+
53+
<div style={{
54+
position: 'relative',
55+
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
56+
height: 0,
57+
width: '100%'
58+
}}>
59+
<iframe
60+
src="https://demo.arcade.software/nHrVL2cgyzjIgoSUu36F?embed&show_copy_link=true"
61+
title=""
62+
style={{
63+
position: 'absolute',
64+
top: 0,
65+
left: 0,
66+
width: '100%',
67+
height: '100%',
68+
colorScheme: 'light'
69+
}}
70+
frameborder="0"
71+
loading="lazy"
72+
webkitAllowFullScreen
73+
mozAllowFullScreen
74+
allowFullScreen
75+
allow="clipboard-write">
76+
</iframe>
77+
</div>
78+
79+
80+
### Compile Code
81+
82+
When you are done adding your code snippets, you can compile it to ensure there are no
83+
compilation errors. To do so, click the **Compile Code** button.
84+
85+
86+
<figure>
87+
![compile-errors.png](imgs%2Fcompile-errors.png)
88+
<figcaption class="centered-caption">How to recognize compile time errors</figcaption>
89+
</figure>
90+
91+
92+
### Code Analyzer
93+
94+
The code analyzer is available in all your custom code snippets and ensures the quality and correctness of your custom code. It automatically checks your Dart code for errors and warnings, providing real-time feedback as you write.
95+
![code-analyzer.png](imgs%2Fcode-analyzer.png)
96+
When there is a compilation error, the code analyzer will stop running and display the errors caught by the compiler. Once fixed, save the code and rerun the Compile Code button. The code analyzer should then be reconnected. You can also manually reconnect it if needed.
97+
98+
### Custom Code Settings
99+
100+
101+
102+
103+
#### Adding a Pub Dependency
104+
105+
:::tip[Scope]
106+
You can only add a pub dependency to Custom Action & Custom Widgets.
107+
:::
108+
109+
If you plan to use a dependency from [*pub.dev*](https://pub.dev/) into a custom widget or action, you must go through the following steps:
110+
111+
1. [Choosing dependency](#1-choosing-dependency)
112+
5. [Copying dependency/package name](#2-copying-dependency-name)
113+
8. [Copying import statement](#3-copying-import-statement)
114+
115+
##### 1. Choosing dependency
116+
117+
You will find varieties of dependencies for a specific requirement, and choosing the best one can be challenging. This section helps you identify the right dependency by examining its score.
118+
119+
When you search for any dependency in *pub.dev*, you will get a list of dependencies. You can filter out the result based on which dependency is more inclined toward your needs. You can do so by opening and checking each dependency manually.
120+
121+
Once you have a handful of dependencies, consider the following factors while choosing the final one.
122+
123+
- **WEB**: It must support Web to run your app in our Run/Test Mode.
124+
- **Likes**: This shows how many developers have liked a dependency.
125+
- **Pub Points**: Tells the quality of the dependency (out of 130) based on code style, platform
126+
support, and maintainability.
127+
- **Popularity**: This metric indicates how many apps use the package. A high popularity score
128+
(out of 100%) can suggest that the package is stable and trusted by many developers.
129+
- **Documentation:** A well-documented package will save you time and reduce ambiguity. Check if
130+
the package has clear usage examples, a comprehensive README, and ideally API documentation.
131+
- **Maintenance & Updates**: Check the last update date. A regularly updated package is more
132+
likely compatible with the latest Dart/Flutter versions and has fewer bugs.
133+
134+
<p></p>
135+
136+
![Dependency-score.png](imgs%2FDependency-score.png)
137+
138+
139+
##### 2. Copying dependency name
140+
To use the dependency code in our code editor, copy its name with the version. To do so, click
141+
the **Copy to Clipboard** icon.
142+
143+
<p></p>
144+
145+
![img.png](imgs%2Fimg.png)
146+
147+
<p></p>
148+
149+
:::warning
150+
The current dependency might depend on other dependencies to work.So make sure you also copy the name and version of all the additional dependencies to specify in the code editor.
151+
:::
152+
153+
You can check if the current dependency has any additional dependencies inside the '*Dependencies'* section at the bottom right side.
154+
155+
![img_1.png](imgs%2Fimg_1.png)
156+
157+
##### 3. Copying import statement
158+
159+
An import statement points to where the dependency's code is located. When making a custom widget or action, place this statement at the beginning of the code editor.
160+
161+
Open the dependency page and select the installing tab; under the Import it section, you'll find
162+
the import statement. To copy, click the **Copy to Clipboard** icon.
163+
164+
![img_2.png](imgs%2Fimg_2.png)
165+
166+
167+
168+
169+
170+

‎docs/ff-concepts/writing-custom-code/imgs/Dependency-score.png

1.32 MB
Loading

‎docs/ff-concepts/writing-custom-code/imgs/code-analyzer.png

124 KB
Loading

‎docs/ff-concepts/writing-custom-code/imgs/compile-errors.png

72.9 KB
Loading

‎docs/ff-concepts/writing-custom-code/imgs/custom-code-common.png

1.31 MB
Loading

‎docs/ff-concepts/writing-custom-code/imgs/img.png

25.2 KB
Loading

‎docs/ff-concepts/writing-custom-code/imgs/img_1.png

84.8 KB
Loading

0 commit comments

Comments
 (0)