Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Feature/concepts #1870

Merged
merged 8 commits into from
Nov 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/styles/Google/Headings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -241,4 +241,7 @@ exceptions:
- console.log
- console.error
- console.warn
- Community
- Community
- Datasources (Server Data Models)
- Widgets (Views)
- Queries and JavaScript (Controllers)
34 changes: 33 additions & 1 deletion website/docs/build-apps/overview.md
Original file line number Diff line number Diff line change
@@ -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)

Check warning on line 5 in website/docs/build-apps/overview.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/build-apps/overview.md#L5

[Google.Headings] 'Datasources (Server Data Models)' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Datasources (Server Data Models)' should use sentence-style capitalization.", "location": {"path": "website/docs/build-apps/overview.md", "range": {"start": {"line": 5, "column": 5}}}, "severity": "WARNING"}

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)

Check warning on line 9 in website/docs/build-apps/overview.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/build-apps/overview.md#L9

[Google.Headings] 'Widgets (Views)' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Widgets (Views)' should use sentence-style capitalization.", "location": {"path": "website/docs/build-apps/overview.md", "range": {"start": {"line": 9, "column": 5}}}, "severity": "WARNING"}

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)

Check warning on line 13 in website/docs/build-apps/overview.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/build-apps/overview.md#L13

[Google.Headings] 'Queries and JavaScript (Controllers)' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Queries and JavaScript (Controllers)' should use sentence-style capitalization.", "location": {"path": "website/docs/build-apps/overview.md", "range": {"start": {"line": 13, "column": 5}}}, "severity": "WARNING"}

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

Check warning on line 19 in website/docs/build-apps/overview.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/build-apps/overview.md#L19

[Google.Headings] 'Reactive bindings' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Reactive bindings' should use sentence-style capitalization.", "location": {"path": "website/docs/build-apps/overview.md", "range": {"start": {"line": 19, "column": 5}}}, "severity": "WARNING"}

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.

<div class="containerGridSampleApp">
<div class="containerColumnSampleApp columnGrid column-one">
Expand Down
8 changes: 0 additions & 8 deletions website/docs/build-apps/reference/README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,7 @@

import DocCardList from '@theme/DocCardList';

# Reference

Technical descriptions and information about widgets and app settings.




<div class="containerGridSampleApp">
<div class="containerColumnSampleApp columnGrid column-one">
<div class="containerCol">
Expand All @@ -22,5 +16,3 @@ Technical descriptions and information about widgets and app settings.
<div class="containerDescription">Theme allows you to style your pages and widgets using global controls, making it easy to change the visual layout with a single click. </div>
</div>
</div>


7 changes: 0 additions & 7 deletions website/docs/connect-data/reference/overview.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,5 @@
# Reference

Technical descriptions and information about widgets and app settings.




<div class="containerGridSampleApp">
<div class="containerColumnSampleApp columnGrid column-one">
<div class="containerCol">
Expand All @@ -19,5 +14,3 @@ Technical descriptions and information about widgets and app settings.
<div class="containerDescription">This page is a reference guide that provides a description of all the settings available for configuring your queries. </div>
</div>
</div>


96 changes: 35 additions & 61 deletions website/docs/core-concepts/writing-code/ext-libraries.md
Original file line number Diff line number Diff line change
@@ -1,78 +1,61 @@
# Use External JS Libraries
# Use External JS Libraries

Check warning on line 1 in website/docs/core-concepts/writing-code/ext-libraries.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/core-concepts/writing-code/ext-libraries.md#L1

[Google.Title] 'Use External JS Libraries' should be in title case
Raw output
{"message": "[Google.Title] 'Use External JS Libraries' should be in title case", "location": {"path": "website/docs/core-concepts/writing-code/ext-libraries.md", "range": {"start": {"line": 1, "column": 3}}}, "severity": "WARNING"}

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.

<VideoEmbed host="youtube" videoId="xXssLXQvdyY" title="How To Use Custom JavaScript Libraries" caption="How To Use JavaScript Libraries"/>


## 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/[email protected]/dist/exceljs.min.js`

❌ Valid URL. Unsupported build format: `https://cdn.jsdelivr.net/npm/[email protected]/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

<VideoEmbed host="youtube" videoId="bo66yFTfy6Q" title="Installing custom JavaScript libraries" caption="Installing External JavaScript libraries"/>

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/[email protected]/dist/exceljs.min.js
```

- Click `Install`.
### Library compatibility

Check warning on line 25 in website/docs/core-concepts/writing-code/ext-libraries.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/core-concepts/writing-code/ext-libraries.md#L25

[Google.Headings] 'Library compatibility' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Library compatibility' should use sentence-style capitalization.", "location": {"path": "website/docs/core-concepts/writing-code/ext-libraries.md", "range": {"start": {"line": 25, "column": 5}}}, "severity": "WARNING"}

### 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/[email protected]/dist/exceljs.min.js`

### Examples
❌ Invalid URL: unsupported build format: `https://cdn.jsdelivr.net/npm/[email protected]/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

Check warning on line 46 in website/docs/core-concepts/writing-code/ext-libraries.md

View workflow job for this annotation

GitHub Actions / vale

[vale] website/docs/core-concepts/writing-code/ext-libraries.md#L46

[Google.Headings] 'Accessing installed libraries' should use sentence-style capitalization.
Raw output
{"message": "[Google.Headings] 'Accessing installed libraries' should use sentence-style capitalization.", "location": {"path": "website/docs/core-concepts/writing-code/ext-libraries.md", "range": {"start": {"line": 46, "column": 5}}}, "severity": "WARNING"}

#### 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', '[email protected]', {{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 () => {
Expand Down Expand Up @@ -104,15 +87,6 @@
};
```

## 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.
Loading