Merge pull request mendix#10472 from stdagkalakis/wtf-2288-doc-update-for-primitive-and-optional-page-parameters

Documentation update for page parameters [WTF-2288]

Author: Yiyun333

content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/client-activities/show-page.md

@@ -45,9 +45,9 @@ You can also open the dialog box by double-clicking the activity, or right-click
 
 ### Page
 
-The [page](/refguide/page/) that is displayed to an end-user. If the page has parameters, the [Parameters](#parameters) section allows you to specify the which objects should be passed to the page.
+The [page](/refguide/page/) that is displayed to an end-user. If the page has parameters, the [Parameters](#parameters) section allows you to specify which values should be passed to the page.
 
-To create a new page that **Show page** activity will show, click the **Select** button > **New**. Studio Pro will ask you whether you want to pass a variable as an argument to the new page. If you select a variable to pass, Studio Pro will automatically create a page parameter of that type and a data view to edit that object.
+To create a new page that **Show page** activity will show, click the **Select** button > **New**. Studio Pro will ask you whether you want to pass a variable as an argument to the new page. If you select a variable to pass, Studio Pro will automatically create a page parameter of that type and a data view to edit that value.
 
 ### Page Title
 
@@ -72,7 +72,7 @@ Often you need to have control of page history, for example to show the correct
 
 ### Parameters Section {#parameters}
 
-Depending on the selected page, you will see a list of its parameters. For each parameter, you can configure a variable or expression to specify which object should be passed to it. These objects are used by [data views](/refguide/data-view/) with a page parameter data source. If only one variable of the expected type for a certain parameter is available, that variable is automatically filled in.
+Depending on the selected page, you will see a list of its [parameters](/refguide/page-parameter/). For each parameter, you can configure a variable or expression to specify which value should be passed to it. These values are used by [data views](/refguide/data-view/) with a page parameter data source. If only one variable of the expected type for a certain parameter is available, that variable is automatically filled in.
 
 ## Common Section{#common}
 

content/en/docs/refguide/modeling/pages/on-click-event.md

@@ -98,7 +98,7 @@ The **Show a page** event opens the specified page. Select the page which opens
 
 #### Page Arguments
 
-**Page arguments** are automatically configured based on the parameters of the selected page and the available arguments. In general, arguments are taken from any enclosing data widget. If the data widget enclosing the widget calling a page is inside another (nested) data widget, then objects from that data widget and any others in which it is nested can also be passed.
+**Page arguments** are automatically configured based on the [parameters](/refguide/page-parameter/) of the selected page and the available arguments. In general, arguments are taken from any enclosing data widget or the page itself.
 
 ### Call a Microflow {#call-microflow}
 

content/en/docs/refguide/modeling/pages/page-resources/snippet.md

@@ -46,7 +46,11 @@ The values for the platform property are:
 
 #### Parameters {#parameters}
 
-**Snippet Parameters** works the same way as [Page Parameter](/refguide/page-properties/#parameters) with the difference that a snippet's parameter can be accessed at the top level, for example when creating expressions or selecting attributes.
+**Snippet parameters** allow snippets to be re-used with different data. They work the same way as [Page Parameters](/refguide/page-properties/#parameters).
+
+{{% alert color="info" %}}
+Snippet parameters do not support primitive types and cannot be made optional, like [page parameters](/refguide/page-parameter/) do.
+{{% /alert %}}
 
 #### Variables {#variables}
 

content/en/docs/refguide/modeling/pages/page/page-parameter.md

@@ -0,0 +1,60 @@
+---
+title: "Page Parameters"
+url: /refguide/page-parameter/
+weight: 70
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+## Introduction
+
+Parameters are the means by which you pass data to your page. When a page is loaded, the parameters are filled with the current values.
+
+To use an object or primitive value in your page, define a parameter. In the image below, the parameter is named **CustomerName**, is of type string, is not required, and has a default value of an empty string `''`:
+
+{{< figure src="/attachments/refguide/modeling/pages/page/page-parameter.png" alt="use an object or primitive value" class="no-border" >}}
+
+## Properties
+
+### Name
+
+* **Name** — The name of the parameter.
+
+### Data Type
+
+The data type of a 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`.
+
+Default: *Object*
+
+### Argument {#argument}
+
+Argument determines whether it is **Required** or **Optional** to [pass an argument](#passing-arguments) to the parameter when opening the page. If it is required it is mandatory to supply an argument for that parameter when opening a page.
+
+### Default Value
+
+When argument is set to **Optional**, a default value can be set. The default value is used if no [argument is passed](#passing-arguments) to the parameter. Given the example below, if no argument is passed for `CustomerName`, the page will open with the parameter set to `''`:
+
+{{< figure src="/attachments/refguide/modeling/pages/page/page-parameter-default-value.png" alt="no argument example" max-width=70% >}}
+
+{{% alert color="info" %}}
+The default value is used when the argument is omitted during modeling. Not when the argument value is `empty` during runtime.
+{{% /alert %}}
+
+## Passing Arguments {#passing-arguments}
+
+Arguments are passed to page parameters when a page is opened. For example, using a **Show page** action [on a widget event](/refguide/on-click-event/#show-page) or in a [microflow](/refguide/show-page/). For each parameter the page has an argument can be configured. It is only necessary to pass arguments to [required parameters](#argument):
+
+{{< figure src="/attachments/refguide/modeling/pages/page/page-parameter-mappings.png" alt="example of passing arguments" width="500px" >}}
+
+### Variable Arguments
+
+Variable arguments are used to pass parameters from the context to the page. This is done by selecting from the available variables on the page presented in the dropdown. **Optional** parameters do not require an argument and can be omitted by selecting `(None)` :
+
+{{< figure src="/attachments/refguide/modeling/pages/page/page-parameter-argument-variable.png" alt="example of variable arguments" max-width=70% >}}
+
+### Expression-Based Arguments
+
+This method allows users to use functions and follow associations within the expression to set the argument values. Using expressions for arguments provides flexibility in setting values and improves the functionality of pages. 
+
+In the example below, the page has a parameter **AnimalName** which is populated by an expression extracting the **Name** member of the provided **Animal** object:
+
+{{< figure src="/attachments/refguide/modeling/pages/page/page-parameter-expression.png" alt="example expression-based arguments" width="500px" >}}

content/en/docs/refguide/modeling/pages/page/page-properties.md

@@ -105,7 +105,7 @@ In simple e-commerce applications, the URLs can be configured as follows:
 
 #### Parameters {#parameters}
 
-The list of parameters that this page expects. These parameters can be used by [data views](/refguide/data-view/) with a page parameter data source.
+The list of [parameters](/refguide/page-parameter/) that this page expects. These parameters can be used by widgets on the page.
 
 A page parameter is an input that needs to be passed from the calling page, microflow, or nanoflow to the current page. Page parameters determine information that can be reused on the page. For example, if you want to build an **Employee_Details_Edit** page, the page will have a parameter **Employee**. Thus when this page is called an Employee object needs to be passed to it to show the corresponding Employee data.