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

Apply the new Text Template guide to Text Widget's Caption #7932

Open
wants to merge 2 commits into
base: development
Choose a base branch
from

Conversation

weirdwater
Copy link
Contributor

@weirdwater weirdwater commented Jun 24, 2024

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

@weirdwater weirdwater marked this pull request as draft June 24, 2024 11:30
@weirdwater weirdwater force-pushed the wtf-1870-clienttemplate-placeholders-revised branch from e31269e to de278c8 Compare June 24, 2024 12:17
@weirdwater weirdwater marked this pull request as ready for review June 24, 2024 14:02
@ConnorLand
Copy link
Collaborator

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

@ConnorLand ConnorLand self-assigned this Jun 25, 2024
@MariaShaposhnikova
Copy link
Collaborator

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants