[weirdwater]

As discussed with @ConnorLand, the general description of Text Templates in !7745 will be applied to each property using it individually. I have written a template and applied it to the Text Widget's Caption property as an example.

The Template

<!-- TODO: Replace PARAMETER_NAME with the name of the parameter -->
<!-- TODO: Replace PARAMETER_SLUG with the url-safe name of the parameter -->
<!-- TODO: Replace WIDGET_NAME with the name of the widget -->

### X.X PARAMETER_NAME {#PARAMETER_SLUG}

<!-- TODO: Add the existing description of the property  -->

The **PARAMETER_NAME** supports dynamic text using templating. The final text is determined by the given [**Template**](#PARAMETER_SLUG-template), [**Parameters**](#PARAMETER_SLUG-parameters), and [**Fallback Text**](#PARAMETER_SLUG-fallback), which can be found in the 'Edit PARAMETER_NAME' dialog box. The dialog box can be opened in two ways:

* From the properties sidebar: double-click the property (for example, "Caption") or click the "more" ellipsis (...)
* From the widget properties dialog box: click the **Edit ...** button next to the property's textbox

{{< figure src="/attachments/refguide/modeling/pages/text-widgets/text/caption-edit-button.png" alt="Opening Parameters" width="450" >}}

#### X.X.1 Template {#PARAMETER_SLUG-template}

The **PARAMETER_NAME** can be made dynamic by placing placeholders in the **Template**. Placeholders must follow the format `{i}`, where _i_ is the **Index** of a specific parameter from the list of [parameters](#PARAMETER_SLUG-parameters). Parameters can be referenced multiple times, and can be referenced out of order.

#### X.X.2 Parameters {#PARAMETER_SLUG-parameters}

Parameters define what data is inserted into the template and how it is formatted. Parameters can refer to object attributes or expressions. Editing parameters is done in the 'Edit PARAMETER_NAME' dialog box.

Parameters have the following settings:

* **Index** – an identification number of a parameter 
* **Value** – an attribute or an expression value to be displayed
* **Format** – a format in which the value will be displayed (only for attributes)

{{< figure src="/attachments/refguide/modeling/pages/text-widgets/text/parameter-settings.png" alt="Parameter Settings" width="450" >}}

{{% alert color="info" %}}
You can use the formatter functions in the expression editor when using expressions. For more information, see [this list](/refguide/expressions/#expressions-formatter-functions).
{{% /alert %}}

##### X.X.2.1 Adding New Parameters

To be able to use parameters, the WIDGET_NAME must be in the context of an entity such as a [Data widget](/refguide/data-view), [Snippet parameter](http://localhost:1313/refguide/snippet/#parameters), or [Page parameter](/refguide/page-properties/#parameters). To use parameters, do the following:

1. Open the properties for the WIDGET_NAME.
1. Click the **Edit ...** button of the PROPERTY_NAME to open its dialog box.
1. In the **Parameters** section, click **New**:

    {{< figure src="/attachments/refguide/modeling/pages/text-widgets/text/adding-parameter.png" alt="Adding New Parameter"  width="450" >}}

1. In the **Edit Template Parameter** dialog box, click **Select**, choose an attribute, and confirm your choice.
1. Edit the template and add a placeholder that matches the index of your parameter (for example `{1}`).

In the example below, the placeholder `{1}` corresponds to the **Title** attribute, `{2}` to **NrOfPages**, and `{3}` to **DatePublished**:

{{< figure src="/attachments/refguide/modeling/pages/text-widgets/text/parameters-example.png" alt="Parameter Example"  width="450" >}}


##### X.X.2.2 Performing Other Actions on Parameters

In addition to adding new parameters, you can perform the following actions on parameters:

* **Delete** – to delete a parameter click **Delete** or press <kbd>Delete</kbd> on your keyboard
* **Edit** – double-click a parameter to edit it or click **Edit**
* **Move up** – to move a parameter up in the list of parameters and also to change its index, click **Move up**
* **Move down** – to move a parameter down in the list of parameters and also to change its index, click **Move down**

{{< figure src="/attachments/refguide/modeling/pages/text-widgets/text/parameter-actions.png" alt="Parameter Actions" width="450" >}}


#### X.X.3 Fallback Text {#PARAMETER_SLUG-fallback}

The fallback text is shown when the datasource of the **Parameters** is empty or unavailable. 

Empty attributes used as parameters do not cause the fallback text to be shown. Instead the template is rendered as normal and the placeholders for the empty parameters are substituted by empty strings. 

For example: The template `Hello, {1}!` with the fallback text _"Nobody to greet."_ would get rendered as follows:

| Scenario         | Rendered text      |
| ---------------- | ------------------ |
| Filled attribute | "Hello, World!"    |
| Empty attribute  | "Hello, !"         |
| Missing object   | "Nobody to greet." |

Widget Properties using Text Template

• Text: Caption
• Common: Label Caption
• Date Picker: Placeholder Text
• Text Area: Placeholder Text
• Text Box: Placeholder Text
• Button: Caption
• Data Grid 2: Caption
• Data Grid 2: Tooltip
• Data Grid 2: Dynamic Text - Not documented separately at the moment.
• Group Box: Caption
• Tab Container: Badge - Not documented at the moment
• Static Image: Alternative Text - Not documented at the moment
• Dynamic Image: Alternative Text - Not documented at the moment

[ConnorLand]

This PR is an iteration on work done here: #7745

[MariaShaposhnikova]

@ConnorLand , since #7745 has been closed, should this one be closed too?