4. Properties

There is a download available of this widget on the Examples page.

In our previous chapters, we created a simple static widget. Now, let's make it a little more dynamic by adding properties to the widget. These properties are similar to any other property you see in the user interface of the modeler, such as the Name of an interaction node, the Validation of a text data field, or an Action on an assignment node.

Creating a Personalized Greeting Widget

Let's create a widget that provides a more personal greeting:

1. Inside the "Widget Academy" library, create a new widget and name it "Hello, You!"

2. Select the Scripts tab and paste the following code:

<? var @uppercasedName := ToUpper(@Name) ?>
<h2>Hello, <? print html @uppercasedName ?>!</h2>

There are a few new things happening here, so let’s unpack them.

The <? ?> symbols denote code blocks, where you write WEMscript. The code within these blocks is executed server-side and is not included in the output. In the first line, we declare a variable using the var statement. For those familiar with WEM expressions, you’ll notice that we convert the name to uppercase using ToUpper(@Name). Yes! In WEMscript, you can also write WEM expressions! In the second line, we use the print statement to output the contents of the variable @uppercasedName. Notice the html argument provided to the print statement; this will HTML encode the output. For example, < will be output as <. If we don't HTML encode it, we risk breaking the HTML or, even worse, allowing a hacker the opportunity to inject malicious code, something we will discuss in depth in later chapters.

You may be wondering if writing <? print html ... ?> will become tedious over time. Fortunately, WEMscript has a shorthand for that: <?= @uppercasedName ?>. Our updated code now looks like this:

<? var @uppercasedName := ToUpper(@Name) ?>
<h2>Hello, <?= @uppercasedName ?>!</h2>

This is much shorter and more convenient! There are also other shorthand notations, such as <?js for JavaScript and <?attr for HTML attribute encoding, which will be discussed in later chapters.

Now, you may notice that when you validate the widget (try it now by pressing the validate button next to the save button), an error will appear: "An unknown variable is used." This is because we have not yet added @Name as a property.

Adding the Name Property

To add the property:

1. Select the Properties tab.

2. Click on "New property" in the toolbar.

3. Name the property "Name."

4. Set the property type to "Text."

5. Set the input type to "Literal."

6. Set the property group to "General."

We will go into much more detail about the different property types and settings in later chapters. For now, we are ready to test our new widget. Place this widget on a template, select it, and you will notice that a Name property is visible in the right panel. Fill in the property with a value, such as your name, save the template, and preview it.