docs - notes on actions (#29576) (#29579)

Co-authored-by: Jeff Bruemmer <jeff.bruemmer@gmail.com>

docs/actions/custom.md

@@ -17,9 +17,65 @@ There are two ways to create a custom action:
 1. Click the **+ New** > **Action**. When you save your action, you'll be prompted to associate that action with a model. (NOTE: the **Action** option will only show up in the **+ New** menu if you've first created, or have access to, a [model](../data-modeling/models.md) in Metabase.)
 2. Via the model detail page: from a model, click on the **info** button in the upper right. In the upper right of the sidebar, click **Model detail** > **Actions** > **New action**.
 
-In the action editor, you can write your own code to create an action, like writing an action that would only update a subset of the columns in a table.
+In the action editor, you can write your own code to create an action, like writing an action that would only update a subset of the columns in a table. See [Example actions](#example-custom-actions).
 
-## Example `UPDATE` action
+## Field types for action variables
+
+For each {% raw %}{{ variable }}{% endraw %} that you set in an action, you'll need to set the field type.
+
+Each of these variable field types present different options. Click on the gear icon to change options.
+
+If you don't require a variable, you can optionally specify a default value for Metabase to use in cases where people don't fill out the field. In the SQL code, remember to enclose any optional variables and commas in brackets, like `{% raw %}[[, column = {{ optional_variable }}]] {% endraw %}`.
+
+You can include placeholder text for all fields in the action form.
+
+**Text**
+
+- Text
+- Long text
+- Dropdown
+- Inline select
+
+**Number**
+
+- Number
+- Dropdown
+- Inline select
+
+**Date**
+
+- Date
+- Date + Time
+
+For both **Dropdown** and **Inline select**, you can specify a list of options to present on the form, with each option on its own line.
+
+![Dropdown select](./images/dropdown.png)
+
+## Appearance
+
+The appearance tab in the action editor modal will display a preview of the variable's form element. In the image below, we've clicked on the variable's **gear** and set the variable to use a text > dropdown list. The appearance section gives a preview for what the form element would look like:
+
+![Appearance gives a preview of the form element](./images/appearance.png)
+
+## Action settings
+
+From the model detail page, click on the **three dot menu** (...) next to the action. Once in the action editor, click on the **gear** icon to bring up the action settings.
+
+### Make public
+
+Creates a publicly shareable link to the action form. Anyone with access to that link can fill out the form and run the action. Useful for creating surveys.
+
+![Public action form](./images/public-form.png)
+
+### Set a success message
+
+Here you can edit the success message, which is the message Metabase will display in the toast that pops up after Metabase hears back from the database that everything went smoothly.
+
+If something goes wrong, Metabase will display the error message it received from the database.
+
+## Example custom actions
+
+### Example `UPDATE` action
 
 You could write an action that would update the `plan` column for a record in the `invoices` table in the Sample Database:
 
@@ -39,7 +95,7 @@ The code in brackets `[[ ]]` makes the statement optional: the bracket-enclosed
 
 ![Example action form](./images/form.png)
 
-## Example `INSERT` action
+### Example `INSERT` action
 
 Insert statements are pretty straightforward:
 
@@ -93,7 +149,7 @@ VALUES (
 {% endraw %}
 ```
 
-## Casting field values in actions
+### Casting field values in actions
 
 If you get a type error when you submit a form, you may need to `CAST` the data type in the query so it matches the data type of the target field in the database. Here we're casting a value to a `boolean`:
 
@@ -105,7 +161,7 @@ WHERE id = {{id}};
 {% endraw %}
 ```
 
-## Referencing saved questions in actions
+### Referencing saved questions in actions
 
 You can also reference saved questions in actions. Here we're taking the results of a `SELECT` statement on a saved question ("Potential customers") and inserting the results into a `people_to_write` table.
 
@@ -127,54 +183,6 @@ FROM prospects;
 {% endraw %}
 ```
 
-## Field types for action variables
-
-For each {% raw %}{{ variable }}{% endraw %} that you set in an action, you'll need to set the field type.
-
-Each of these variable field types present different options. Click on the gear icon to change options.
-
-If you don't require a variable, you can optionally specify a default value for Metabase to use in cases where people don't fill out the field. In the SQL code, remember to enclose any optional variables and commas in brackets, like `{% raw %}[[, column = {{ optional_variable }}]] {% endraw %}`.
-
-You can include placeholder text for all fields in the action form.
-
-**Text**
-
-- Text
-- Long text
-- Dropdown
-- Inline select
-
-**Number**
-
-- Number
-- Dropdown
-- Inline select
-
-**Date**
-
-- Date
-- Date + Time
-
-For both **Dropdown** and **Inline select**, you can specify a list of options to present on the form, with each option on its own line.
-
-![Dropdown select](./images/dropdown.png)
-
-## Action settings
-
-From the model detail page, click on the **...** next to the action. Once in the action editor, click on the **gear** icon to bring up the action settings.
-
-### Make public
-
-Creates a publicly shareable link to the action form. Anyone with access to that link can fill out the form and run the action. Useful for creating surveys.
-
-![Public action form](./images/public-form.png)
-
-### Set a success message
-
-Here you can edit the success message, which is the message Metabase will display in the toast that pops up after Metabase hears back from the database that everything went smoothly.
-
-If something goes wrong, Metabase will display the error message it received from the database.
-
 ## Further reading
 
 - [Introduction to actions](./introduction.md)

docs/actions/introduction.md

@@ -20,19 +20,18 @@ Here are a few ideas for what you can do with actions:
 - Let team members remove redundant data.
 - Create a customer feedback form and embed it on your website.
 
-Actions must be added to a [model](../data-modeling/models.md), but actions only run on the raw tables that back those models (so actions will never edit your [model definition](../data-modeling/models.md#edit-a-models-query).
+Actions must be added to a [model](../data-modeling/models.md), but actions only run on the raw tables that back those models (so actions will never edit your [model definition](../data-modeling/models.md#edit-a-models-query)).
 
-## Enabling actions
+## Enabling actions for a database
 
-To enable actions for a database connection, admins should click on the gear icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option.
+For actions to work, you'll first need to do the following two things:
 
-For actions to work, the database user account (the account you're using to connect to the database) must have write permissions. And for now, actions are only supported on PostgreSQL, MySQL, and H2 databases.
+1. **Enable model actions for the database connection**. To enable actions for a database connection, admins should click on the **gear** icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option. For actions to work, the database user account (the account you're using to connect to the database) must have write permissions. And for now, actions are only supported on PostgreSQL, MySQL, and H2 databases.
+2. **Create at least one model from that database.** Actions are associated with models, so you'll need to have created (or have access to) at least one model before you can start creating actions.
 
 ## Who can use actions
 
-Actions are associated with models, so you'll need to have created (or have access to) at least one model before you can start using actions.
-
-- **To create or edit an action**, a person must be in a group with Native query editing privileges for the relevant database.
+- **To create or edit an action**, a person must be in a group with [Native query editing](../permissions/data.md) privileges for the relevant database.
 - **To run an action**, all you need is view access to the action's model or dashboard (or a link to a public action).
 
 ## Types of actions

docs/developers-guide/start.md

@@ -43,3 +43,7 @@ This guide contains detailed information on how to work on Metabase codebase.
 ## Metabase documentation
 
 - [Developing Metabase documentation](./docs.md)
+
+## Releases
+
+- [Metabase release versioning](./versioning.md)