@@ -68,7 +71,7 @@ The canvas at the center of the editor is where you design and see the overall U
@@ -80,7 +83,46 @@ The canvas at the center of the editor is where you design and see the overall U
/>
-## Outputs
+## Connecting Components
+
+The strength of Windmill's app editor is the ability to connect everything together:
+- components can be linked to each other
+- components can be directly linked to scripts and trigger them
+- background runnables can be that are run in the background on app refresh on when an input changes
+- frontend scripts can be used to manipulate the client app state
+
+
+
+
+
+In Windmill's app editor:
+
+- the [runnable editor](#runnables-panel) catalogs and configures all the scripts present in the application
+- the [output panel](#outputs) lists the outputs of all the components and scripts in your application
+
+### Runnables panel
+
+On the bottom panel of the editor, you can see the list of runnables of the app. The runnables are the scripts or flows that are linked to components, or ran in the background. They are used to perform actions when a component is clicked, to fetch data, etc. They make all the interactions of the app.
+
+
+
+#### Learn more
+
+
+
+
+
+### Outputs
On the left panel of the editor, you can see the list of outputs of the app. These outputs represent the states & results of the app and are categorized into four types:
@@ -96,7 +138,7 @@ You can perform the following actions with the outputs:
- Search for an output.
- Edit the output's ID.
- Select a component to view its outputs.
-- [Connect an input to an output](../2_outputs.md#connecting-inputs).
+- [Connect an input to an output](../2_connecting_components/index.mdx).
#### Learn more
@@ -115,23 +157,6 @@ You can perform the following actions with the outputs:
/>
-## Runnables panel
-
-On the bottom panel of the editor, you can see the list of runnables of the app. The runnables are the scripts or flows that are linked to components, or ran in the background. They are used to perform actions when a component is clicked, to fetch data, etc. They make all the interactions of the app.
-
-
-
-#### Learn more
-
-
diff --git a/docs/apps/2_connecting_components/index.mdx b/docs/apps/2_connecting_components/index.mdx
new file mode 100644
index 000000000..8d7bb18bb
--- /dev/null
+++ b/docs/apps/2_connecting_components/index.mdx
@@ -0,0 +1,117 @@
+import DocCard from '@site/src/components/DocCard';
+
+# Connecting Components
+
+The strength of Windmill's app editor is the ability to connect everything together:
+- components [can be linked to each other](#connecting-inputs--outputs)
+- components can be directly [linked to scripts](../3_app-runnable-panel.mdx) and trigger them
+- [background runnables](../3_app-runnable-panel.mdx#background-runnables) can be that are run in the background on app refresh on when an input changes
+- [frontend scripts](../3_app-runnable-panel.mdx#evals) can be used to manipulate the client app state
+
+
+
+
+
+In Windmill's app editor:
+
+- the [runnable editor](#runnable-editor) catalogs and configures all the scripts present in the application
+- the [output panel](#outputs-panel) lists the outputs of all the components and scripts in your application
+- the [component settings](#component-configuration) allows for managing the inputs of the components as well as linking them to scripts.
+
+## Runnables & Outputs
+
+In order to connect the components, it is best to be familiar with the concepts of [Runnable](#runnable-editor) and [Output](#outputs-panel).
+
+### Runnable Editor
+
+On the bottom of the app editor, you can find the Runnable Editor. It allows you to create, edit, or manage the scripts or flows linked to components (runnables) and background runnables.
+
+
+
+The panel is structured as follows:
+
+- **Runnable list**: A list of all the runnables. Click on a runnable to select it.
+- **Runnable editor**: The editor of the selected runnable.
+
+Each script can have [inputs from other components](../3_app-runnable-panel.mdx#configure-triggers). The script will return [outputs](#outputs-panel) that can be used in other components.
+
+
+
+
+
+### Outputs Panel
+
+On the left panel of the editor, you can see the list of outputs of the app. These outputs represent the states & results of the app and are categorized into four types:
+
+- **Context**: The context holds information such as the user email, username, workspace, query parameters, and more.
+- **State**: The state holds the app's current state, which can be manipulated by the frontend scripts.
+- **Component Outputs**: These outputs correspond to the outputs of the individual components.
+- **Background Runnables**: These outputs represent the outputs of the background runnables.
+
+
+
+You can perform the following actions with the outputs:
+
+- Search for an output.
+- Edit the output's ID.
+- Select a component to view its outputs.
+- [Connect an input to an output](../2_connecting_components/index.mdx).
+
+
+
+
+
+### Component Configuration
+
+Each component can be configured individually. This allows for adjusting its value, behavior (especially by linking a script) to the component, and styling.
+
+
+
+
+
+## Connecting Inputs & Outputs
+
+Inputs (from scripts or components) can be connected to any outputs. When connecting, you can click on the output to connect the input to it. The data source will change to [eval](../3_app-runnable-panel.mdx#evals).
+
+Note that you can select nested outputs, objects and arrays.
+
+
+
+
+
+Here are the steps to connect an input to an output:
+
+- Click on the component input you want to connect to an output.
+- Click on the plug icon to open the connection menu, then:
+ - either click on the red plug directly next to the component, and pick the output
+ - or pick the component directly from the output menu on the left.
+- The input is now connected to the output through an eval.
+
+Alternatively, refer to the component directly through an [eval](../3_app-runnable-panel.mdx#evals), e.g. `a.result`.
+
+
\ No newline at end of file
diff --git a/docs/apps/2_outputs.md b/docs/apps/2_outputs.mdx
similarity index 81%
rename from docs/apps/2_outputs.md
rename to docs/apps/2_outputs.mdx
index 7cd85bc94..5833228cf 100644
--- a/docs/apps/2_outputs.md
+++ b/docs/apps/2_outputs.mdx
@@ -1,3 +1,5 @@
+import DocCard from '@site/src/components/DocCard';
+
# Outputs Guide
The outputs represent the states & results of the app.
@@ -8,14 +10,14 @@ All outputs can be found on the left-hand side of the app editor. There are thre
- Component outputs
- Background runnables outputs
-
+
When a component or a background runnable is selected, the outputs of the component or the background runnable are displayed.
You can manually open an output by clicking on the header of the output. Once manually opened, the output will stay open until you close it.
You can search for an output by typing in the search bar. It searches in the output name and in the output object keys, recursively.
-
+
### App context
@@ -34,7 +36,7 @@ The app state is a client-side store that can be used to store data. The app sta
Each component has its own outputs. The outputs are displayed in a tree structure. The tree structure is collapsible and can be expanded by clicking on the `{...}` button. Next to the button, you can see the number of outputs.
-
+
For example, the [Table component](./4_app_configuration_settings/table.mdx) has the following outputs:
@@ -44,26 +46,30 @@ For example, the [Table component](./4_app_configuration_settings/table.mdx) has
- search: the search value of the table
- selectedRowIndex: the selected row index
-
+
The outputs are used to quickly visualize the current state of the app.
### Containers
-Some components are "containers" and can contain other components. They are 4 types of containers:
-
-- Containers: Plain container that can contain other components
-- Tabs: Tabs that can contain other components
-- Horizontal split: Horizontal split that can contain other components
-- Vertical split: Vertical split that can contain other components
+Some components are "containers" and can contain other components.
The components contained in a container have their outputs displayed in the container outputs.
-
+
+
+
+
+
### Background runnables outputs
-A background runnable is a script or flow that runs in the background and can be used to perform actions that are not related to the UI.
+A [background runnable](./3_app-runnable-panel.mdx#background-runnables) is a script or flow that runs in the background and can be used to perform actions that are not related to the UI.
### Connecting inputs
diff --git a/docs/apps/3_app-runnable-panel.mdx b/docs/apps/3_app-runnable-panel.mdx
index 000cf0b3f..f512fd89f 100644
--- a/docs/apps/3_app-runnable-panel.mdx
+++ b/docs/apps/3_app-runnable-panel.mdx
@@ -1,12 +1,14 @@
import DocCard from '@site/src/components/DocCard';
-# Runnable Guide
+# Runnable Editor
-Windmill Apps can be powered by code, with scripts linked to components, background runnables that are not linked to a component but run in the background, frontend scripts that can be used to manipulate the client app state, and evals.
+The strength of Windmill's app editor is the ability to connect everything together:
+- components [can be linked to each other](./2_connecting_components/index.mdx)
+- components can be directly [linked to scripts](#inline-scripts) and trigger them
+- [background runnables](#background-runnables) can be that are run in the background on app refresh on when an input changes
+- [frontend scripts](#evals) can be used to manipulate the client app state
-## Overview
-
-On the bottom of the app editor, you can find the runnable editor. It allows you to create, edit, or manage the scripts or flows linked to components (runnables) and background runnables.
+On the bottom of the app editor, you can find the runnable editor. The runnable editor is a [code editor](../code_editor/index.mdx) that allows to create, edit, or manage the scripts or flows linked to components (runnables) and background runnables.
@@ -27,30 +29,44 @@ When a runnable is selected, the runnable editor is displayed. It is composed of
- **Runnable editor**: The code editor of the runnable.
+
+
+
+
## Types of runnables
There are 5 types of runnables:
- **Inline scripts**: Scripts that are defined on the app editor, linked to a component.
-- **Workspace/Hub**: Runnables (scripts; flows) linked to a component, but defined in the workspace or the Hub.
+- **Workspace/Hub**: Runnables (scripts; flows) linked to a component, but defined in the workspace or the [Hub](https://hub.windmill.dev/).
- **Background runnables**: Runnables that are not linked to a component, but run in the background.
- **Frontend scripts**: Scripts that can be used to manipulate the client app state. They can either be linked to a component or be a background runnable. If they are a background runnable, they are not executed unless manually set to run when the app starts or reloads.
- **Evals**: Evals are used to connect data sources to other components or parameters. They are only evaluated on changes to the outputs that have been identified.
They provide interactivity to your app.
-## Inline scripts
+### Inline scripts
Inline scripts are scripts that are defined on the app editor.
They can be either attached to a component or detached.
-## Background runnables
+### Frontend scripts
-Background runnables are scripts that are executed in the background. They are not attached to any component.
+Frontend scripts are scripts that are executed on the browser.
+
+### Background runnables
-## Evals
+Background runnables are scripts that are executed in the background. They are executed on the server.
+They can be triggered on app refresh or when their input changes. They are not attached to any component but their result can be shared among many components.
-Evals are used to [connect data sources](./2_outputs.md#connecting-inputs) to other components or parameters.
+### Evals
+
+Evals are used to [connect data sources](./2_connecting_components/index.mdx) to other components or parameters.
-Backend scripts are executed on the server and support the following languages:
+
-- Typescript
-- Python3
-- Go
-- Bash
+
+
+
-In addition, we also provide Typescript templates for common use cases:
+## Runnable Configuration
-- **PostgreSQL**: A script that connects to a PostgreSQL database and executes a query.
-- **HTTP**: A script that makes an HTTP request.
+The runnable configuration consists of:
-#### Frontend scripts
+- Hide refresh button: Some components have a refresh button. This can be hidden by checking this box.
+- Transformer: A transformer is a function that alters the output of the runnable, often used to format the output.
+- List of triggers: Configure whether the script runs on app start, app refresh, or whenever an input changes.
+- Runnable Inputs: The runnable inputs are [inferred from the inputs](../core_concepts/13_json_schema_and_parsing/index.md) of the flow or script parameters this component is attached to.
-Frontend scripts are scripts that are executed on the browser.
+
+
+### Transformer
+
+A [transformer](#transformer) is an optional frontend script executed immediately after the component's script. It's used to perform lightweight transformations in the browser. It accepts the previous computation's result as `result`.
+
+For instance, if component has a script that returns:
+
+```js
+{
+ data: {
+ name: 'John',
+ age: 20
+ }
+}
+```
+
+A transformer could be used to extract the data object:
+
+```js
+return result.data;
+```
+
+## Runnable Execution
+
+A component can have runnables attached to it. Depending on the component type, the runnables are executed at different times:
+
+- **Data source**: The runnable's result is used as the component's data source. It executes on app start and app refresh. For instance, if the component is a table, the runnable's result is used as the table's data source.
+- **Event handler**: The runnable executes when the event is triggered. For instance, if the component is a button, the runnable executes when the button is clicked.
+- **Validations**: Only the `Stepper` component has validations. The runnable executes when the step of the stepper changes.
+
+### Configure Triggers
+
+#### Run on Start and App Refresh
+
+Two types of runnables can be configured to run on app start and app refresh:
+
+- **Background runnables**: Runnables that are run in the background and aren't attached to a component.
+- **Component runnables used as data sources**: Runnables attached to a component and used as the component's data source.
+
+### Recompute on Any Input Change
+
+Runnables can be configured to recompute whenever an input changes. This is useful for recomputing a component's runnable when an input changes.
+
+Two types of runnables can be configured to recompute on any input change:
+
+- **Backend background runnables**: Background runnable that are executed on the server.
+- **Component runnables used as data sources**: Runnables attached to a component and used as the component's data source.
+
+Inputs of runnables that are either connected to an output or [evaluated](#evals) can trigger a recompute. These are displayed in the `Change on value` section.
+
+Runnables can "Recompute" and "Recompute others":
+- Recompute: Other component can trigger a component to recompute. For example, a button can trigger a table to recompute. When the button is clicked, the table is reloaded. See Recompute Others for more information.
+- Recompute others: Button and Form components can trigger other components to recompute. For example, a button can trigger a table to recompute. When the button is clicked, the table is reloaded.
+
+### Manual Dependencies
+
+Frontend scripts don't have any inputs. However, you can manually specify a frontend script's dependencies. This is useful when you want to recompute a frontend script when an input changes.
+
+Manual dependencies are found in the `Change on value` section and can be removed by clicking on the `x` button.
+
+## Cache app inline scripts
+
+Caching an app inline script means caching the results of that script for a certain duration. If the script is triggered with the same inputs during the given duration, it will return the cached result.
+
+
+
+
+
+You can enable caching for an app inline script directly its editor settings. Here's how you can do it:
+
+1. **Settings**: From the Code Editor, go to the top bar and pick the `Cache` tab.
+2. **Enable Caching**: To enable caching, toggle on "Cache the results for each possible inputs" and specify the desired duration for caching results (in seconds.)
+
+In the above example, the result of step the script will be cached for 5 minutes. If `Inline Script 0` is re-triggered with the same input within this period, Windmill will immediately return the cached result.
+
+
+
+
## Frontend scripts helpers
We expose a few functions and global objects to help you interact with the app from a frontend script.
-### Context
+#### Context
You can access the context object with the `ctx` global variable.
@@ -122,7 +235,9 @@ You can access the context object with the `ctx` global variable.
console.log(ctx.email);
```
-### State
+Context objects can be seen on the [Output menu](./2_outputs.mdx).
+
+#### State
The app state is a client-side store that can be used to store data.
@@ -138,17 +253,17 @@ You can update the state directly by manipulating the `state` object.
state.foo = 'bar';
```
-### goto
+#### goto
Use the `goto` function to navigate to a specific URL.
-#### Syntax
+##### Syntax
```js
goto(path: string, newTab?: boolean)
```
-#### Parameters
+##### Parameters
`path`
The URL to navigate to.
@@ -156,24 +271,24 @@ The URL to navigate to.
`newTab` (optional)
Whether to open the URL in a new tab or not.
-#### Example
+##### Example
```js
goto('/apps/1');
goto('https://www.windmill.dev/', true);
```
-### setTab
+#### setTab
Use the `setTab` function to manually set the tab of a Tab component.
-#### Syntax
+##### Syntax
```js
setTab(id: string, index: string)
```
-#### Parameters
+##### Parameters
`id` string
The tab to set.
@@ -181,159 +296,114 @@ The tab to set.
`index` string
The index of the tab to set.
-#### Example
+##### Example
```js
setTab('a', '1');
```
-### openModal
+#### openModal
Use the `openModal` function to open a modal.
-#### Syntax
+##### Syntax
```js
openModal(id: string)
```
-#### Parameters
+##### Parameters
`id` string
The id of the modal component to open.
-#### Example
+##### Example
```js
openModal('a');
```
-### closeModal
+#### closeModal
Use the `closeModal` function to close a modal.
-#### Syntax
+##### Syntax
```js
closeModal(id: string)
```
-#### Parameters
+##### Parameters
`id` string
The id of the modal component to close.
-#### Example
+##### Example
```js
closeModal('a');
```
-### recompute
+#### recompute
Use the `recompute` function to recompute a component.
-#### Syntax
+##### Syntax
```js
recompute(id: string)
```
-#### Parameters
+##### Parameters
`id` string
The id of the component to recompute.
-#### Example
+##### Example
```js
recompute('a');
```
-### getAgGrid
+#### getAgGrid
Use the `getAgGrid` function to get the ag-grid instance of a table.
-#### Syntax
+##### Syntax
```js
getAgGrid(id: string)
```
-### setSelectedIndex
+#### setSelectedIndex
Use the `setSelectedIndex` function to select a row in a table or an AG Grid table.
-#### Syntax
+##### Syntax
```js
setSelectedIndex(id: string, index: number)
```
-### setValue
+#### setValue
The `setValue` function is meant to set or force the value of a component. This can be convenient in cases where connection is not the easiest pattern.
Note that it's a bad idea to mix dynamic default value and setValue together.
-`setValue` supports the following components:
-
-- [Display](./4_app_configuration_settings/log_display.mdx)
-- [Date Input](./4_app_configuration_settings/date_input.mdx)
-- [Number Input](./4_app_configuration_settings/number_input.mdx)
-- [Currency Input](./4_app_configuration_settings/currency_input.mdx)
-- [Form Input](./4_app_configuration_settings/form_input.mdx)
-- [Toggle](./4_app_configuration_settings/toggle.mdx)
-- [Standalone Tab](./4_app_configuration_settings/select_tab.mdx)
-- [Standalone step](./4_app_configuration_settings/select_step.mdx)
-- [Range](./4_app_configuration_settings/range.mdx)
-- [Multi Select](./4_app_configuration_settings/multiselect.mdx)
-- [Text Input](./4_app_configuration_settings/text_input.mdx)
-- [Slider](./4_app_configuration_settings/slider.mdx)
-- [Select](./4_app_configuration_settings/select.mdx)
-- [Text](./4_app_configuration_settings/text.mdx)
-- [Rich Text Editor](./4_app_configuration_settings/rich_text_editor.mdx)
-
-#### Parameters
+##### Parameters
`id` string
-## Recompute
-
-Other component can trigger a component to recompute. For example, a button can trigger a table to recompute. When the button is clicked, the table is reloaded. See Recompute Others for more information.
-
-## Recompute others
-
-Button and Form components can trigger other components to recompute. For example, a button can trigger a table to recompute. When the button is clicked, the table is reloaded.
-
-## Cache app inline scripts
-
-Caching an app inline script means caching the results of that script for a certain duration. If the script is triggered with the same inputs during the given duration, it will return the cached result.
-
-
-
-
-
-You can enable caching for an app inline script directly its editor settings. Here's how you can do it:
-
-1. **Settings**: From the Code Editor, go to the top bar and pick the `Cache` tab.
-2. **Enable Caching**: To enable caching, toggle on "Cache the results for each possible inputs" and specify the desired duration for caching results (in seconds.)
+## Policy
-In the above example, the result of step the script will be cached for 5 minutes. If `Inline Script 0` is re-triggered with the same input within this period, Windmill will immediately return the cached result.
+A viewer of the app will execute the runnables of the app on behalf of the publisher avoiding the risk that a resource or script would not be available to the viewer. To guarantee tight security, a policy is computed at time of saving of the app which only allow the scripts/flows referred to in the app to be called on behalf of. Furthermore, static parameters are not overridable. Hence, users will only be able to use the app as intended by the publisher without risk for leaking resources not used in the app.
-
-
-## Policy
-
-A viewer of the app will execute the runnables of the app on behalf of the publisher avoiding the risk that a resource or script would not be available to the viewer. To guarantee tight security, a policy is computed at time of saving of the app which only allow the scripts/flows referred to in the app to be called on behalf of. Furthermore, static parameters are not overridable. Hence, users will only be able to use the app as intended by the publisher without risk for leaking resources not used in the app.
+ />
+