Skip to content

Commit 76d390a

Browse files
harshilp24harshilp24
committed
ui-tutorial
1 parent 02f44b8 commit 76d390a

File tree

3 files changed

+173
-16
lines changed

3 files changed

+173
-16
lines changed

‎website/docs/packages/reference/query-module.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,6 @@ When you incorporate a module from the package into your application, you create
77
This page provides information about the module settings and properties available within the app, enabling you to configure the query and JS modules.
88

99

10-
<ZoomImage
11-
src="/img/modules-diagram.png"
12-
alt=""
13-
caption=""
14-
/>
15-
1610

1711
<ZoomImage
1812
src="/img/query-module-ins.drawio.png"

‎website/docs/packages/tutorial/ui-module.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# UI Module
2+
3+
In this tutorial, you will learn how to create a reusable UI Module that accepts dynamic inputs from an application.
4+
UI Modules can be built using widgets, private queries, and private JS Objects, enabling you to encapsulate visual elements, data fetching, and logic within a self-contained component.
5+
6+
7+
:::tip What will I learn? 📝
8+
In this tutorial, you will create a reusable User Profile Card UI Module that displays basic user details dynamically.
9+
10+
- 🔧 **Basics**: Learn how to create and configure a UI Module.
11+
- 🔄 **Dynamic Data**: Learn how to pass data from an application into the UI Module.
12+
- ♻️ **Reusability**: Discover how to reuse the UI Module across multiple applications
13+
:::
14+
15+
16+
17+
## Prerequisites
18+
19+
Before you start, make sure you have the following:
20+
21+
* A self-hosted instance of Appsmith with a [paid subscription](https://www.appsmith.com/pricing). Refer to the [Appsmith installation guides](/getting-started/setup/installation-guides) for detailed instructions on setting up your Appsmith instance.
22+
* If you are new to Appsmith, see [Tutorial - Basics](/getting-started/tutorials/start-building).
23+
24+
25+
26+
27+
:::note
28+
The ability to use query modules or JS modules directly inside UI Modules is not currently supported. This functionality will be available in a future release.
29+
:::
30+
31+
<div style={{ position: "relative", paddingBottom: "calc(50.52% + 41px)", height: 0, width: "100%" }}>
32+
<iframe
33+
src="https://demo.arcade.software/KHcwNrupekXborH0Hw4Z?embed"
34+
frameBorder="0"
35+
loading="lazy"
36+
webkitAllowFullScreen
37+
mozAllowFullScreen
38+
allowFullScreen
39+
allow="fullscreen"
40+
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
41+
title="Appsmith | Connect Data"
42+
/>
43+
</div>
44+
45+
46+
1. Open your workspace and click **Create New** in the top-right corner. Select Package and choose **UI Package** as the package type.
47+
48+
<dd>
49+
50+
A UI Package is a collection of UI Modules that contain reusable widgets, queries, and JS Objects. These modules can be dynamically configured and reused across multiple applications within the same workspace.
51+
52+
</dd>
53+
54+
2. Click on the Module Container. The module container represents the overall layout for the UI Module, where you define inputs and configure widgets.
55+
56+
57+
3. From the right-side property pane of the Module Container, you can configure **Inputs**.
58+
59+
60+
<dd>
61+
62+
Inputs allow you to dynamically set widget values inside the module.
63+
These values are passed from the application into the UI Module at
64+
65+
Create the following inputs for the module:
66+
67+
| Input Name | Purpose |
68+
| ----------- | ------------------------------- |
69+
| `userName` | Full name of the user |
70+
| `userEmail` | Email address of the user |
71+
| `userID` | Unique ID of the user |
72+
| `userImg` | URL of the user's profile photo |
73+
74+
75+
</dd>
76+
77+
4. Drag three Text widgets and one Image widget onto the canvas to create a simple user profile UI.
78+
These widgets will display user details such as the user's name, email, ID, and profile photo, using the input values passed from the application.
79+
80+
5. Once the widgets are added to the canvas, configure each widget to display values passed through the module’s inputs.
81+
82+
<dd>
83+
84+
To bind an input value to a widget, use the following syntax:
85+
86+
```js
87+
{{inputs.<inputName>}}
88+
```
89+
90+
Set the widget properties as follows:
91+
92+
| Widget | Property | Value |
93+
| -------------------- | ------------------ | ---------------------- |
94+
| Name Text Widget | Text | `{{inputs.userName}}` |
95+
| Email Text Widget | Text | `{{inputs.userEmail}}` |
96+
| ID Text Widget | Text | `{{inputs.userID}}` |
97+
| Profile Image Widget | Image Source / URL | `{{inputs.userImg}}` |
98+
99+
</dd>
100+
101+
102+
6. Publish the UI Module from the top-right corner.
103+
This allows the module and its changes to reflect on the application side for reuse.
104+
105+
<dd>
106+
107+
If the package is git-connected, you also need to release a new version for the changes to be available. For more details, refer to [Package Version Control](/packages/reference/versioning).
108+
109+
</dd>
110+
111+
112+
7. Navigate back to the workspace homepage and create a new application.
113+
114+
8. Inside the application, click on the **UI** tab and select Add **New UI Element**. Click on **Module** to view all the UI Modules that are published within the same workspace.
115+
116+
117+
9. Drag the `UserProfileCard` module onto the canvas. This creates an instance of the UI Module that you can configure inside the application.
118+
119+
10. To pass dynamic data into the module, drag a Table widget onto the canvas.Click **Connect Data** and select the **Sample Users** datasource.
120+
Then, select the **public.users** table to connect the Table widget to sample user data.
121+
122+
11. Click on the `UserProfileCard` module instance added to the canvas.
123+
In the property pane, set each input by referencing the selected row from the Table widget.
124+
125+
<dd>
126+
127+
Use the following bindings:
128+
129+
130+
| Input Name | Value |
131+
| ----------- | ------------------------------- |
132+
| `userName` | `{{Table1.selectedRow.name}}` |
133+
| `userEmail` | `{{Table1.selectedRow.email}}` |
134+
| `userID` | `{{Table1.selectedRow.id}}` |
135+
| `userImg` | `{{Table1.selectedRow.image}}` |
136+
137+
138+
</dd>
139+
140+
:::tip
141+
🎉 Great Job!
142+
143+
You have successfully created a reusable UI Module that dynamically displays user details based on application data.
144+
145+
By using inputs, you can easily reuse this User Profile Card across different applications and pass parameters at runtime, without rebuilding the UI each time.
146+
:::

‎website/sidebars.js‎

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -749,7 +749,8 @@ const sidebars = {
749749
label: 'Tutorial',
750750
items: [
751751
'packages/tutorial/query-module',
752-
'packages/tutorial/js-module'
752+
'packages/tutorial/js-module',
753+
'packages/tutorial/ui-module'
753754
],
754755
},
755756
{
@@ -761,15 +762,31 @@ const sidebars = {
761762
'packages/how-to-guides/use-query-inside-js-module',],
762763
},
763764
{
764-
type: 'category',
765-
collapsed: false,
766-
label: 'Reference',
767-
items: [
768-
'packages/reference/package',
769-
'packages/reference/query-module',
770-
'packages/reference/versioning'
771-
],
772-
}
765+
type: 'category',
766+
collapsed: false,
767+
label: 'Reference',
768+
items: [
769+
'packages/reference/versioning', // Package Version Control
770+
{
771+
type: 'category',
772+
label: 'Code Packages',
773+
collapsed: true,
774+
items: [
775+
'packages/reference/package', // Module
776+
'packages/reference/query-module', // Module Instance
777+
],
778+
},
779+
{
780+
type: 'category',
781+
label: 'UI Packages',
782+
collapsed: true,
783+
items: [
784+
'packages/reference/ui-module', // UI Module
785+
'packages/reference/ui-module-instance', // UI Module Instance
786+
],
787+
},
788+
],
789+
}
773790
]
774791
}, //module end
775792

0 commit comments

Comments
 (0)