+
+## Connection types
+
+There are 2 kinds of data sources that do not require a connection instance:
+
+### Function
+
+
+
+You can define secrets (key/value) that can later be accessed in the function datasource query:
+
+
+
+### Fetch
+
+
+
+You can configure:
+
+- **base url** - url that can be shared between different queries.
+- **Headers** - pass custom headers with each request.
+- **Authentication** type - if your API is protected choose the authentication method that fits your needs:
+ - **Basic** - adds authorization header and generates base64 encoded value for a given user credentials.
+ - **Bearer token** - adds authorization header generates value for provided token.
+ - **API key** - adds key/value header.
+
+There are 2 datasources that require a connection instance:
+
+### Google Sheets
+
+**Obtain credentials**
+
+Before you create a Google Sheets connection you must first configure Toolpad app by providing Google Sheets **client ID** and **client secret**:
+
+1. Create a new Google Cloud project - [instructions](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).
+
+2. Generate Oauth 2.0 credentials - [instructions](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred).
+
+3. Start Toolpad with following environment variables:
+
+ ```sh
+ TOOLPAD_EXTERNAL_URL=
+
+1. Choose the Google account that you want to authorize.
+
+1. Grant access to your Google Drive files by clicking **Allow**.
+
+1. Once you successfully connect your account you should see a button stating the account that was connected.
+
+
+
+### PostgreSQL
+
+To query data from a PostgreSQL database, you must configure the connection:
+
+
+
+Provide the database credentials and click **TEST CONNECTION** to verify that you're able to connect.
+
+If everything is correct, click **SAVE** to complete the connection.
+
+Learn more in the [PostgreSQL documentation](/toolpad/connecting-to-datasources/postgre-sql/).
diff --git a/docs/data/toolpad/connecting-to-datasources/fetch.md b/docs/data/toolpad/connecting-to-datasources/fetch.md
new file mode 100644
index 00000000000..da094c3eb34
--- /dev/null
+++ b/docs/data/toolpad/connecting-to-datasources/fetch.md
@@ -0,0 +1,35 @@
+# Fetch datasource
+
+Fetch datasource is the easiest and fastest way to load external data within Toolpad app.
+ +## Working with fetch + +As explained in the [connections](/toolpad/connecting-to-datasources/connections/) section you can either create a reusable connection or simply create a new query and put all connection details inline: + +1. Choose **ADD QUERY** in the **Inspector** on the right. + +1. Select fetch datasource and click **CREATE QUERY**: + +
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configuration following properties inline:
+
+ 
+ + + - **HTTP method** - by default GET is used, but we also support POST, PUT, DELETE, PATCH and HEAD methods. + - **url** - is an endpoint to which requests will be made. We also have an option to dynamically generate url by using [data binding](/toolpad/data-binding/). **Parameters** can be accessed by using **query** object inside url data binding editor. + - **parameters** - allows us to use [data bound](/toolpad/data-binding/) properties which can then be used construct dynamic **url** value. + +
+
+1. Knowing that data comes in a different shapes we provide an easy way to **transform response**:
+
+ - Simply enable option by checking **Transform response**.
+ - Then modify which properties of data object should be returned as a final response.
+
+ 
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.
diff --git a/docs/data/toolpad/connecting-to-datasources/function.md b/docs/data/toolpad/connecting-to-datasources/function.md
new file mode 100644
index 00000000000..c577845c87b
--- /dev/null
+++ b/docs/data/toolpad/connecting-to-datasources/function.md
@@ -0,0 +1,65 @@
+# Function datasource
+
+Function datasource is an advanced way to make request from Toolpad app.
+ +## Working with functions + +As explained in the [connections](/toolpad/connecting-to-datasources/connections/) section you can either create a reusable connection or simply create a new query and put all connection details inline: + +1. Choose **ADD QUERY** in the **Inspector** on the right. + +1. Select function datasource and click **CREATE QUERY**: + +
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you are now presented with a **code editor** where you can write a custom code for data fetching:
+
+ 
+
+ Supported features:
+
+ - Subset of webplatform APIs:
+
+ - fetch (Request, Response)
+ - AbortController
+ - console (.log, .debug, .info, .warn, .error)
+ - setTimeout, clearTimeout
+ - TextEncoder, TextDecoder
+ - ReadableStream
+
+ - Access outside variables by binding parameters fields.
+ - Console and Network tabs for an easier debugging.
+
+ Current limitations:
+
+ - You can not import modules.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.
+
+## Use cases
+
+While [function](/toolpad/connecting-to-datasources/function/) datasource can suffice for many different setups we found some advances use cases where limitations of function datasource starts surfacing and prevents us from building more complex data access queries.
+
+1. **Pre-processing** request:
+
+ You can execute extra steps before doing an actual request in case you need to do some pre-processing. I.e. sending parameters as a BASE64 encoded data:
+
+ 
+
+1. **Fetching** data from **multiple data sources** and **combining** the result:
+
+ 
+
+1. **Chaining** multiple request:
+
+ In this example you might want to fetch name of the top contributor of **mui/materual-ui** repository, in order to do that you first need to fetch a list of contributors for a given repo. Once you have a response and link to a top contributor you can do a follow up request to fetch details about specific user:
+
+ 
+
+1. **Custom error handling**:
+
+ You can handle different error scenarios. I.e. if 404 error is returned you can still pass empty array so that UI does not break:
+
+ 
diff --git a/docs/data/toolpad/connecting-to-datasources/google-sheets.md b/docs/data/toolpad/connecting-to-datasources/google-sheets.md
new file mode 100644
index 00000000000..43946e9aa23
--- /dev/null
+++ b/docs/data/toolpad/connecting-to-datasources/google-sheets.md
@@ -0,0 +1,29 @@
+# Google Sheets datasource
+
+Google Sheets datasource allows fetching data from Google Sheets living in your Google Drive.
+ +## Working with Google Sheets + +1. Create a new Google Sheets connection as explained in the [instructions](/toolpad/connecting-to-datasources/connections/#google-sheets). + +1. Once your connection is ready click on **ADD QUERY** in the **Inspector** on the right. + +1. Select Google Sheets datasource and click **CREATE QUERY**: + +
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configure following properties inline:
+
+ 
+
+ - **Select spreadsheet** - browse for a spreadsheet that you own or that is shared with you.
+
+ - **Select sheet** - choose a spreadsheet's sheet from which you want to pull the data.
+
+ - **Range** - select a range of cells from which the data should be pulled.
+
+ - **First row contains column headers** - enable this setting if you would like to use names defined in a header row as the name for object keys in a response.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.
diff --git a/docs/data/toolpad/connecting-to-datasources/postgre-sql.md b/docs/data/toolpad/connecting-to-datasources/postgre-sql.md
new file mode 100644
index 00000000000..fa2108a7ca4
--- /dev/null
+++ b/docs/data/toolpad/connecting-to-datasources/postgre-sql.md
@@ -0,0 +1,31 @@
+# PostgreSQL datasource
+
+PostgreSQL datasource allows fetching data straight from PostgreSQL database.
+ +## Working with PostgreSQL + +1. Create a new PostgreSQL connection as explained in the [instructions](/toolpad/connecting-to-datasources/connections/#postgresql). + +1. Once your connection is ready click on **ADD QUERY** in the **Inspector** on the right. + +1. Select PostgreSQL datasource and click **CREATE QUERY**: + +
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configure following properties inline:
+
+ 
+
+ - On the left is a SQL query editor.
+
+ - On the right is a table for previewing results.
+
+ - Below the query editor you can configure parameters which can be used to bind page state to your SQL query. Toolpad uses [prepared statements](https://www.postgresql.org/docs/current/sql-prepare.html) under the hood to prevent SQL injection. You can use the positional parameter syntax (`$1`, `$2`, `$3`) of postgres prepared statements. Additionally it will also accept named parameters of the form `$myParameter`.
+
+ 
+
+ Like so: `SELECT * FROM "db" WHERE name = $name`.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.
diff --git a/docs/data/toolpad/connecting-to-datasources/queries.md b/docs/data/toolpad/connecting-to-datasources/queries.md
new file mode 100644
index 00000000000..3acc1792ce0
--- /dev/null
+++ b/docs/data/toolpad/connecting-to-datasources/queries.md
@@ -0,0 +1,28 @@
+# Queries
+
+Toolpad allows you to easily connect to external datasources and render dynamic data. The easiest way to do so is to create a new query which can be used to fetch data.
+ +1. Locate **ADD QUERY** button in the **Inspector** on the right: + +
+
+2. There are currently 4 different datasources\* that can be used to fetch data:
+
+ 
+
+ - [Function](/toolpad/connecting-to-datasources/function/) - advanced fetching methods which gives a lot of freedom by allowing to write custom fetching code.
+ - [Fetch](/toolpad/connecting-to-datasources/fetch/) - basic, but very powerful. Just pass URL of an API endpoint and you are ready to query your data.
+ - [Google Sheets](/toolpad/connecting-to-datasources/google-sheets/) - allows accessing data from your Google sheet document.
+ - [PostgreSQL](/toolpad/connecting-to-datasources/postgre-sql/) - ability to hook directly into your own DB without the need to use API.
+
+ \* - by default you will see only **Function** and **Fetch** datasources, for **Google Sheets** and **PostgreSQL** you will first need to create a [CONNECTION instance](/toolpad/connecting-to-datasources/connections/).
+
+3. After choosing the **QUERY** datasource and clicking **CREATE QUERY** you will be presented with a query configuration dialog (configuration settings for each individual type are documented on their respective pages).
+
+ There are a few configuration options that are applicable to every query type:
+
+ 
+
+ - **Refetch on window focus** - execute the query every time the window is focused to make sure you always have the latest data visible.
+ - **Refetch on network reconnect** - execute the query every time the network status changes.
+ - **Refetch interval** - you can configure the query to run on an interval, e.g. **every 30s**. To disable this option, keep the field empty.
diff --git a/docs/data/toolpad/data-binding.md b/docs/data/toolpad/data-binding.md
new file mode 100644
index 00000000000..981161b73ec
--- /dev/null
+++ b/docs/data/toolpad/data-binding.md
@@ -0,0 +1,53 @@
+# Data binding
+
+Data binding is a widely used concept inside Toolpad app which allows connecting various parts of the application and make them dynamically react to data changes.
+ +## Binding button + +In order to initiate data binding look around in the UI for a binding button. + +
+
+The easiest way to tell if a value can be "data bound" is by locating binding button, i.e. TextField component allows us to bind every property that we could otherwise control manually.
+
+
+
+## Binding editor
+
+Upon clicking **binding button** you will be presented with binding editor which allows you to define JavaScript expression.
+
+At the top of the editor you can see an explanation what type of property we expect to be defined (i.e. above mentions string).
+
+
+
+On the left side of the editor you have a list of all the variables in the scope that can be used to define the expression.
+
+You can either simply pass a path to a property of the object or you can also use any other JavaScript expression or code snippet to additionally process the value that is going to be used.
+
+
+
+All that's left is to click **UPDATE BINDING** and you can observe how application behaves.
+
+(In this example you can see TextField value bound to the value of Typography component).
+
+Empty field:
+
+
+
+Field with value:
+
+
+
+## Global scope variables
+
+Sometimes you might want to define custom variables that could be used for data binding in order to do that you can use **EDIT PAGE MODULE** functionality that can be found in the **Inspector** on the right:
+
+
+
+You will be presented with an editor where you can define any number of variables:
+
+
+
+Once you **SAVE** the changes you can use those variables to bind value of any property:
+
+
diff --git a/docs/data/toolpad/data-fetching/google-sheets.md b/docs/data/toolpad/data-fetching/google-sheets.md
deleted file mode 100644
index eff68bd7aa6..00000000000
--- a/docs/data/toolpad/data-fetching/google-sheets.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Google Sheets
-
-Google Sheets data source.
- -## Setup Google Cloud - -Google Cloud Platform allows us to authorize third-party applications to access files (docs, sheets, photos, etc.) in our Google Drive. -Below are the steps to create a Toolpad application that can be given permission to access your Google Drive folder using OAuth. - -You need to enable Google Login to connect Google Sheets. If you're an existing user, you can sign in to [Google Console](https://cloud.google.com/) or create a new account. - -1. The first step would be to [create a new Google Cloud project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project). - -2. You need valid Google Oauth 2.0 credentials, specifically a Client ID and a Client Secret, to set - this datasource up. Follow the instructions [here](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred) to generate these credentials. - -3. You will need the following environment variables to setup the datasource: - - ```sh - TOOLPAD_EXTERNAL_URL=Fetching data into a Toolpad app.
- -In order to be able to display external data, Toolpad needs to be able to connect to a datasource and execute queries against it. -Toolpad allows you to connect to REST APIs and Google Sheets. - -## Data sources - -A Toolpad app can connect to different data sources. -To create this connection, click the "+" button next to "connections" in the left menu. -A popup will open where you can pick the type of connection you want to make. - -Choose a connection type and click "create". The connection editor will open where you can configure the necessary paramaters for this connection. - -- [REST](/toolpad/data-fetching/rest/) -- [Google Sheets](/toolpad/data-fetching/google-sheets/) diff --git a/docs/data/toolpad/data-fetching/queries.md b/docs/data/toolpad/data-fetching/queries.md deleted file mode 100644 index 17386bd2a95..00000000000 --- a/docs/data/toolpad/data-fetching/queries.md +++ /dev/null @@ -1,15 +0,0 @@ -# Queries - -Query data inside a Toolpad app.
- -To make external data available on a page, you can define a query. -To do so, deselect all elements in the page to make the page options visible. Click "Add query". -A popup opens that asks you to select one of the connections you have defined. -After you click "create query" you'll be presented with a popup where you can set up the query that should run against the connection. - -You'll also have access to a some options that influence the query behavior: - -- **Refetch on window focus**: Rerun the query every time the window is focused to make sure you always have the latest data visible. -- **Refetch on network reconnect**: Rerun the query every time the network status changes. -- **Refetch interval**: You can configure the query to run on an interval, e.g. every 30s. To disable this option, just empty the field. -- **Transform response**: Use this to post process the data before it gets sent to the client. You'll have to define a function body that has parameter `data` which is the raw result as it comes from the data source. You're expected to return the transformed `data`. diff --git a/docs/data/toolpad/data-fetching/rest.md b/docs/data/toolpad/data-fetching/rest.md deleted file mode 100644 index 33c1be91332..00000000000 --- a/docs/data/toolpad/data-fetching/rest.md +++ /dev/null @@ -1,9 +0,0 @@ -# REST API - -Connect to any REST API from a Toolpad app.
- -Toolpad comes with a default REST API That you can use to make all purpose API calls. You can set up a connection to a REST API where you can configure a base URL, headers, authentication. In order to use API headers, one must define a base url. - -- **No authentication**: The default -- **Basic authentication**: Allows you to set a username and a password which will eb automatically encoded for you in a `Authorization` header. -- **Bearer authentication**: Allows to configure a token that will be used in the `Authorization` header. e.g. to configure an access token for OAuth. diff --git a/docs/data/toolpad/getting-started/overview.md b/docs/data/toolpad/getting-started/overview.md new file mode 100644 index 00000000000..8d782d7a71d --- /dev/null +++ b/docs/data/toolpad/getting-started/overview.md @@ -0,0 +1,29 @@ +# Overview + +Toolpad is a low-code UI builder for creating apps with MUI's suite of component libraries.
+ +## Introduction + +Toolpad is a self-hosted low-code internal tools builder designed to extend MUI's suite of React components. +It's designed for developers of all trades who want to save time building internal applications. +Drag and drop pre-built UI components, connect your data sources, release your app, and you're done! + +
+
+## Advantages of Toolpad
+
+- **Build faster than ever before:** measure your development time in minutes rather than hours or days—simply drag and drop the components you need.
+- **Extensible with code:** build low-code with pro-code extensibility. You can write JavaScript anywhere in Toolpad as soon as you feel limited by the built-in features.
+- **Connect to any data source:** Toolpad lets you work with HTTP endpoints, Google Sheets, or PostgreSQL for backend functionality.
+
+## Toolpad terminology
+
+
+
+These are the primary elements of the Toolpad interface:
+
+- **Navigation**: where you can return to the homepage, or preview or deploy your app.
+- **Explorer**: where you can define and manage pages, connection configurations, custom component definitions, and more.
+- **Component library**: where you can find components to drag and drop onto the Canvas.
+- **Canvas**: where you build the UI for your application.
+- **Inspector**: where you can inspect and modify properties of selected elements in the canvas.
diff --git a/docs/data/toolpad/getting-started/quickstart.md b/docs/data/toolpad/getting-started/quickstart.md
new file mode 100644
index 00000000000..aa2e1966e2f
--- /dev/null
+++ b/docs/data/toolpad/getting-started/quickstart.md
@@ -0,0 +1,148 @@
+# Quickstart
+
+Learn the fundamentals of building with Toolpad by creating and deploying a simple application.
+ +This guide will walk you through the process of creating a basic Toolpad application. +You'll use the MUI X DataGrid component to display a list of dog breeds from the [Dog API](https://dog.ceo/dog-api/). +When you click on the name of a breed, its photo will be displayed using the Material UI Image component. + +## Purpose + +This Quickstart guide is intended to introduce you to the fundamentals of building with Toolpad. +By the end, you should be able to: + +- set up a new Toolpad app +- navigate through your workspace +- add components, data sources, and queries to an app +- bind data sources and components +- deploy a Toolpad app + +## Prerequisites + +This guide assumes that you have [Docker](https://www.docker.com/) installed on your machine. + +Make sure you have a running Toolpad instance. + +1. Download the docker compose file + + ```sh + curl -LO https://raw.githubusercontent.com/mui/mui-toolpad/master/docker/compose/docker-compose.yml + ``` + +1. Start the docker compose services + + ```sh + docker-compose -f docker-compose.yml up -d + ``` + +Toolpad will be accessible under `http://localhost:3000/`. + +## Building your first application + +### Create a new app + +1. Open Toolpad by navigating to [http://localhost:3000/](http://localhost:3000/). It should look like this: + +
+
+1. Click **CREATE NEW** and name your application. Confirm by clicking **CREATE**. You'll then be taken to the workspace for your new app, which looks like this:
+
+ 
+
+### Assemble the UI
+
+1. Hover over **Component library** and drag DataGrid and Image components into **Canvas**
+
+ 
+
+ Congratulations, you are done building the UI! Now all you need to do is connect it with a data source.
+
+1. Click anywhere inside **Canvas** (except on the components that you just added) to deselect added components
+
+1. Locate **ADD QUERY** button inside **Inspector** and press that to start configuring our data source
+
+ 
+
+1. This time you are going to use simple fetch datasource to query your data. Choose and press **CREATE QUERY**
+
+ 
+
+1. Fetch some data about dogs from `https://dog.ceo/dog-api`:
+
+ Use `https://dog.ceo/api/breeds/list/all` as a GET query **URL**
+
+ Give a unique name to this query i.e. **dogQuery**
+
+ 
+
+1. Now because data comes in different shapes and forms you can provide a quick and convenient way to **transform response** data - **enable** option and use `return data.message` expression
+
+ 
+
+ In the response preview pane on the right you can see transformed data will be assigned to `dogQuery`
+
+1. **SAVE** your changes and you will return to **Canvas**
+
+1. Select DataGrid component by clicking on it
+
+1. Then locate rows binding button in the **Inspector** and click to configure data binding
+
+ 
+
+1. Use a `dogQuery` variable available in the scope as a binding expression. Because rows property expects array type value, you first need to convert `dogQuery.data` (which is object) to array:
+
+ ```js
+ Object.entries(dogQuery.data);
+ ```
+
+ and click **UPDATE BINDING**
+
+ 
+
+1. You have finally connected data source to your UI component!
+
+ 
+
+1. You can make your app a bit more interactive by displaying an image of a selected breed. Create a dynamic query which reacts to the selection inside DataGrid component
+
+ - **ADD QUERY** -> create fetch type
+ - **name** -> **imageQuery**
+ - Add new parameter named **breed**
+
+ 
+
+ - Bind breed parameter value to `dataGrid.selection ? dataGrid.selection[0] : 'akita'` (grabs selected value from `dataGrid` or defaults to akita breed)
+
+ 
+
+ - Then bind query **url** property to `https://dog.ceo/api/breed/${query.breed}/images/random`
+
+ 
+
+ - Last **transform responese** using `return data.message;` and click **SAVE**
+
+1. Next you want to display a picture of a selected breed using Image component
+
+ - select Image component
+
+ - bind **src** prop to `imageQuery.data` and now you can preview pictures of a selected breed
+
+ 
+
+ Congratulations! 🎉 You now have an app fetching data from remote source and reacting to the user input!
+
+## Deploying your application
+
+In order to share your application with others you will want to deploy it
+
+1. Click **DEPLOY** button in the top navigation:
+
+ 
+
+1. (Optional) Enter **description** of your choice
+
+1. Click **DEPLOY** to confirm.
+
+ 
+
+Once deployed, the app will automatically open in a new browser tab.
diff --git a/docs/data/toolpad/getting-started/setup.md b/docs/data/toolpad/getting-started/setup.md
deleted file mode 100644
index 6068612cd6f..00000000000
--- a/docs/data/toolpad/getting-started/setup.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Setup
-
-Set Toolpad up locally.
- -## docker-compose - -The easiest way to run Toolpad locally is through docker-compose. - -**NOTE: Toolpad is in preview, do not run this in production.** - -### Prerequisites - -Make sure you have the following tools installed: - -- Docker -- docker-compose -- git - -### Steps - -1. Download the docker compose file - - ```sh - curl -LO https://raw.githubusercontent.com/mui/mui-toolpad/master/docker/compose/docker-compose.yml - ``` - -1. Start the docker compose services - - ```sh - docker-compose -f docker/compose/docker-compose.yml up -d - ``` - -Toolpad will be accessible under `http://localhost:3000/`. - -## Heroku - - diff --git a/docs/data/toolpad/getting-started/tutorial.md b/docs/data/toolpad/getting-started/tutorial.md deleted file mode 100644 index 3cc5b59355b..00000000000 --- a/docs/data/toolpad/getting-started/tutorial.md +++ /dev/null @@ -1,73 +0,0 @@ -# Tutorial - -Get started building a Toolpad app!
- -This page will guide you into creating your very first Toolpad application. We will create a "hello world" type of application that will ask for a name and print a greeting. - -## Prerequisites - -Make sure you have a running Toolpad instance. If you don't know how to do that, please follow the [setup instructions](/toolpad/getting-started/setup/). - -## Building your first application - -1. Open Toolpad by navigating to [http://localhost:3000/](http://localhost:3000/) if you went through the docker setup, or otherwise, the URL Toolpad is hosted under. You'll be presented with an overview screen with all the applications available. If you've started from a fresh instance, there should be none present. - -  - -1. Click "create new" and choose a name for your application in the popup, then click "create". This will create a new Toolpad application and the page will navigate to the application editor. - -  - -1. In the left navigation bar, you will see all the objects that are present in this application. You'll see "connections", which represent credentials needed to connect to a data source. "APIs" allow you to query your data and make it available to pages. Next to the "pages" entry click + the icon to add a new page, give it a name, and click "create". The page designer will open. - -  - -1. You are now in the page designer. You can access the components catalog by hovering over the bar on the left side containing the word "components". When the catalog folds out, grab a "TextField" and drag it into the canvas over the green box that says "insert here". When the box highlights, drop the TextField. An MUI TextField will now appear on the page canvas and the component properties editor opens. This input will be used to enter the name of the person we want to greet. In the component editor, change the name to "nameInput". We will use this name, later on, to refer to this TextField, so that we can bind properties to their value. - -  - -1. Open the component catalog again and drag a "Typography" component on the page. This will contain our greeting. In the component editor on the right-hand side, locate the text field for the "value" property. Try typing in this field. You'll notice the text on the screen changes. We can also make this value dynamic. To do this, click the link icon to the right of the text field to open the binding editor. - - In the binding editor, you can write any JavaScript expression. For instance, try typing the javascript string `'Hello everybody!'` and click "update binding". You'll notice that the text on the screen changes to "Hello everybody!". - - Now, change the JavaScript expression to `` `Hello ${nameInput.value}!` ``. Notice how we refer to our textField by the name "nameInput" that we set before. Now click "update binding" and close the binding editor. - -  - -1. Select the TextField and try typing your name. See how the Text follows? - -  - -## Deploying your first application - -Now that we have our first simple application, let's make sure we can use it outside of the editor. We will deploy our application under a stable URL. - -1. The first thing we need to do is to create a release for our application. When you create a release, the current state of the application is captured as a snapshot and stored. This snapshot will never change, we will always be able to access this snapshot and see the state of the application at the time that we took the snapshot. To create a release, click the launch icon in the top right corner of the menu bar. In the dialog that opens, write "Initial release" in the description field and click "create". You will be directed to the release's page. Here you'll get a list of all the pages present in this release. Go ahead and click the "open page" icon to see what your released page looks like. - -  - -1. You just created a versioned release of your application. Click the "deploy" button to host this version under the production URL of your page. Navigate to Toolpad home to get an overview of your application and click the "open" button on the application you just deployed. You'll be presented with an overview of the pages available in this application. Click on a page to see the production version of the application. - - Now, go back to editing your application and change the binding of the Typography component to `` `Goodbye ${state.nameInput.value}!` ``. Create another release. After you've verified that the pages in this release are working correctly, click "deploy" to make this release the production version of your application. - -## Data fetching - -A Toolpad aplication wouldn't be useful if you couldn't import your data into it. - -1. the first step is to make a connection to your data source. The connection holds the necessary credentials. In the case of a database, this may be the connection string, or in the case of a REST API this may contain an API token. For demo purposes, we will just create a dummy connection that we can use to make public HTTP requests. To get started, click on the plus button next to "Connections" in the left menu. In the popup that opens, select the "Fetch" type and click "create". In the window that opens, give your connection a name "ourData". - -  - -1. Now that we can connect to our data source, we can make an API endpoint for it on the Toolpad application. Click the plus button next to "Apis" in the left menu and select the "ourData" connection that we will make an API for. In the editor that opens, give it a name "ourDataApi" and in the url fill in `https://gist.githubusercontent.com/Janpot/c9d1f00be8472f2a510680b7e716a43b/raw/f001e0c3c501f5a0da35474ba4854cfc69acfd78/sample-data.json`. This contains a sample dataset for us to use. If everything went well, you will see a preview in the bottom half of the page. Click "update" to accept the parameters for this API. - -  - -1. Now we need to bring this data to our page. To do this, make a new page and click the "create query state" button in the page properties. In the popup that opens, give the state a name "ourDataState" and select the API we created before. We now have the data from this API available on the page in a variable `ourDataState` and we can bind it to components on the page. - -  - -1. Now add a DataGrid on the page and in its properties click the link button next to "DataQuery". This will open our trusty binding editor in which you can type `ourDataState` and click "update binding". Close the binding editor to see the result. - -  - -Read our deep dive into data fetching in the [data fetching documentation](/toolpad/data-fetching/). diff --git a/docs/pages/toolpad/connecting-to-datasources/connections.js b/docs/pages/toolpad/connecting-to-datasources/connections.js new file mode 100644 index 00000000000..ffa83bfe688 --- /dev/null +++ b/docs/pages/toolpad/connecting-to-datasources/connections.js @@ -0,0 +1,11 @@ +import * as React from 'react'; +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import { + demos, + docs, + demoComponents, +} from '../../../data/toolpad/connecting-to-datasources/connections.md?@mui/markdown'; + +export default function Page() { + return