Skip to Content

Dynamic Substitution

Dynamic Substitution is a type of syntax that can be used in Vinyl to dynamically substitute in the result of an expression either in the Business Logic Layer and or in the Application UI Layer. In the Business Logic Layer it is used for dynamically substituting data purposes, and in the Application UI Layer it is used to dynamically substitute in the resultant value being displayed. Dynamic substitution can also be used in Notifications, where you want to substitute in information being displayed, for example {{CustomerName}}.

When using Dynamic Substitution in the Application UI Layer, you need to assign the Page to a Business Object in order to use the dynamic substitution. This information gets configured at the Page level, so every field needed by the substitution will need to be available on the Page Business Object.

Benefits to using dynamic substitution in Business Logic are that it allows you to simplify the amount of information contained within an Expression, and they make Expressions more human readable.

Dynamic Substitution Syntax

The syntax to use for Dynamic Substitution is: 

`{{AliasName}}`

Here, the curly brackets {{ }} (or braces in the US) surround the Alias value that is going to be used for the dynamic substitution. It is recommended that the actual value contained within the curly brackets is an Alias value vs. a Column Name or Expression value as over time an Alias value is generally considered more static than a Column Name or Expression.

Business Logic Example

Dynamic Substitution is very useful in Where clauses as well as simplifying calculations in the Business Logic Layer. Here we'll look at specific examples where we can leverage Dynamic Substitution.

For this example we'll use the Northwinds database as our source, and assume we're looking at an Orders page containing information on orders placed through an order fulfillment app. First we'll see how we can use Dynamic Substitution in a Business Logic Rule so that we restrict the Orders information displayed just the Orders placed within the last 3 years:

  • Navigate to the app Orders page, go to Action Drawer > Live Designer
  • Drill into the SQL cog icon for the Orders Panel
  • Copy the Order (Source) Business Object and rename it. For example: Orders (Last Few Years)
  • For the new Rule, on the Columns tab create a new Expression that calculates the number of years since an Order has been placed using DATEDIFF and provide an Alias value for this Expression. This Alias is what will be used for dynamic substitution. For example: DateDiff
  • Set the appropriate Cast Option for the Logical Data Type for the Expression. Here we set it to Number.
  • Validate to check results are as expected

Next we'll use dynamic substitution in the Where clause of our Business Object, in order to restrict the results we want returned.

  • Navigate to the Business Logic screen where you're configuring the Rule from above
  • Click to select the Where tab
  • Click + Where Clause and add in Dynamic Substitution syntax, using our Alias value from the Expression just created and provide information on how you want to restrict the results. For example:
    • Left = {{DateDiff}}
    • Operator = <=
    • Right = 3
  • Validate and check that the records returned are only the Orders placed within the last 3 years

Lastly with this example, we'll look at how we can simplify a calculation using dynamic substitution. Continuing to work with the Business Object created for the example we have, we'll modify it to include an additional Expression that uses dynamic substitution to string together the number of years since an Order was placed with the word 'years'.

  • Click the Vinyl Back button to go back to the Business Logic screen where you're configuring the Rule
  • Click to select the Columns tab
  • Click + Column and add in an Expression that casts the dynamic substitution value and stings it together with the word 'years':
    • For example: CAST({{DateDiff}} as string) || 'years'
  • Provide an Alias value for this Expression. For example: Years
  • Validate results

URL Example

If you are looking to dynamically substitute in a URL in a data object, you could use syntax like the following example: 

'www.webpage.com/path/path/' || {{DynamicSubstitution}}

Complex Expression Example

If you are working with dynamic substitution in a more complex Expression, be cautious with the syntax. There may be instances where you need to add in an additional set of parentheses in order to get the syntax to work properly (or as you are expecting).

For example, if you were to use the following Expression Vinyl will return a Divide by Zero error:

IIF({{Sum}} = 0, 0,({{CompletedCount}}/{{Sum}})*100)

This is because the process and order in which the Expression is being evaluated, it requires an additional set of parentheses in order to output the desired results. Here is the corrected syntax version: 

IIF(({{Sum}}) = 0, 0,((CAST({{CompletedCount}} AS DECIMAL(15,5)))/(CAST({{Sum}} AS DECIMAL(15,5))))*100)

Page or Panel Name Example

Dynamic Subsitutions can also be used for page or panel Names. In this example scenario, we'll use Dynamic Substitution for a panel Name for the Employees Page Form panel. Here we will dynamically substitute the Employee Full Name as the panel Name for the Employee Form.

  1. Navigate to the page in your application where you want to substitute the Panel Name. For example: Employee
  2. Click on the Action Drawer menu, select Live Designer
  3. Select the Business Object that contains the column value you'll be using for Source under Page Options
  4. Click the Label Options tab for the panel you want to modify the panel Name. For example: Employee

  5. Modify the Label field to contain the column value you're using, using the proper syntax for Dynamic Substitution.

    • For example: {{FullName}}

  6. Click Save

  7. Navigate back to the Page in the application, refresh your web browser and test

Vinyl Validations

If you want to use Dynamic Substitutions with Vinyl Validation Messages, you'll need to put the Dynamic Substitution value on the Validation Message itself and also on the Panel Business Object.

Validation Message Example: Cannot exceed {{MaxDiscount}}

Limitations

The following are known limitations when working with Dynamic Substitutions:

  • Not currently supported for Column Names in a Chart
  • Foreign currency formatting does not currently allow for dynamic substitution. Workaround is to format in the data object and Cast as String, which causes the total function to then work.