diff --git a/.github/styles/Google/Headings.yml b/.github/styles/Google/Headings.yml index ff2dc16de7..c5accbdc44 100644 --- a/.github/styles/Google/Headings.yml +++ b/.github/styles/Google/Headings.yml @@ -241,4 +241,7 @@ exceptions: - console.log - console.error - console.warn - - Community \ No newline at end of file + - Community + - Datasources (Server Data Models) + - Widgets (Views) + - Queries and JavaScript (Controllers) \ No newline at end of file diff --git a/website/docs/build-apps/overview.md b/website/docs/build-apps/overview.md index 1ed6b558a9..a4a716001e 100644 --- a/website/docs/build-apps/overview.md +++ b/website/docs/build-apps/overview.md @@ -1,8 +1,40 @@ # Overview -Appsmith allows you to develop internal applications with streamlined integration of front-end and back-end. Built-in widgets serve as foundational blocks for dynamic app layouts, all customizable through a user-friendly drag-and-drop interface. +Appsmith is a low-code development platform that enables the rapid creation of web applications through an architecture that supports reactive bindings and MVC-like separation. The platform revolves around widgets, datasources, queries, and JavaScript, each serving a unique role in the application's structure. +### Datasources (Server Data Models) +Datasources encapsulate the connections to databases, APIs, and other services, and are shared across all applications within a workspace. This allows developers to securely connect to the data models in their databases. + +### Widgets (Views) + +Widgets are the visual components of an Appsmith application; they represent the 'views' in the architectural framework. From input fields to tables and charts, widgets provide the means for user interaction and data presentation. Widget properties can be either statically assigned or dynamically controlled through JavaScript expressions, which adapt to changes in the application's state. + +### Queries and JavaScript (Controllers) + +Queries function as 'controllers', shaping the flow of data between views and models. They can retrieve, update, and submit data to the datasources based on interactions with the application's widgets. JavaScript can be embedded within these queries using mustache binding syntax (`{{...}}`), providing dynamic data manipulation and interaction within the application. + +Appsmith stores the last response from a query execution within the query object's data property, thus bringing the server data models to the client as application state and making them accessible to the widgets (views). + +### Reactive bindings + +Appsmith's framework is inherently reactive, which means that changes in the state of any entity like widgets, queries, or JSObjects automatically trigger updates throughout the application. This reactivity eliminates the need for imperative command sequences to keep the user interface in sync with the application's state. +Developers can describe the desired state of a widget through expressions that reference other entities in the application. For example, to hide or show a widget based on the existence of a selected row in a table, one might use: + +``` +{{ Table1.selectedRow !== undefined }} +``` + +This reactive binding ensures that the visibility of the widget is automatically managed by Appsmith, without needing to write explicit event handlers or rely on callback functions which can be quite difficult to maintain. + +## Data flows in Appsmith + +Most applications are a combination of read or write data flows. + +- ** Read data flows (Model -> Controller -> View) **: Data from a datasource (server data model) is fetched and transformed using a query & javascript (controller) and displayed on a widget like a table (view). +- ** Write data flows (View -> Controller -> Model) **: Data captured from a widget like a form (view) is validated, sanitised and sent using a query & javascript (controller) to update a datasource (server data model). + +Mastering these data flows allows developers to create applications that can seamlessly read and write data, creating a dynamic and reactive user experience. Understanding and utilizing these patterns is the key to efficiently build robust applications with Appsmith.
diff --git a/website/docs/build-apps/reference/README.md b/website/docs/build-apps/reference/README.md index 6f9d05f666..3fe3a8f344 100644 --- a/website/docs/build-apps/reference/README.md +++ b/website/docs/build-apps/reference/README.md @@ -1,13 +1,7 @@ - import DocCardList from '@theme/DocCardList'; # Reference -Technical descriptions and information about widgets and app settings. - - - -
@@ -22,5 +16,3 @@ Technical descriptions and information about widgets and app settings.
Theme allows you to style your pages and widgets using global controls, making it easy to change the visual layout with a single click.
- - diff --git a/website/docs/connect-data/reference/overview.md b/website/docs/connect-data/reference/overview.md index ca50399a19..b29ed0be30 100644 --- a/website/docs/connect-data/reference/overview.md +++ b/website/docs/connect-data/reference/overview.md @@ -1,10 +1,5 @@ # Reference -Technical descriptions and information about widgets and app settings. - - - -
@@ -19,5 +14,3 @@ Technical descriptions and information about widgets and app settings.
This page is a reference guide that provides a description of all the settings available for configuring your queries.
- - diff --git a/website/docs/core-concepts/writing-code/ext-libraries.md b/website/docs/core-concepts/writing-code/ext-libraries.md index 25a7f1ee80..31d489a1dd 100644 --- a/website/docs/core-concepts/writing-code/ext-libraries.md +++ b/website/docs/core-concepts/writing-code/ext-libraries.md @@ -1,78 +1,61 @@ -# Use External JS Libraries +# Use External JS Libraries -The Appsmith platform includes built-in JavaScript utility libraries, which can be used to work with data within `{{ }}` bindings or within JSObjects. You can also install and use other custom libraries to manipulate or transform data. These external libraries provide additional methods to help you build complex applications and business logic. +You can install custom libraries to help you build complex applications and business logic. Custom Javascript libraries enable complex use cases like PDF generation, CSV Parsing, & authentication. - -## Custom JavaScript Libraries - -Custom Javascript libraries provide far more advanced capabilities for complex use cases like PDF generation, CSV Parsing, analytics, authentication, error logging, etc. You can browse and install a JS library of your choice by pasting a valid URL to the library’s index file. - -### Library compatibility - -Appsmith is only compatible with libraries that support **[UMD](https://github.com/umdjs/umd)** builds. If a library supports the UMD build format, the source code of a library’s index file should conform to this [basic pattern](https://github.com/umdjs/umd/blob/master/templates/commonjsStrict.js). The index file for most compatible libraries can be found under the `root`, `/umd` or `/browser` folders and have a `.min.js` file extension. If a library you wish to use doesn't support a UMD build, you may use [browserify](https://browserify.org/) to generate one and host it in a CDN of your choice. - -✅ Valid URL: `https://cdn.jsdelivr.net/npm/exceljs@4.3.0/dist/exceljs.min.js` - -❌ Valid URL. Unsupported build format: `https://cdn.jsdelivr.net/npm/uuid@9.0.0/dist/index.js` - -❌ Invalid URL. Doesn't point to the index file: `https://www.jsdelivr.com/package/npm/datejs` - ### Install external library -Appsmith makes it easy to install an external JavaScript library with just a few simple steps - - - -There is a selection of recommended libraries that you can install by simply clicking on the install icon. However, if you want to install a specific library with a URL, the process is just as simple. To install other libraries: +Appsmith provides a set of recommended libraries that you can install by clicking the + icon next to libraries in the entity explorer and clicking on the install icon next to the library. +If you want to install a specific library that you found online, the steps are: -- Find a [compatible](#library-compatibility) library on popular CDN services like [jsDelivr](https://www.jsdelivr.com/) or [UNPKG](https://unpkg.com/). -- Copy the URL to its index file and paste it on Appsmith to start the installation. +- Find a [compatible](#library-compatibility) distribution of the library on a popular CDN service like [jsDelivr](https://www.jsdelivr.com/) or [UNPKG](https://unpkg.com/) +- Copy the URL to its index file - Navigate to the Explorer tab -- Click the `+` sign next to `Libraries`. -- Paste the URL into the designated field. For example: +- Click the `+` sign next to `Libraries` +- Paste the URL into the designated field +- Click `Install` -```js +Example URL: + +```URL https://cdn.jsdelivr.net/npm/exceljs@4.3.0/dist/exceljs.min.js ``` -- Click `Install`. +### Library compatibility -### Using external libraries +Appsmith only supports libraries that have **[UMD](https://github.com/umdjs/umd)** builds. The index file for most compatible libraries can be found under the `root`, `/umd` or `/browser` folders and have a `.min.js` file extension. If a library you wish to use doesn't support a UMD build, you may use [browserify](https://browserify.org/) to generate one and host it in a CDN of your choice. -External libraries can be used within `{{ }}` in the same way JavaScript is used elsewhere in the application. For more information about the signature of the JavaScript libraries, see their official documentation. +✅ Valid URL: `https://cdn.jsdelivr.net/npm/exceljs@4.3.0/dist/exceljs.min.js` -### Examples +❌ Invalid URL: unsupported build format: `https://cdn.jsdelivr.net/npm/uuid@9.0.0/dist/index.js` -Here are some examples of how to use external JavaScript libraries: +❌ Invalid URL: doesn't point to the index file: `https://www.jsdelivr.com/package/npm/datejs` -#### lodash +Appsmith also does not support libraries -Following is an example of the Lodash `_.map` utility, in use. `fetchFruits` is the name of the API / Query +- Libraries that manipulate the DOM +- Libraries that reply on making XHR requests +- Libraries that try to invoke or access certain browser methods + - setInterval + - clearInterval + - localStorage + - setImmediate + - navigator -```javascript -{ - { - _.map(fetchFruits.data, (fruit) => { - return { label: fruit.name, value: fruit.id }; - }); - } -} -``` +### Accessing installed libraries -#### moment +External libraries once installed can be accessed as an object anywhere you can write Javascript in Appsmith. For information about the signature of the JavaScript libraries, see their official documentation. -An example of the moment.js `format` utility, in use in a [query](/connect-data/overview). +#### Example -```sql -insert into users (name, email, createdDate) values -('John', 'john@appsmith.com', {{moment().format("YYYY-MM-DD")}}) -``` +You can install excelJS library using this URL -#### excelJS +``` +https://www.jsdelivr.com/package/npm/exceljs +``` -You can install excelJS library using this [URL](https://www.jsdelivr.com/package/npm/exceljs) . +You can write code to create a workbook in a JS function as below ```javascript createWorkbook: async () => { @@ -104,15 +87,6 @@ createWorkbook: async () => { }; ``` -## General notes - -You may not be able to install or use methods of certain libraries due to platform limitations: - -* [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) access: Libraries that try to manipulate document objects won’t work. Example: https://d3js.org/ -* [XHR](https://developer.mozilla.org/en-US/docs/Glossary/XMLHttpRequest): Libraries that only rely on XHR won’t work. -* Other APIs: Library methods that use the following APIs under the hood won’t work: [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval), [clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval), [setImmediate](https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate), [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and [Navigator](https://developer.mozilla.org/en-US/docs/Web/API/Navigator). - - ### Troubleshooting -If you are experiencing difficulties with connecting external libraries, you can refer to the [JavaScript Errors troubleshooting guide](/help-and-support/troubleshooting-guide/js-errors) for assistance or seek help on [Discord](https://discord.com/invite/rBTTVJp). You can also ask questions and get support on the [community forum](https://community.appsmith.com/). +If you are experiencing difficulties installing external libraries, you can refer to the [JavaScript Errors troubleshooting guide](/help-and-support/troubleshooting-guide/js-errors) or reach out to the support team via the chat widget on this page. diff --git a/website/docs/core-concepts/writing-code/javascript-editor-beta/README.md b/website/docs/core-concepts/writing-code/javascript-editor-beta/README.md index 1f560e5829..fae4420109 100644 --- a/website/docs/core-concepts/writing-code/javascript-editor-beta/README.md +++ b/website/docs/core-concepts/writing-code/javascript-editor-beta/README.md @@ -1,362 +1,68 @@ -# Create JS Objects +# JS Objects -The JavaScript Editor in Appsmith enables you to create _JS Objects_ with a page-level scope. A JS Object is an encapsulation of variables and functions associated with it. It is a template similar to a Java class that contains the variables and the methods used to perform actions. +JS Objects in Appsmith are powerful tools that enable developers to encapsulate JavaScript code, including functions and variables, to enhance the capability of their applications. They serve the purpose of segregating business logic, performing complex data manipulations, and interacting seamlessly with Appsmith's widgets and backend services. This updated document will provide a detailed understanding of JSObjects in Appsmith, focusing on the aspect of exporting a single default object and the behavior of variables within it. -:::info -JS Objects are accessible only within the page where they're defined and aren't accessible across pages. -::: +## Defining a JS Object - +To define a JS Object in Appsmith, you create a JavaScript module that contains an object that exports specific functions and variables. It's important to note that a JS Object can only export one default object. Here's the general structure of a JS Object: -## Create JS Objects - -You can create JS Objects from the entity explorer on the left sidebar. - -Click the **Explorer** tab. Click **+** next to **Queries/JS**. Select **New JS Object** from the list of options. - -![Create JS Object](/img/create-js-object.png)
Create JS Object
- -A JS Object has the following structure: - -``` +```javascript export default { - - myVar1: [], // define array - myVar2: {}, // define object - - // define functions - myFun1: () => { - //write code to manipulate the data or perform actions like executing a query - }, - - myFun2: async () => { - //use async-await or promises - // this helps when you want to trigger queries at run time. - // For example, API_NAME.run() - run method executes the call and returns the response. - } - -} -``` - -:::caution -The JS Object notation should start with `export default`. The [**export default**](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export) declaration exposes functions that are part of the JS Object to the page where it is defined. -::: - -You can access the properties of the JS Objects defined using the dot or bracket notation. - -**Example**: - -``` - export default { - - useJSObjectProps: () => { - const userObject = new Object(); //object with method scope and is local to this method. - userObject.id = 1; // setting property using dot notation - userObject[“name”] = “John”; //setting property using bracket notation - showAlert(userObject.id); - showAlert(userObject[“name”]); - } - -} + // Exported functions and variables go here +}; ``` -## Execute functions +Within this default object, you can define all your reusable code and state that can be accessed throughout the application. -Click the **Run** button on the top right corner to execute the JS function. If your JS object has only one function defined, the editor defaults the function name. But if your JS Object has more than one function defined, you can select the function you want to execute and then click **Run**. If your code has errors, the **Run** button is greyed out and blocks the execution until the errors are resolved. You can also execute the function using a shortcut key **CMD+ENTER** or **CTRL + ENTER** +## Functions in JS Objects +JSObjects can contain different types of function definitions. -## Use variables for state management - -JS Object variables are mutable and can be used to contain the reference to a value. You can use it to store your data in a non-persistent state. As the storage state is non-persistent, the data is saved until the page reloads or until the user closes the window. JSObject variables can be of any data type, such as Number, String, Object, Array, Date object, etc. - - - -**Example 1:** a counter that increments or decrements the value in a JS Object variable. - -1. Create a JS Object `JSObject1` and add the following code: - - ```javascript - export default { - counter: 1, - increment: () ⇒ { - this.counter = this.counter + 1 - }, - decrement: () ⇒ { - this.counter = this.counter - 1 - } - } - ``` - -2. Drop a Text widget on the canvas and display the value of the counter variable in the **Text** property as shown below: - - ```javascript - { - { - JSObject1.counter; - } - } - ``` - -3. Drop two Button widgets labelled _Increment_ and _Decrement_ and add the following code in **onClick** event to trigger these functions: - - ```javascript - //for increment - { - { - JSObject1.increment(); - } - } - - //for decrement - { - { - JSObject1.decrement(); - } - } - ``` - -4. Test the buttons and notice the value change in the Text widget. - ---- - -**Example 2:** mutating values in an array object +### Arrow function example ```javascript export default { - users: [{name: "a"}, {name: "b"}, {name: "c"}, {name: "d"}], - modifyFirstUserName: () ⇒ { - this.users[0].name = "Hello" - } -} + calculateArea: (length, width) => length * width, +}; ``` -:::info -Variable mutations can be triggered only using event listeners(async fields). For example, you can't update the variable value using the **Text** property on the Text widget, but you can use the **onClick** event on the Button widget. -::: - - -## Write complex code - -When you build applications, it’s often more than just a CRUD operation from a single datasource. You might integrate with multiple APIs or want the dataset created by querying multiple tables to traverse data, filter, or manipulate the response by calling different APIs. You can write complex logic with ease using JavaScript Editor. - -### Use case - -You want to create a developer task tracker dashboard, update developer information, and add some permissions, like ensuring only admins can access the dashboard. +### Traditional function syntax -#### Code workflow - -Let’s create a task tracker dashboard that gives you an overview of task progress. You have a query called “_developers_,” which fetches the developers’ information like name, email, etc. You have an API, `getAllDeveloperTaskStatus`, that gives you a task list with the status for each developer. - -**Task Tracker** - -You want to display the developer details in a tabular format so that you can choose a table widget. You would want to show a total number of tasks like total tasks, no of completed tasks, no of to-do tasks, and no of in-progress tasks. You can achieve this by adding a JS Object and creating one function in it, “_getTaskList_.” Let’s write the code for this function using the JavaScript Editor. - -- In the **Explorer** tab, >> click **(+)** next to `JS Objects` >> Select `New JS Object`. -- It’ll open a JS Editor. Rename the JS Object to `Utils` -- Add the below code snippet in the **Code** tab. - -``` +```javascript export default { - getAllDeveloperTaskStatus: () => { - return developers.data.map((developer) => { - const developerId = developer.id; - const taskList = developerTaskStatus.data.filter((alltask) => alltask.userId === String(developerId)); // fetch all the tasks for the given developer - const completedTaskList = taskList.filter((task) => task.status === "Completed"); // fetch tasks that are completed by the developer - const todoTaskList = taskList.filter((task) => task.status === "To-Do"); // fetch tasks that aren't yet started by the developer - const inProgressTaskList = taskList.filter((task) => task.completed === "In-Progress"); // fetch tasks that are in progress by the developer - return { - "Id": developer.id, - "Name": developer.name, - "Email": developer.email, - "Total Tasks": taskList.length, - "To-Do Tasks": todoTaskList.length, - "In Progress Tasks": inProgressTaskList.length, - "Completed Tasks": completedTaskList.length - }; - }) - } -} + calculateArea: function (length, width) { + return length * width; + }, +}; ``` -The `getAllDeveloperTaskStatus` function does the following: - -- Reads all the developers’ data -- Iterates for each developer record - - Scans the `tasklist` to fetch the developer-related tasks - - Based on task status (TO-DO, In-Progress, and Completed) - - Generate a response that gives a cumulative task breakup for each task status for each developer - -To display the response generated by`getAllDeveloperTaskStatus` bind it to a widget. - -- Navigate to `Page` >> Select [`Table`](../../../reference/widgets/table/) widget in Widgets Tab >> Drag it onto the canvas. -- Select the `Table` Widget on the canvas -- In the `Property Pane` on the right side add the code `{{Utils.getAllDeveloperTaskStatus()}}` in the `Table Data` property. - - - -The [table widget](../../../reference/widgets/table/) shows the data in the screenshot below. - -![Display data in a table widget](/img/JavaScript_Editor__Write_Complex_Code__Bind_JS_Function_Response_to_Table_Widget.png) - -**Update Developer Information** - -Let’s add another function where you can select a developer record and update the information. - -To achieve this, add a new column to the [table widget](../../../reference/widgets/table/) and select the `Column Type` as an `icon button` type that opens a modal window. - - - -Now that the `Edit` column appears on the table, let’s add a modal to fetch the `developer` information like `Name` and `Email`. - - +### ES6 function syntax -Navigate to Explorer >> Select `Utils` >> Add the code snippet for `updateUserData()` after `getAllDeveloperTaskStatus()`. - -``` +```javascript export default { - getAllDeveloperTaskStatus: () => { - ...// code block for getAllDeveloperTaskStatus - }, - updateUserData: () => { - // Construct new user's data - const newUserData = { - ...Table1.selectedRow, - name: devName.text, - email: devEmail.text, - } - // Run updateDeveloperDetails query - updateDeveloperDetails.run( - // on successful execution of updateDeveloperDetails run developers to fetch updated data - async () => { - await developers.run(); - closeModal("editModal"); - showAlert("Developer Details are updated successfully!"); - }, - // On Error, close the modal and show an error toast - (e) => { - closeModal("editModal") - showAlert("An error occurred while updating the developer details!"); - if (e.statusCode === 401) { - navigateTo("Page1"); - } - }, - // Params Object - newUserData) - } -} + calculateArea(length, width) { + return length * width; + }, +}; ``` -The `updateUserData` function does the following: - -- Create the dynamic data that are updated by the user in `editModal` in `newUserData` JSON -- Executes query `updateDeveloperDetails` - - On successful execution of the query: - - Calls `developers` query to fetch the updated developer details - - Shows a success toast to the user - - Closes the `editModal` - - On error or failed execution of the query - - Shows an error toast to the user - - Closes the `editModal` - -Rename the `Confirm` button to `Update` and bind the function `updateUserData` to its `onClick()` event. You can bind the function call by using `{{Utils.updateUserData()}}`. - -![How to bind function call to an `onClick` event?](/img/JavaScript_Editor__Edit_Modal__Bind_UpdateUser_Function_Call_on_Update_Button.png) - -When you hit the `Update` button, the `updateUserData` function gets executed which updates the developer information and refreshes the developer table to fetch the updated information. - -**Add Permissions** - -As you want only the admins to access the dashboard, let’s create another function for access control. The function contains a list of users’ emails who can update data in the table. Let’s call this function `isAdmin`. +## Variables in JS Objects -Add the code snippet for `isAdmin()` and `adminsList` to the `Utils` JS Object. +Variables declared in a JSObject are assigned by value. This means that if you assign a changeable object or a primitive value to a variable within the JSObject, it will not automatically update if the original source changes. To update a variable in the object, you must explicitly re-assign it. -``` -export default { - adminsList: ["admin1@yourdomain.com", "admin2@yourdomain.com", "admin3@yourdomain.com"], - getAllDeveloperTaskStatus() => { - ... // code block for getAllDeveloperTaskStatus - }, - updateUsersData() => { - ... // code block for updateUserData - }, - isAdmin: (email) => { - if (this.adminList.indexOf(appsmith.user.email) > -1) { // check if the logged in user is an admin - return true; - } - return false; - } -} -``` - -The final function looks like the below: - -``` +```javascript export default { - //the allowed list of admin's email - adminsList: ["admin1@yourdomain.com", "admin2@yourdomain.com", "admin3@yourdomain.com"], - getAllDeveloperTaskStatus: () => { - return developers.data.map((developer) => { - const developerId = developer.id; - const taskList = developerTaskStatus.data.filter((alltask) => alltask.userId === String(developerId)); // fetch all the tasks for the given developer - const completedTaskList = taskList.filter((task) => task.status === "Completed"); // fetch tasks that are completed by the developer - const todoTaskList = taskList.filter((task) => task.status === "To-Do"); // fetch tasks that aren't yet started by the developer - const inProgressTaskList = taskList.filter((task) => task.completed === "In-Progress"); // fetch tasks that are in progress by the developer - return { - "Id": developer.id, - "Name": developer.name, - "Email": developer.email, - "Total Tasks": taskList.length, - "To-Do Tasks": todoTaskList.length, - "In Progress Tasks": inProgressTaskList.length, - "Completed Tasks": completedTaskList.length - }; - }) - }, - updateUserData: () => { - // Construct new user's data - const newUserData = { - ...Table1.selectedRow, - name: devName.text, - email: devEmail.text, - } - // Run updateDeveloperDetails query - updateDeveloperDetails.run( - // on successful execution of updateDeveloperDetails run developers to fetch updated data - async () => { - await developers.run(); - closeModal("editModal"); - showAlert("Developer Details are updated successfully!"); - }, - // On Error, close the modal and show an error toast - (e) => { - closeModal("editModal") - showAlert("An error occurred while updating the developer details!"); - if (e.statusCode === 401) { - navigateTo("Page1"); - } - }, - // Params Object - newUserData) + colorValue: "#4A90E2", // The color value is set when the JSObject is defined +}; - }, - isAdmin: async () => { - if (this.adminsList.indexOf(appsmith.user.email) > -1) { - return true; - } - navigateTo("Page2"); - return false; - } -} +// Example of re-assigning the variable +setColorValue: (newColor) => { + jsObjectName.colorValue = newColor; +}; ``` - - -Only the users with email added to the `adminList` can access the dashboard and do the updates. - -With the Async function settings, you can bind the `isAdmin` function to `RUN ON PAGE LOAD`. The execution of `IsAdmin` on page load ensures the validation of the user’s email against the `adminList` for the logged-in user should happen on the page load. If the logged-in user's email is in the `adminsList`, the user can access the dashboard. If not, the user navigates to the denied access page with the message 'You don't have permission to access the Dashboard'. +In this example, `colorValue` is initially assigned a hex color code. If later in the application, you want to change this color based on user interaction or some other event, you will have to explicitly call a function like `setColorValue` and pass the new color value as an argument to update `colorValue`. -## Current limitations +## Summary -- You can't use `JS Objects` defined within a page across other pages. -- You can't define variables and functions outside of the `export default { }` declaration. -- If a function is async, it means that it returns a promise, so it can't be called on the fields incompatible with the return type, such as the **Text** property of the Text widget. +JSObjects in Appsmith are critical for developers who want cleaner code and modular application logic. By limiting JSObjects to a single default export, Appsmith ensures code encapsulation and modularity. Use JSObjects to centralize your application's logic and data manipulations in a secure and organized manner, facilitating both individual productivity and teamwork in building sophisticated applications on the Appsmith platform. diff --git a/website/docs/reference/appsmith-framework/query-object.mdx b/website/docs/reference/appsmith-framework/query-object.mdx index cf4b6f7b43..372f25b15b 100644 --- a/website/docs/reference/appsmith-framework/query-object.mdx +++ b/website/docs/reference/appsmith-framework/query-object.mdx @@ -1,15 +1,15 @@ --- sidebar_position: 3 --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import CodeBlock from "@theme/CodeBlock"; # query The `query` object contains the parameters required to run queries and access the query data. - ## Properties The query object has the following properties that you can use to reference the query's response or check the status of the query. @@ -18,11 +18,12 @@ The query object has the following properties that you can use to reference the
-`data` is a read-only property that contains the response body from the last successful execution of this query. +`data` is a read-only property that contains the response body from the last successful execution of this query. ``` {{Query1.data}} ``` + If this property is referenced in a widget's property field, the query is automatically run on page load. You can manually enable a query to run on page load from the [query settings](/connect-data/reference/query-settings).
@@ -39,7 +40,6 @@ The `responseMeta` object contains details about the response, such as the statu - ## Methods Query object has the following methods that enable you to run a query or clear a query response. @@ -48,26 +48,25 @@ Query object has the following methods that enable you to run a query or clear a
-When you call the `run()` function of a query, it executes the query. +When you call the `run()` function of a query, it executes the query. #### Signature ``` -run(params: Object): Promise +run(params: Object): Promise ``` -| Argument | Description | -| ------------- | --------------------------------------------------------------------------------------------------- | -| **params** | An object containing key-value pairs to pass into the query. You can access it using the key - `{{ this.params.KEY_NAME }}`. | +| Argument | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **params** | An object containing key-value pairs to pass into the query. You can access it using the key - `{{ this.params.KEY_NAME }}`. | - -`run()` is an asynchronous function and it returns a promise. This asynchronous nature allows you to handle sequential asynchronous actions using `.then()` and `.catch()` methods or the `async/await` syntax. It can't be used in [synchronous fields](/core-concepts/writing-code/workflows#display-data-from-async-js-function). +`run()` is an asynchronous function that returns a promise and thus sequential code may not have the updated response of the query. Sequential code can be executed using the `.then()` and `.catch()` methods or the `async/await` syntax. The run function can't be invoked inside widget data properties but can be invoked from event handlers such as onClick. ```javascript // Using promise syntax to chain actions in sequence {{ Query1.run(params) - .then(() => {...}) // run after the query is successful + .then((response) => {...}) // run after the query is successful .catch(() => {...}) // run if the query encounters any errors }} ``` @@ -76,15 +75,14 @@ In certain scenarios, such as when running a query inside a loop, it may be nece
- ### query.clear()
This function clears all data from the query's `data` property. -``` +``` {{Query1.clear()}} ``` -
\ No newline at end of file + diff --git a/website/docs/write-code/how-to-guides/README.md b/website/docs/write-code/how-to-guides/README.md index 4ce33534e2..d7032edac9 100644 --- a/website/docs/write-code/how-to-guides/README.md +++ b/website/docs/write-code/how-to-guides/README.md @@ -2,21 +2,6 @@ import DocCardList from '@theme/DocCardList'; # How to Guides - -
-
-
- Write Code in Appsmith -
-
Allows you to write JavaScript code almost everywhere on the GUI inside widget properties, events listeners, queries, and other settings.
-
-
-
- Create JS Objects -
-
The JavaScript Editor in Appsmith enables you to create JS Objects with a page-level scope.
-
-
@@ -50,7 +35,7 @@ import DocCardList from '@theme/DocCardList';
- Use external JS libraries + Install External JS libraries
Shows hwo to install external libraries for additional data manipulation or transformation capabilities.
@@ -62,4 +47,3 @@ import DocCardList from '@theme/DocCardList';
- diff --git a/website/docs/write-code/overview.md b/website/docs/write-code/overview.md index 5706d7d0ff..80d3c85ad7 100644 --- a/website/docs/write-code/overview.md +++ b/website/docs/write-code/overview.md @@ -1,8 +1,88 @@ # Overview -Appsmith enables writing JavaScript code almost everywhere on the GUI inside widget properties, events listeners, queries, and other settings. With the help of the JavaScript editor and the debugging tools, you can write complex reusable code and build scalable applications. +One of the key features of Appsmith is the ability to write custom code to enhance the functionality of your applications. This concept document introduces how to write code in Appsmith, the usage of mustache bindings, and the creation and use of functions within JSObjects. +## Inline code with mustache bindings +Appsmith uses a templating syntax (known as mustache bindings) to write dynamic code inside widget properties and queries. Mustache bindings are expressed by wrapping the code inside `{{ }}`. This syntax allows you to insert JavaScript code directly into properties of widgets or as part of query configurations. Writing code inline does not allow for multi-line functions which are better suited to be written inside JSObjects. + +### Inline code in widget properties + +``` +// This code snippet can be used in a widget property to dynamically set its value +{{ "Current date and time: " + new Date().toLocaleString() }} +``` + +When used in widget properties, mustache bindings dynamically compute values based on the current state of the application, user inputs, or other variable data. + +### Inline code in queries + +```javascript +// This example shows a SQL query with mustache bindings to insert dynamic values +SELECT * FROM users WHERE id = {{ Input1.text }} +``` + +Within queries, you can reference widgets JSObjects, & any application state. The bindings will be evaluated at runtime when the query is triggered, ensuring that the latest values are used in the query execution. + +## Creating functions in JS Objects + +A JSObject is a collection of JavaScript functions and variables that can be used to transform data or perform custom logic in your application. It helps in centralizing code, reusability, and keeping the logic separate from the UI. + +### Simple functions + +Simple functions in a JSObject can transform data, format values, or perform any JavaScript logic that doesn't involve asynchronous operations. + +```javascript +export default { + formatUserName: (user) => { + return user.firstName + " " + user.lastName; + }, +}; +``` + +### Asynchronous functions and triggering queries + +Async functions within JSObjects allow you to perform asynchronous operations such as API calls, database queries, or any other operations that return a Promise. + +```javascript +export default { + fetchData: async () => { + const data = await Api1.run(); + return data; + }, +}; +``` + +Since async functions return promises, the value of their returned data can be accessed in a widget by using the .data property of the function. + +``` +{{JSObject1.fetchData.data}} +``` + +Async functions can only be triggered from other async functions or widget event handlers. + +## JavaScript context in Appsmith + +For security purposes, any JavaScript code executed within Appsmith does not have access to the global `window` object that you typically have in a web browser environment. This restriction helps prevent security vulnerabilities and ensures that the code within the application is self-contained. + +However, Appsmith provides a special `appsmith` object that contains a context with useful properties and methods that can be utilized within your code: + +```javascript +export default { + contextExample: () => { + // Access to Appsmith context object properties + console.log(appsmith.user); + console.log(appsmith.store); + // ... other operations + }, +}; +``` + +The `appsmith` object includes information about the current user, application state, and exposed methods useful for application development. By providing these out-of-the-box functionalities within a controlled context, Appsmith ensures both the flexibility and security of code execution within your applications. + +Remember that while Appsmith provides significant power and flexibility for writing custom code, it is important to understand the execution context and keep security best practices in mind while developing your applications. + +---
@@ -10,7 +90,7 @@ Appsmith enables writing JavaScript code almost everywhere on the GUI inside wid
How-to Guides
- Directions and step-by-step guides covering key operations and common tasks. + Directions and step-by-step guides covering key operations and common tasks.
diff --git a/website/docs/write-code/reference/Built-in-JS-Libraries.md b/website/docs/write-code/reference/Built-in-JS-Libraries.md index e056ffa05c..af0953da49 100644 --- a/website/docs/write-code/reference/Built-in-JS-Libraries.md +++ b/website/docs/write-code/reference/Built-in-JS-Libraries.md @@ -1,11 +1,61 @@ -# Built-in JS Libraries +# JS Libraries -Built-in JavaScript libraries provide a comprehensive array of capabilities for common tasks such as data manipulation, numeric operations, date and time handling, and more. These libraries can be accessed and used without the need for any additional installations or setup. +JavaScript libraries simplify common tasks such as data manipulation, date handling, and more. These libraries can be accessed using their imported names inside Appsmith. + +## Built-in JS libraries Appsmith provides the following built-in JavaScript libraries that can be utilized in your applications. -- [Lodash](https://lodash.com/docs/4.17.15) provides functions for common programming tasks such as formatting data, iterating over collections, and manipulating arrays and objects. +#### [Lodash](https://lodash.com/docs/4.17.15) + +
+Lodash provides functions for common programming tasks such as formatting data, iterating over collections, and manipulating arrays and objects. + +``` +{{ _.sortBy(fetchUsers.data, ["age"]) }} +``` + +
+ +#### [Moment](https://momentjs.com/docs/) + +
+simplifies working with dates and times in JavaScript by providing functions for parsing, validating, manipulating, and displaying dates and times. + +``` +{{ moment(datePicker1.selectedDate.format('DD MMM')) }} +``` + +
+ +#### [Fast XML Parser](https://github.com/NaturalIntelligence/fast-xml-parser#readme) + +
+Fast XML Parser can be used to work with cryptographic algorithms and protocols in JavaScript. + +``` +{{ xmlParser.parse(xmlAPI.data) }} +``` + +
+ +#### [Forge](https://github.com/digitalbazaar/forge) + +
+Forge can be used to work with cryptographic algorithms and protocols in JavaScript. + +```javascript +export default { + hash() { + var md = forge.md.sha256.create(); + md.update("The quick brown fox jumps over the lazy dog"); + return md.digest().toHex(); + }, +}; +``` + +
-- [Moment](https://momentjs.com/docs/) simplifies working with dates and times in JavaScript by providing functions for parsing, validating, manipulating, and displaying dates and times. +## External JS libraries -- [Forge](https://github.com/digitalbazaar/forge) can be used to work with cryptographic algorithms and protocols in JavaScript. +You can also [follow this guide](core-concepts/writing-code/ext-libraries) to install external javascript libraries that are not loaded by default into your application. diff --git a/website/docs/write-code/reference/Function-Settings.md b/website/docs/write-code/reference/Function-Settings.md deleted file mode 100644 index 8d2f6dd2f3..0000000000 --- a/website/docs/write-code/reference/Function-Settings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Asynchronous JavaScript Function Settings - -The asynchronous function allows you to choose when you want to execute code. For example, you may want to delay the query execution or fetch the data on demand. - -## How to define an Asynchronous function in Appsmith? - -In the Appsmith environment, a function is termed as **async** if you are performing one of the below actions: - -* You have a keyword (async) that marks the asynchronous execution of the function. - - ``` - export default{ - functionName: async() => { - //use async-await or promises - } - } - ``` -* You have any in-built Appsmith functions like `showModal(), showAlert()`, etc., added in the function block. -* You want to execute a query or call an API on run time. For example, you have an API `GetUsersList,` and you want to call this API on runtime, that is, whenever the JS Object function `callAPI()` is executed. Your function may look as below: - - ``` - export default { - callAPI: () => { - GetUsersList.run(); - } - } - ``` - -The line of code `GetUsersList.run()` marks the function `callAPI()` for asynchronous execution and hence `callAPI` function is considered as async. - -A JavaScript Editor in Appsmith provides some additional settings for asynchronous functions that helps you add more configurations. - -You can specify the settings in the **Settings** tab on the Appsmith JS Editor. - -## Settings - -You’ll see the **Settings** tab next to **Code** whenever you have added an **asynchronous function** to the JS Object. Head to the **Settings** tab and click it to reveal additional configurations. - -Let’s quickly dive into these configurations to understand how they help you make your application behavior better. - -Navigate to **JS Object** —> You’ll see **Settings** next to **Code** - -![How to navigate to JS Object Settings for an asynchronous function?](/img/JSObject-Settings-Tab.png) - -Click **Settings** to reveal configurations. - -![Configurations available for asynchronous functions](/img/Settings-Configurations.png) - -You get two settings to configure for asynchronous functions: - -* RUN ON PAGE LOAD -* CONFIRM BEFORE CALLING - -The settings are available at the function level. For **every** asynchronous function defined, you’ll have a corresponding configuration available for a run on page load and confirm before calling. Refer to the screenshot below, where you can see that the functions - **myFun2** and **`showData`** have configurations available that you can define for them individually. - -![The asynchronous function configurations are available for each async function defined in a JS Object.](/img/Async-Setting-Function-Level.png) - -### RUN ON PAGE LOAD - -As the name suggests, you can use the configuration to mark that your function is executed whenever a page is loaded. For example, you have a page `User Listing` and have added a JS object with the function `GetUserRole` which fetches the user’s role. You want that the query should be executed at the time of page load so that the logged-in user is able to see the user listing. To get this working, you have to set the **RUN ON PAGE LOAD** configuration as **YES** for the `GetUserRole` function. Once the configuration is in place, the function `GetUserRole` is executed whenever the app is loaded and the response generated by it is displayed on the page. - - - - -:::info -By default, **RUN ON PAGE LOAD** is turned **ON** (**Yes** selected) for functions that display data on a widget. That is, the widget binds to the response generated by **`JSObjectName.asynFunctionName.data`**. In this case, the on-page load is automatically set as true. You can explicitly change this setting to suit your logic in the **Settings** tab. -::: - -If you wish to delay the call of function on demand, then select **No**. It marks that the function isn't called on page load, and the execution is deferred until called on demand by calling the function. - -#### Configure run on page load - -On Appsmith, you can bind execution of JS Objects on page load in either of two ways: - -**Bind Response to Widget** - -Whenever you bind a [query](/connect-data/overview) or [API](/connect-data/reference/authenticated-api) response to a [widget](/reference/widgets/), Appsmith automatically sets the execution of the corresponding API or Query on page load. For example, you have a widget that refers to the data property of the JavaScript async function by adding `{{JSObject.myFun.data}}`, at that time Appsmith marks the execution of that query/API on page load. You can modify the same by navigating to **JSObject** → **Settings** → **RUN ON PAGE LOAD** → Select **No**. - - - - -Here’s a quick snapshot of how Appsmith triggers a query or API execution on page load: - -* Add a [table](/reference/widgets/table/) widget (_Table1_), and add a function in `JSObject5` that calls an API _`getUsers`_. The _`getUsers`_ API call is embedded in the _`showData`_ function and generates a user listing. - -![Call a getUsers API in the `showData` JS function]() - -* Bind the response generated by `showData` to table widget `Table1` by adding the below code in the `Table Data` property available on the property pane of the [Table](../../../reference/widgets/table/#table-data) widget. - -``` -{{JSObject5.showData.data}} // behind the scenes Appsmith - // marks execution of showData on page load - // to get the response and bind it to the table data -``` - -![`showData` function called on page load](/img/Show-Data-Called-OnPageLoad.png) - -**Asynchronous Function Setting** - -Especially for asynchronous functions, you can explicitly mark the execution of an async function on page load for the corresponding JS Object. - -Navigate to **JS Object** —> Click **Settings** —> Select **Yes** for **RUN ON PAGE LOAD** next to the JS function. You are all set. Appsmith takes care of executing the async function on page load for you. - -![How to set run on page load for async function?]() - -As shown in the screenshot below, you can see that the `showData` function is called **on page load**, and `Table1` displays the data. - -![Data displayed in the table widget](/img/Show-Data-Data-Displayed-InTable.png) - -### CONFIRM BEFORE CALLING - -With this setting, you can generate a confirmation pop-up and take the user’s input for executing the function. For example, the JS object has the function `deletePermission` which calls an API that deletes the database’s permission. You would want to ensure that the user wants to delete permission, in which case, you would like to show a confirmation dialog. The confirmation dialog ensures that the user wants to perform a delete action. A user can choose **Yes** to delete or can decline the same by choosing **No**. Thus, `Confirm Before Calling` comes in handy to protect against users accidentally running destructive operations. - -![A confirmation dialog is shown to the user before execution on myFun2]() - -#### Configure confirm before calling - -Confirmation is like a nudge given to the user before executing a function. It ensures that the user is aware of the action that would be performed, and the same is not triggered by chance. A confirmation setting can only be defined explicitly from the Settings tab. - -Navigate to **JS Object** —> Click **Settings** —> Select **Yes** for **CONFIRM BEFORE CALLING** next to the JS function. You are all set. Appsmith takes care of executing and showing the confirmation dialog to the user whenever the action is triggered. - -![Configurations for CONFIRM BEFORE CALLING]() - -## When to use Asynchronous settings - -Asynchronous function settings enable users to create complex workflows by executing functions before the application loads, allowing the data manipulation logic to run and make the desired outcome— secure function execution with a confirmation before you want application users to execute any critical operations. - -Let’s understand the settings deeper with examples. - -For example, you would want to apply restrictions in your application based on the user’s domain. That is, anonymous users (users who are not a part of your domain) cannot access certain application pages. You can quickly implement this by creating a function that uses the asynchronous function setting- Run on page load. - - - - -Here’s a quick snapshot of steps that you can take to create this logic: - -* Create an application and add two pages. - * First Page (UserListingForAppsmithUsers)- Add a table, and rename it to `UserListing` which displays the data generated by the `showUserListing` function of the `DataLoader` JS object. The function generates a list of users. - * Second Page (AnonymousUser) - Displays a message to the user. -* Create a JS object `DataLoader` and add a function `showUserListing` _that checks whether the user is logged in or not_.\_ The function verifies the below logic: - * If the user is logged in, then the `GetUserList` API is called, and the response is generated - * If the user is not logged in or is not an Appsmith user, redirect the user to the `AnonymousUser` page. -* Mark function `showUserListing` of JS Object - DataLoader to run on page load by selecting **Yes**. - -**UserListingForAppsmithUsers** - DataLoader JS object Code. You can see that a function `showUserListing` is marked for asynchronous execution by defining the `async` keyword. - -``` -export default { - showUserListing: async () => { - //use async-await or promises - if(appsmith.user.isAnonymous) { - navigateTo("AnonymousUser"); - } - //verify if the logged-in user is from appsmith - if(appsmith.user.email.match("appsmith")){ - return GetUserList.run(); - }else{ - navigateTo("AnonymousUser"); - } - } -} -``` - -For logged-in appsmith users, a user listing is shown as the`GetUserList` API is executed: - -![The user listing is displayed to logged-in appsmith users](/img/LoggedIn-Appsmith-Users-User-Listing-Shown.png) - -**Anonymous users -** Whenever the application renders, the `showUserListing` function is executed. The function determines whether the user is anonymous. You can use the property of a user object `isAnonymous` to check the user's logged-in status. - -``` -appsmith.user.isAnonymous -``` - -![An anonymous user is shown the page with an unauthorized message](/img/Anonymous-Users.png) - -Suppose the user is **not** logged in, then `appsmith.user.isAnonymous` _returns `true` **and redirects** the user to the `AnonymousUser` page and displays the message._ - -:::info -You are not authorized to view user data. -::: - -If the user is **logged in** `appsmith.user.isAnonymous` returns `false` and the logic is executed to verify if the logged-in user is an Appsmith user. If the user is an Appsmith user, `GetUserList` API is called to fetch the user listing. The execution is completed, and the response is generated, displayed in the `UserListing` table. - -You can do authentication and authorization using the Async function settings. To get started, you can use one of the below applications: - -1. [View and fork the authentication application](https://app.appsmith.com/app/custom-auth-google-sso/login-62a99de284b91337251a7dd3) -2. [View and fork the authorization application](https://app.appsmith.com/applications/62a069e0e56c5566a628df0a/pages/62a069e0e56c5566a628df0d) - -With the out-of-the-box settings provided for async functions, you can manage the execution of your asynchronous functions and create a better user experience. diff --git a/website/docs/write-code/reference/README.md b/website/docs/write-code/reference/README.md index 0e4acbe31a..a8df366d7c 100644 --- a/website/docs/write-code/reference/README.md +++ b/website/docs/write-code/reference/README.md @@ -39,9 +39,9 @@ To know more about the objects and functions, refer to the resources below:
- Built-in JS Libraries + JS Libraries
-
Built-in JavaScript libraries provide a comprehensive array of capabilities for common tasks such as data manipulation, numeric operations, date and time handling, and more.
+
JavaScript libraries provide a comprehensive array of capabilities for common tasks such as data manipulation, numeric operations, date and time handling, and more.
diff --git a/website/docs/write-code/reference/overview.md b/website/docs/write-code/reference/overview.md index 883859e063..f84eae2006 100644 --- a/website/docs/write-code/reference/overview.md +++ b/website/docs/write-code/reference/overview.md @@ -1,48 +1,31 @@ # Reference -Technical descriptions and information about widgets and app settings. - - - -
Global Objects
-
Global objects like Appsmith object, Console object, and Query object enable users to execute database queries, share data between pages using parameters, gather information about the application's current state, and facilitate code debugging.
+
Global objects to access common information like query data, application context, and user information
Global Functions
-
The Appsmith framework allows triggering actions for widget events and inside JS Objects. There are functions to navigate to another page, show alert messages, open/close modals, and store data in local storage.
+
Common functions to trigger page navigate, show alert messages, open modals, and store data in browser storage
-
- Built-in JS Libraries + JS Libraries
-
Built-in JavaScript libraries provide a comprehensive array of capabilities for common tasks such as data manipulation, numeric operations, date and time handling, and more. These libraries can be accessed and used without the need for any additional installations or setup.
+
JavaScript libraries to simplify common tasks such as data manipulation, date handling, and more
Fetch API
-
The Fetch API provides an interface for executing network calls programmatically. You can use fetch() to programmatically configure and execute a REST API.
-
-
- - -
-
-
- Function Settings -
-
The asynchronous function allows you to choose when you want to execute code. For example, you may want to delay the query execution or fetch the data on demand.
+
Execute API calls from the browser using the fetch method
-
diff --git a/website/sidebars.js b/website/sidebars.js index 08c18a413e..09c879e0de 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -464,10 +464,6 @@ const sidebars = { label: 'How-To Guides', link: { type: 'doc', id: 'write-code/how-to-guides/README' }, items: [ - - 'core-concepts/writing-code/README', - 'core-concepts/writing-code/javascript-editor-beta/README', - 'write-code/how-to-guides/display-data-from-functions', 'core-concepts/writing-code/javascript-promises', 'advanced-concepts/sharing-data-across-pages', `core-concepts/writing-code/workflows`, @@ -488,9 +484,9 @@ const sidebars = { label: 'Global Objects', link: { type: 'doc', id: 'write-code/reference/README' }, items: [ + 'reference/appsmith-framework/query-object', 'reference/appsmith-framework/context-object', 'reference/appsmith-framework/console-object', - 'reference/appsmith-framework/query-object', ], }, { @@ -520,9 +516,9 @@ const sidebars = { ] }, + 'core-concepts/writing-code/javascript-editor-beta/README', 'write-code/reference/Built-in-JS-Libraries', 'write-code/reference/Fetch-API', - 'core-concepts/writing-code/javascript-editor-beta/asynchronous-javascript-function-settings', ], }, //Reference End diff --git a/website/vercel.json b/website/vercel.json index 4bbb211166..a295e1918e 100644 --- a/website/vercel.json +++ b/website/vercel.json @@ -1117,6 +1117,10 @@ { "source": "/getting-started/setup/upgrade-to-business-edition/upgrade-k8s-to-business-edition", "destination": "/getting-started/setup/upgrade-from-community-edition/kubernetes" + }, + { + "source": "/core-concepts/writing-code/javascript-editor-beta/asynchronous-javascript-function-settings", + "destination": "/core-concepts/writing-code/javascript-editor-beta" } ] } \ No newline at end of file