Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -253,11 +253,11 @@ To fix CE1154, make sure that the snippet call is placed in a data container whi

### Error Code: CE1570

CE1570 error message: *The selected snippet {Name of the snippet} expects an object of type {type of object}, which is not available here.*
CE1570 error message: *The selected snippet {Name of the snippet} expects an argument of type {type of argument}, which is not available here.*

You get CE1570 if the snippet has a snippet parameter that expects an object of a particular type to be passed to it. This error occurs when the snippet is called from another page, layout, or snippet which does not have this object available.
You get CE1570 if the snippet has a snippet parameter that expects an argument of a particular type, such as an object or a primitive value like a string, and no argument is available for it. This error occurs when the snippet is called from another page, layout, or snippet which does not have a matching object or variable available, and no expression is configured for the argument.

To fix CE1570, make sure that the object is passed correctly in the snippet settings of the snippet call.
To fix CE1570, make sure that the argument is passed correctly in the snippet settings of the snippet call. Select an available variable of the correct type, or configure an expression. For more information, see [Passing Arguments](/refguide/snippet-call/#passing-arguments) in *Snippet Call*.

## Data Consistency Errors

Expand Down
28 changes: 16 additions & 12 deletions content/en/docs/refguide/modeling/pages/page-resources/snippet.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
* You can add a new empty snippet (see [Page Resources](/refguide/page-resources/)).
* You can extract a snippet from a widget on an existing document (see [Extract Snippet](#extract-snippet)).

A snippet expects zero or more parameters. To change the parameters of the snippet, click the **Parameters** button in the top bar. This opens a dialog box which allows you to add, modify, and remove parameters. The **Parameters** button shows the current number of parameters in its caption, while its tooltip shows the name and type of each parameter. For more information about snippet parameters, see the [Parameters](#parameters) section in snippet properties.
A snippet expects zero or more parameters. To change the parameters of the snippet, click the **Parameters** button in the top bar. This opens a dialog box which allows you to add, modify, and remove parameters. The **Parameters** button shows the current number of parameters in its caption, while its tooltip shows the name and type of each parameter. A parameter can be an object or a primitive value, such as a string or a boolean. For more information about snippet parameters, see the [Parameters](#parameters) section in snippet properties.

Check failure on line 17 in content/en/docs/refguide/modeling/pages/page-resources/snippet.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Mendix.Capitalization] Use ''Boolean'' (capitalized) Raw Output: {"message": "[Mendix.Capitalization] Use ''Boolean'' (capitalized)", "location": {"path": "content/en/docs/refguide/modeling/pages/page-resources/snippet.md", "range": {"start": {"line": 17, "column": 428}}}, "severity": "ERROR"}

In the example below, the snippet defines a single parameter with name **Order** and type **MyFirstModule.Order**.
In the example below, the snippet defines two parameters: an object parameter named **Order** with type **MyFirstModule.Order**, and a primitive parameter named **Amount** with type `Integer/Long`.

{{< figure src="/attachments/refguide/modeling/pages/page-resources/snippet/snippet.png" alt="Example of a snippet" width="400" class="no-border" >}}
{{< figure src="/attachments/refguide/modeling/pages/page-resources/snippet/snippet-settings.png" alt="Example of a snippet with an object parameter and a primitive parameter" width="500" class="no-border" >}}

## Properties Pane

Expand Down Expand Up @@ -46,22 +46,24 @@

#### Parameters {#parameters}

**Snippet parameters** allow snippets to be re-used with different data. They work the same way as [Page Parameters](/refguide/page-properties/#parameters).
**Snippet parameters** allow snippets to be re-used with different data. They work the same way as [Page Parameters](/refguide/page-properties/#parameters), with the exception that snippet parameters cannot be made optional.

{{% alert color="info" %}}
Snippet parameters do not support primitive types and cannot be made optional, like [page parameters](/refguide/page-parameter/) do.
{{% /alert %}}
The data type of a snippet parameter defines the type of the value that it expects. Possible data types are **Objects**, and **Primitives** such as `Boolean`, `Date and time`, `Decimal`, `Enumeration`, `Integer/Long`, and `String`. For more information, see [Page Parameters](/refguide/page-parameter/#data-type).

*Default value*: *Object*

An argument must be passed to every snippet parameter. For more information, see [Passing Arguments](/refguide/snippet-call/#passing-arguments) in *Snippet Call*.

#### Variables {#variables}

The list of **Variables** defined on the snippet. Variables are non-persistent, primitive values that can be used as attributes by widgets in the snippet. They behave the same as [variables on pages](/refguide/page-properties/#variables), with the exception that default values cannot reference snippet parameters.

{{% alert color="info" %}}
[Snippet extraction](#extract-snippet) does not automatically recreate variables in the resulting snippet. Missing variables must be added manually.
[Snippet extraction](#extract-snippet) does not recreate variables in the resulting snippet. Instead, the variables that the extracted widgets use are turned into primitive snippet parameters.
{{% /alert %}}

{{% alert color="info" %}}
[Inlining a snippet](/refguide/snippet-call/#inline-snippet) does not automatically create variables on a page. Missing variables must be added manually. If the snippet and the page have identically named variables, then references will automatically carry over.
[Inlining a snippet](/refguide/snippet-call/#inline-snippet) creates the variables of the snippet on the page or snippet that it is inlined into.
{{% /alert %}}

### Designer Section {#designer}
Expand All @@ -84,7 +86,7 @@

{{< figure src="/attachments/refguide/modeling/pages/page-resources/snippet/extract-snippet-contextmenu.png" alt="Example of a widget about to be extracted to a snippet" width="800" class="no-border" >}}

To determine which snippet parameters are needed, Studio Pro analyzes which objects from the surrounding widgets are used inside the selected widget. There are various ways a widget can refer to a surrounding object:
To determine which snippet parameters are needed, Studio Pro analyzes which objects and variables from the surrounding widgets are used inside the selected widget. There are various ways a widget can refer to a surrounding object or variable:

* The selected attribute of an attribute widget (such as Text box)
* The parameters of a text template
Expand All @@ -107,16 +109,18 @@

The names of the snippet parameters can be changed only if they are unique and not already used in the extracted content. The order of the parameters can also be changed.

Clicking **OK** will create the new snippet and replace the extracted widget in the original document with a snippet call. The **Snippet settings** of the call are automatically configured to pass the correct object to each snippet parameter. In the extracted snippet, references to the original objects are rewritten to refer to a snippet parameter instead. For example, a conditional visibility expression could be rewritten as shown in the following side-by-side comparison:
Clicking **OK** will create the new snippet and replace the extracted widget in the original document with a snippet call. The **Snippet settings** of the call are automatically configured to pass the correct argument to each snippet parameter. In the extracted snippet, references to the original objects and variables are rewritten to refer to a snippet parameter instead. For example, a conditional visibility expression could be rewritten as shown in the following side-by-side comparison:

{{< figure src="/attachments/refguide/modeling/pages/page-resources/snippet/extract-snippet-expression-rewrite.png" alt="Example of an expression rewritten by Extract snippet" width="580" class="no-border" >}}

{{% alert color="info" %}}
Not every widget can be successfully extracted to a snippet if the result requires multiple snippet parameters. For example, a Data view with an *Association* data source must be surrounded by a single context object, which is not the case in a snippet with multiple parameters.

This can be fixed after the extraction by manually wrapping the widget in a Data view with a *Context* data source pointing to the correct snippet parameter.
{{% /alert %}}

Widgets that are configured with variables cannot be successfully extracted.
{{% alert color="info" %}}
Variables used by the extracted widgets are turned into primitive snippet parameters.
{{% /alert %}}

## Read More
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,40 @@ The **Snippet** property shows the name of the snippet that the snippet call wil

#### Snippet Settings {#snippet-settings}

The **Snippet settings** property opens a dialog box that shows a list of parameters of the selected snippet and the objects that will be passed to each of them.
The **Snippet settings** property opens a dialog box that shows a list of parameters of the selected snippet and the arguments that will be passed to each of them. For more information, see [Passing Arguments](#passing-arguments).

### Common Section {#common}

{{% snippet file="/static/_includes/refguide/common-section-link.md" %}}

## Passing Arguments {#passing-arguments}

An argument must be passed to every [snippet parameter](/refguide/snippet/#parameters) of the snippet that is called. The **Snippet settings** dialog box lists the parameters of the snippet with their **Name**, **Type**, and **Argument**. To configure the argument of a parameter, select the parameter and click **Edit parameter value**. In the dialog box that opens, set **Type** to **Variable** or **Expression**. This works the same for object and primitive parameters.

In the example below, the snippet has an object parameter **Order** and a primitive parameter **Amount** of type `Integer/Long`:

{{< figure src="/attachments/refguide/modeling/pages/structure-widgets/snippet-call/snippet-arguments-mapping.png" alt="example of the snippet settings dialog box" width="500px" >}}

### Variable Arguments {#variable-arguments}

Variable arguments are used to pass a value from the context of the snippet call to the snippet. This is done by selecting from the available variables in the **Variable** dropdown. Only variables that match the data type of the snippet parameter are shown, for example a page parameter, a [variable](/refguide/page-properties/#variables) of the page, or an object from a surrounding data container. Variables that come from a data source, a selection, or the return value of an action cannot be passed.

In the example below, the argument for the parameter **Amount** is the variable **Amount**:

{{< figure src="/attachments/refguide/modeling/pages/structure-widgets/snippet-call/snippet-argument-variable.png" alt="example of a variable argument" width="500px" >}}

### Expression-Based Arguments {#expression-based-arguments}

Expression-based arguments allow you to use functions and follow associations within the expression to set the argument value. The expression must return a value that matches the data type of the snippet parameter.

In the example below, the argument for the parameter **Amount** is the expression `$Amount`, which uses the variable **Amount** that is available at the snippet call:

{{< figure src="/attachments/refguide/modeling/pages/structure-widgets/snippet-call/snippet-argument-expression.png" alt="example of an expression-based argument" width="500px" >}}

{{% alert color="info" %}}
Snippet parameters are always required. Unlike [page parameters](/refguide/page-parameter/#argument), they cannot be omitted and do not have a default value.
{{% /alert %}}

## Styling

### Design Properties Section {#design-properties}
Expand All @@ -63,7 +91,8 @@ To perform actions on a snippet call, select it on a page and right-click it. Th
When you select **Inline snippet**, Studio Pro will analyze the snippet call to determine if it is safe to inline. If it is safe, the following will occur:

* The snippet call will be replaced by the contents of the snippet
* All references to the snippet parameters will be rewritten to refer to the objects to which they are mapped in the **Snippet settings** of the snippet call
* All references to the snippet parameters will be rewritten to refer to the objects, variables, or expressions to which they are mapped in the **Snippet settings** of the snippet call
* If the snippet has variables, they will be created on the page or snippet that contains the snippet call

This is basically the inverse operation of [Extract Snippet](/refguide/snippet/#extract-snippet).

Expand All @@ -79,9 +108,8 @@ Not every snippet call can be inlined, because certain configurations cannot be

The following are examples of configurations which cannot be correctly inlined:

* A Data view with a *Context* data source using an association of a snippet parameter (if that parameter has been mapped to an object which is not the directly surrounding object of the snippet call)
* An attribute widget (such as Text box) using an attribute of a snippet parameter (if that parameter has been mapped to a page parameter in the snippet call)
* A snippet with variables
* A Data view with a *Context* data source using an association of a snippet parameter (if that parameter has been mapped using an expression)
* An attribute widget (such as Text box) using an attribute of a snippet parameter (if that parameter has been mapped using an expression)

In such cases, the inlined content needs to be fixed manually by adding or removing a Data view (depending on the configuration) and reconfiguring the affected widgets to refer to the correct object again.

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading