Skip to content

Commit 3949c1f

Browse files
PoojaB26pinkeshmars
PoojaB26
and
pinkeshmars
authored
User Defined Components Section (#29)
* Add components getting started page * Add component usage & lifecycle info * Add Component State info * Add bit about Themed Widgets * Address comments * Address comments * fixed small typo --------- Co-authored-by: Pinkesh <[email protected]>
1 parent 2f3f7e0 commit 3949c1f

File tree

12 files changed

+739
-2
lines changed

12 files changed

+739
-2
lines changed

‎docs/resources/ui-building-blocks/components/_category_.json

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

‎docs/resources/ui-building-blocks/components/built-in-components/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Built-in Components",
3+
"position": 2
4+
}

‎docs/resources/ui-building-blocks/components/built-in-components/getting-started.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Getting Started
3+
---
4+
5+
# Built-in Components
6+
7+
Built-in components in FlutterFlow are predefined elements designed for various use cases, such as
8+
map functionalities, layouts, and more. These ready-to-use components help streamline development,
9+
allowing you to implement complex features quickly and efficiently.

‎docs/resources/ui-building-blocks/components/overview.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Overview
3+
sidebar_position: 1
4+
---
5+
6+
# Components
7+
8+
Components in FlutterFlow are reusable elements. You design once and utilize throughout your app
9+
to save time, ensure consistency, and simplify maintenance.
10+
11+
Components help in the following ways:
12+
13+
- **Consistency:** Components provide a consistent look and behavior, reducing the likelihood of
14+
discrepancies that can occur when the same UI elements are recreated multiple times.
15+
16+
- **Centralized Updates:** By creating a component once and reusing it across
17+
different parts of your app, you ensure that any design or functionality changes are made in
18+
one place. When that component is updated, all instances of that component across the
19+
app automatically reflect those changes. This significantly reduces the effort required to
20+
maintain and update the app.
21+
22+
:::tip[CLasses vs Instances]
23+
Learn more about **[Classes and their Instances](..%2Foverview.md)** and what they mean in
24+
FlutterFlow.
25+
:::
26+
27+
- **Error Reduction:** Since components reduce design duplication, the risk of errors
28+
decreases. Fixing an issue in a component means it is fixed everywhere, leading to fewer bugs and
29+
inconsistencies.
30+
31+
- **Scalability:** As your app grows, maintaining a DRY codebase through components makes it easier
32+
to scale. Adding new features or modifying existing ones becomes more straightforward and less
33+
prone to introducing errors.
34+
:::tip[DRY PRINCIPLE]
35+
The **DRY (Don't Repeat Yourself)** principle is a software development concept that emphasizes
36+
the
37+
importance of reducing repetition within code and design.
38+
:::
39+
40+
Leveraging components effectively helps you build a consistent, efficient, and maintainable app.
41+
42+
## Types of Components in FlutterFlow
43+
44+
- **[Build-in Components](built-in-components%2Fgetting-started.md):** FlutterFlow
45+
includes a variety of built-in pre-defined widgets that
46+
serve as ready-made components, such as the `CreditCard` or `Signature` widget. These are
47+
out-of-the-box solutions provided by FlutterFlow that can be directly integrated into any project
48+
to offer specific functionalities.
49+
50+
- **[User-Defined Components](user-defined-components/getting-started.md):** You can also build your own
51+
components by assembling
52+
multiple
53+
widgets using FlutterFlow’s drag-and-drop interface. This method involves strategically
54+
positioning atomic widgets such as `TextField`, `Button`s, or `Image`s, etc within the molecular
55+
widgets like `Row`, `Column`, or `Stack` to create a combined widget that serve a specific
56+
function, like a `LoginComponent` or a `SearchBar`.
57+
58+
- **Custom Widgets:** For scenarios where more complex functionalities are required, FlutterFlow
59+
allows you to develop their own Custom Widgets. This involves writing Flutter code from
60+
scratch, offering the highest level of customization and flexibility.
61+
62+
- **Themed Widgets:** Themed widgets can be reused across your app, making it easy to update styles
63+
universally. If you decide to change any properties, such as color schemes or fonts, you can
64+
update the theme widget instead of modifying each widget individually.
65+
66+
## Common Use-cases
67+
68+
Components can be used in various scenarios to accelerate your app development process. Here are
69+
some common use-cases.
70+
71+
- Design a **standard button once** and reuse it across multiple screens to maintain a cohesive
72+
look.
73+
74+
- Utilize components for **card designs** frequently used in your app, such as product cards, user
75+
profiles, or news articles.
76+
77+
- **Standardize input forms** for tasks like user registration, login, or feedback collection,
78+
ensuring
79+
a consistent user experience.
80+
81+
- Design **pop-up messages or dialogs** that match the overall theme of your app, enhancing visual
82+
consistency.
83+
84+
- Build interactive elements such as **custom sliders, ratings, or progress bars**, and use them
85+
across various parts of your app.
86+
87+
- Design sections of a screen that are frequently repeated, such as testimonials, image galleries,
88+
or feature highlights, and reuse them to maintain a cohesive layout.
89+
90+
Here's an example of all the widely used components used in the EcommerceFlow demo app.
91+
// TODO Image will be added once all components are built in project
92+

‎docs/resources/ui-building-blocks/components/user-defined-components/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "User Defined Components",
3+
"position": 3
4+
}

‎docs/resources/ui-building-blocks/components/user-defined-components/component-lifecycle.md

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
title: Component Lifecycle
3+
sidebar_position: 3
4+
toc_max_heading_level: 5
5+
---
6+
7+
# Component Lifecycle
8+
9+
In FlutterFlow, knowing component lifecycle is crucial for managing state and optimizing your
10+
app's performance.
11+
12+
Let's delve into the key moments in the lifecycle of a **Component**:
13+
14+
- **Creation**: Component instances are created dynamically when they are utilized within a page
15+
or another component. This means that component instances are created as needed, which helps in
16+
managing resources efficiently and avoiding unnecessary overhead.
17+
18+
- **Initialization:** Actions defined in the `On Initialization` **Action Trigger** are executed
19+
during this phase. For instance, you can initialize local state variables with initial values, or
20+
start component animations in this phase.
21+
At this stage, component state variables with their default values (if any) are also created.
22+
These variables hold data specific to the component, such as form inputs or toggle states, and are
23+
essential for managing the component’s internal state.
24+
25+
- **Updating:** While in use, the component can receive updated parameters from its parent when
26+
the parent rebuilds itself, allowing the component to adjust its behavior and appearance
27+
accordingly. When updating state variables inside a component, you can choose to rebuild only the
28+
component itself or the entire page containing the given component. This dynamic updating is
29+
crucial for maintaining a responsive and interactive user experience.
30+
31+
- **Disposal:** When the component is no longer needed, such as when a user navigates away
32+
from the page or the component is explicitly removed, it is destroyed.
33+
34+
In FlutterFlow, most of these lifecycle stages are handled internally by FlutterFlow's architecture.
35+
However, we expose some of the methods so that you, as a developer, can decide what additional
36+
configurations to load upon initialization and when to re-render the UI based on interactions.
37+
38+
Let's read more about them in the following sections:
39+
40+
## Initialization Action Triggers
41+
42+
During the initialization of a **Component**, FlutterFlow exposes the `On Initialization` **Action
43+
Trigger** that assist you in loading resources or initializing data when the Component is loaded in
44+
a Page or a Component.
45+
46+
:::info[What are Action Triggers?]
47+
**Action Triggers** serve as event listeners or handlers that respond to
48+
specific events or user interactions within an application. FlutterFlow provides
49+
developers with a way to define logic that responds to various events, such as
50+
button clicks, page loads, form submissions, or data changes.
51+
To learn more, head over to **[Action Flow Editor](#)** section.
52+
:::
53+
54+
As you open the [Action Flow Editor](#) for your Component, you can see the `On Initialization`
55+
**Action Trigger** exposed for your **Component**.
56+
57+
### On Initialization [Action Trigger]
58+
59+
The `On Initialization` action trigger in FlutterFlow allows you to define actions that should occur
60+
when a component loads or initializes, such as setting up necessary data, state variables, or other
61+
initialization tasks.
62+
63+
If the component stops being shown in the UI and then becomes visible again,
64+
the actions under the **On Initialization** action trigger will be re-triggered so any
65+
setup tasks are re-executed. For dynamically generated components, such as those in a ListView with
66+
a query, each instance will trigger the actions under `On Initialization` action trigger when it is
67+
created.
68+
69+
## Component state
70+
71+
:::note[STATE VARIABLES]
72+
A state variable holds information or data about your UI at any given moment. To learn more
73+
about **states and state management, [refer here.](#)**
74+
:::
75+
76+
**Component state** refers to the information that a component tracks about its current condition or
77+
the data it manages internally. This can include data such as whether a button is enabled, the value
78+
of a slider, or the entries in a dynamically updated list. Component state variables are only
79+
accessible within the given component's scope.
80+
81+
This type of variable is particularly useful for storing data that affects how the component behaves
82+
or appears, such as toggling UI elements, keeping track of user choices within the component, or
83+
caching data pertinent to the component's functionality.
84+
85+
For example,
86+
87+
- In a custom drop-down menu component, you might use a component state variable to keep track of
88+
which item is currently selected.
89+
- In a toggle switch component, you could use a component state variable to store the on/off
90+
state based on user interaction.
91+
This approach ensures that the state of the component is maintained as it interacts with the user
92+
or other parts of the application.
93+
94+
When the value of a component state variable is changed, the component can be re-rendered with the
95+
updated values, displaying the latest state of the component with these updates.
96+
97+
### Creating a Component State
98+
99+
To create a new **Component State variable** in your component, follow the steps:
100+
101+
102+
<div style={{
103+
position: 'relative',
104+
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
105+
height: 0,
106+
width: '100%'
107+
}}>
108+
<iframe
109+
src="https://demo.arcade.software/nEmCDqupF7YHUTi4hKvW?embed&show_copy_link=true"
110+
title="Create Component State"
111+
style={{
112+
position: 'absolute',
113+
top: 0,
114+
left: 0,
115+
width: '100%',
116+
height: '100%',
117+
colorScheme: 'light'
118+
}}
119+
frameborder="0"
120+
loading="lazy"
121+
webkitAllowFullScreen
122+
mozAllowFullScreen
123+
allowFullScreen
124+
allow="clipboard-write">
125+
</iframe>
126+
</div>
127+
128+
While creating a Component State, the following properties are included:
129+
130+
- **Is List:** This property determines whether the variable can hold multiple values of the same
131+
data type (like a list or array) or just a single value.
132+
133+
- **Initial Field Value:** This property sets the default value for the variable when it is first
134+
created. It's like setting the starting point or the value that the variable begins with before
135+
anything else happens.
136+
137+
- **Nullable:** This property determines whether the variable can have a null value. When "**Nullable**" is set to true, it means the variable can be empty or have a null value. This is
138+
useful when dealing with optional data or scenarios where the absence of a value is valid.
139+
140+
Now, let's apply these concepts to the `isFavourite` variable in the context of the above example:
141+
142+
- For the `isFavourite` variable, it is a single value (boolean), so **Is List** would be set to
143+
false.
144+
145+
- The **Initial Field Value** would also be set to **false**, indicating that the item is not
146+
favorited by default.
147+
148+
- **Nullable** property will be set to false, as the variable should always have a boolean value
149+
(true or false) and never be null.
150+
151+
:::note
152+
You can set the **Data Type** of your Component State variable to any primitive data types such as **String, Integer, Boolean, Double** or to any other complex built-in data types such as **Enum, Custom Data
153+
Type, Document,** etc. To learn more about the available data types, refer the [**Data
154+
Representation Section.** ](#)
155+
:::
156+
157+
### Get Component State Value
158+
159+
In the following example, we demonstrate how to toggle the heart icon from an outlined to a filled
160+
icon based on the `isFavourite` state variable. We introduce a `Conditional Builder` widget that
161+
allows us to show a widget tree based on **If/Else If/Else** conditions. The goal is to visually
162+
indicate whether a product has been favorited by the user.
163+
164+
Follow the steps as below:
165+
166+
<div style={{
167+
position: 'relative',
168+
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
169+
height: 0,
170+
width: '100%'
171+
}}>
172+
<iframe
173+
src="https://demo.arcade.software/Y96decdgYWVll3SP9Jk8?embed&show_copy_link=true"
174+
title="Get Component State"
175+
style={{
176+
position: 'absolute',
177+
top: 0,
178+
left: 0,
179+
width: '100%',
180+
height: '100%',
181+
colorScheme: 'light'
182+
}}
183+
frameborder="0"
184+
loading="lazy"
185+
webkitAllowFullScreen
186+
mozAllowFullScreen
187+
allowFullScreen
188+
allow="clipboard-write">
189+
</iframe>
190+
</div>
191+
192+
### Update Component State [Action]
193+
194+
**Component state** values can only be updated via actions. Whenever you want to update the
195+
component state, call an action called **Update Component State** from the Action Flow Editor
196+
of the component.
197+
198+
In the following demo, we open the Action Flow Editor on the parent widget `Conditional Builder` and
199+
call the **Update Component State** action to toggle the value of `isFavourite`.
200+
201+
<div style={{
202+
position: 'relative',
203+
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
204+
height: 0,
205+
width: '100%'
206+
}}>
207+
<iframe
208+
src="https://demo.arcade.software/Y96decdgYWVll3SP9Jk8?embed&show_copy_link=true"
209+
title="Get Component State"
210+
style={{
211+
position: 'absolute',
212+
top: 0,
213+
left: 0,
214+
width: '100%',
215+
height: '100%',
216+
colorScheme: 'light'
217+
}}
218+
frameborder="0"
219+
loading="lazy"
220+
webkitAllowFullScreen
221+
mozAllowFullScreen
222+
allowFullScreen
223+
allow="clipboard-write">
224+
</iframe>
225+
</div>
226+
227+
#### Rebuild on Update
228+
229+
When updating your component state in FlutterFlow, you'll often come across the **Update
230+
Type** property in your Action properties. Here's what it means:
231+
232+
- **Rebuild Containing Page:** This option triggers a re-rendering of the page
233+
containing this component.
234+
235+
- **Rebuild Current Component:** This option triggers a re-rendering of the current component only.
236+
237+
- **No Rebuild:** Choose this option when you need to update the state value without
238+
immediately reflecting the changes in the UI.
239+
240+
:::warning[Expensive Rebuilds]
241+
Too many rebuilds can impact performance because rebuilding the widget tree
242+
frequently consumes resources and may lead to decreased responsiveness and
243+
increased battery usage. Therefore, it's essential to consider the trade-offs
244+
and use rebuilds judiciously to maintain optimal app performance.
245+
246+
To learn more about what happens behind the scenes, refer to
247+
the [**Generated Page**](#) section.
248+
:::
249+
250+
251+
252+
253+

0 commit comments

Comments
 (0)