Manipulating the view state via JavaScript can be quite overwhelming. The following table illustrates the differences between various scenarios.

The table below assumes that some view state has been set via JavaScript after a page load to a view state field.

In the case of a widget being unloaded, there are two scenarios where the outcome depends on specific conditions. As discussed in the previous chapter, we have the option to manually clear the state of localStorage and sessionStorage in the unloadscript block.

The teaching of Less and CSS is outside the scope of this academy. However, there are a few important points to keep in mind. Most of the concepts I explain here apply not only to WEM widgets but also to web development in general.

Global Space

When you publish or preview a WEM application, the Less styles from all the widgets are combined into a single CSS file. This CSS file is then included in the design template. This presents a significant issue: all the CSS exists in a global space. I briefly discussed this in previous chapters. As we learned, if you are not careful, you could inadvertently overwrite the styles of other widgets or any HTML element, for that matter! For example:

/* Bob's card widget */
.card {
	background: tomato;
}

/* Jane's card widget */
.card {
	background: lightgoldenrodyellow;
}

In this case, both Bob and Jane have created a card widget using the class name "card." Even if Jane's widget is not used on a page, if Bob's widget is included, it may appear to have a strange yellow background. This can lead to confusion and blame for issues that are not actually related to Bob's widget. It is advisable to make class names more unique. You can add prefixes to the class names, such as your initials, your company name, or both, like this:

/* Bob's card widget */
.bobs-company-name-card {
	background: tomato;
}

/* Jane's card widget */
.janes-company-name-card {
	background: lightgoldenrodyellow;
}

CSS Variables

When WEM supported widgets, it included Less by default. Less is powerful because it supports variables, which makes styling more organized and easier to maintain. Nowadays, CSS variables are supported in all major browsers and offer even greater capabilities. You can alter the value of a CSS variable in real time, creating new opportunities for styling your widgets. You can still use Less variables as a base. For example, consider the following Less code:

body {
	--card-color: @brand-danger;
}

.janes-company-name-card {
	background: var(--card-color);
	border: 1px solid hsl(from var(--card-color) h s calc(l - 10));
	color: white;
	padding: 8px;
}

However, if you save this code, you will encounter an error message indicating a syntax error on the line setting the border property.

Escape Syntax

What is happening here? This is because Less has its own syntax and attempts to parse the CSS value as a Less expression. We can resolve this issue by using the escape syntax ~"value". If we modify the line as follows:

.janes-company-name-card {
	border: ~"1px solid hsl(from var(--card-color) h s calc(l - 10))";
}

This change makes the code valid. While it may not be ideal, it is better than nothing.

Embedding Resources

You may be wondering how to embed a resource in Less. The short answer is that you cannot do it directly. The following code, which uses a made-up WEM style syntax, will not work:

.company-logo {
	/* This does not work. */
	background: <?less FileUrl(@CompanyLogo) ?>;
}

To achieve this, you need to revert to using the <style> tag or apply it via JavaScript.

In the previous module of the view state chapter, we declared a field and created an event to toggle that field, allowing the message box to expand and collapse. Another way to change the view state is through JavaScript. Let's update our previous implementation of the message box to utilize JavaScript instead.

First, we need to add the Text text property and the Style dropdown property, which should include the values "info," "success," and "danger." You can refer to the previous view state chapter for guidance on how we created these properties. Next, we will create a boolean view state field named Collapsed.

Use the following script:

<div id="<?attr OutputId() ?>" class="message <?attr @Style ?> <?attr if @Collapsed then "collapsed" else "expanded" ?>" onclick="toggleMessageBox(this)">
	<span class="box ellipses">
		<span class="glyphicon glyphicon-comment"></span> 
		...
	</span>
	<span class="box text">
		<span class="glyphicon glyphicon-heart-empty"></span>
		<?= @Text ?>
	</span>
</div>
<? scriptmodule "message-box" ?>

	function toggleMessageBox(element) {
		element.classList.toggle("collapsed");
		element.classList.toggle("expanded");
	
		const outputId = element.id;
		const collapsed = element.classList.contains("collapsed");
		
		Runtime.viewState(outputId).set("Collapsed", collapsed);
	}
	
<? end ?>

What has changed is that there is no register event because we don't have an event in this widget, nor do we need @Collapsed := @Collapsed ? false to initialize that field to false when it is unknown. This works in this case because when we check with if @Collapsed then, it does not matter whether the value is unknown or false.

We introduce a new function, OutputId(). Every widget has its own Output ID, which serves as a unique identifier on the page. This is perfect for use in conjunction with the id attribute, which should also be unique! We will discuss this function in more detail in later chapters.

We changed the onclick attribute to execute the toggleMessageBox() function instead of triggering an event, as we did in the previous chapter. A new feature is that this function is declared inside a scriptmodule, which is another way to add JavaScript functionality to the widget, aside from including it via a file. We will cover this topic in more detail in later chapters.

The toggleMessageBox(element: HTMLElement) function is straightforward. Depending on the state, we toggle between the two classes. We retrieve the Output ID from element.id and check if it is collapsed by verifying if the element's class list contains the "collapsed" class. The Runtime.viewState(outputId: string) function returns the view state of the widget with that Output ID. We use the set(key: string, value: any) function, where the key is the name of the view state field, to set a value for that field. There are two additional functions besides set(): get(key: string) and clear(key?: string). These functions are self-explanatory, but you can find more information about them in the WEM widget reference.

The styles remain unchanged and are the same as before:

.message {
	display: flex;

	> .box {
		border: 1px solid transparent;
		border-radius: 4px;
		cursor: pointer;
	}
	
	&.danger > .box {
		background: lighten(@brand-danger, 25%);
		border-color: lighten(@brand-danger, 10%);
		color: darken(@brand-danger, 23%);
	}

	&.info > .box {
		background: lighten(@brand-info, 25%);
		border-color: lighten(@brand-info, 10%);
		color: darken(@brand-info, 23%);
	}

	&.success > .box {
		background: lighten(@brand-success, 25%);
		border-color: lighten(@brand-success, 10%);
		color: darken(@brand-success, 23%);
	}

	&.collapsed > .box {
		padding: 5px;

		&.text {
			display: none;
		}
	}

	&.expanded > .box {
		padding: 15px;

		&.ellipses {
			display: none;
		}
	}
}

Now, place this widget on a template and add a refresh button to the page. Preview the widget. Notice that when you click the widget, there is no refresh, unlike in the previous implementation. This creates a better user experience. However, there is one downside: the view state is only persisted when we perform a postback to the WEM Runtime, such as when clicking the refresh button.

Try toggling the state of the widget, and then press F5 to refresh the page in your browser. You will notice that the widget retains its previous state. Now, toggle the state of the widget again and click the refresh button we added to the page. This time, the state is saved.

In the next chapter, we will explore a more modern approach to storing view state using localStorage and sessionStorage. This method addresses the refresh issue but comes with its own set of challenges.

You can also utilize sessionStorage and localStorage, which are available in the JavaScript standard library. These solutions are purely JavaScript-based and do not rely on WEM view state internals. Let's update our previous widget slightly.

Update the script with the following:

<div id="<?attr OutputId() ?>" class="message">
	<span class="box ellipses">
		<span class="glyphicon glyphicon-comment"></span> 
		...
	</span>
	<span class="box text">
		<span class="glyphicon glyphicon-heart-empty"></span>
		<?= @Text ?>
	</span>
</div>
<? scriptmodule "wem-message-box" ?>

	function clearStateMessageBox(outputId, nodeId) {
		const key = getKeyMessageBox(outputId, nodeId);
		sessionStorage.removeItem(key);
	}

	function getKeyMessageBox(outputId, nodeId) {
		return `${outputId}:${nodeId}:collapsed`;
	}

	function initializeMessageBox(outputId, nodeId, style) {
		const element = document.getElementById(outputId);
		
		const key = getKeyMessageBox(outputId, nodeId);
		const collapsed = sessionStorage.getItem(key) === "yes";

		element.classList.add(style);
		element.classList.toggle("collapsed", collapsed);
		element.classList.toggle("expanded", !collapsed);
		
		element.addEventListener("click", () => toggleMessageBox(element, key));
	}

	function toggleMessageBox(element, key) {
		element.classList.toggle("collapsed");
		element.classList.toggle("expanded");
	
		const collapsed = element.classList.contains("collapsed");
		
		sessionStorage.setItem(key, collapsed ? "yes" : "no");
	}
	
<? end ?>
<?
	/* Unfortunately, WEM does not yet have a NodeId() function. */
	var @currentNodeId = Last(Split(NodeTrail(), ","))
?>
<? startupscript ?>

	initializeMessageBox(<?js OutputId() ?>, <?js @currentNodeId ?>, <?js @Style ?>);

<? end ?>
<? unloadscript ?>

	clearStateMessageBox(<?js OutputId() ?>, <?js @currentNodeId ?>);

<? end ?>

In this update, we introduce startupscript, which is a JavaScript code block that runs after the page has been initialized and all static HTML elements are rendered. We also have unloadscript, which executes when a WEM event is triggered, just before the new page is rendered. We will discuss these script blocks in more detail in later chapters.

Comparing the previous code with the new version, you will notice that the initializeMessageBox() function is used to initialize the message box, as the name suggests. Here, we set the class names and retrieve the view state using sessionStorage through JavaScript. Additionally, we updated the code to set the click handler here instead of using an onclick attribute. While functionally there is no difference, this approach promotes better organization, a principle known in computer science as "separation of concerns."

Looking at the function getKeyMessageBox(outputId, nodeId) and the line const key = ${element.id}:${nodeId}:collapsed;, we see that the key is created by combining the Output ID, a node ID, and an arbitrary identifier, separated by a colon. Since sessionStorage keys are stored globally, we need to ensure that the keys for this widget are globally unique. If we had simply used "collapsed" as the key and had two identical widgets on the same page, they would overwrite each other's state. The node ID ensures that the view state of this widget is unique per interaction node. While we use a colon here, any character that is not alphanumeric can be used, as those characters are reserved for the Output ID and node ID.

Depending on the widget you are creating, you may want to clear the view state—demonstrated using clearStateMessageBox() here—when unloading the widget.

Let’s open the overlay again to create a property. All property types have the following attributes:

Name

The name of the property is identified as @MyPropertyName in WEMscript.

Input Type

The input type determines how we set the value of the property. There are three methods to do this. Note that there is only one way to write to a property, which is via the Data Model.

Appearance

This property indicates which group the property should be rendered in within the template editor. It does not affect the functionality of the property.

File Type

The file property has an additional attribute for validation. You can leave it blank to accept any file type.

Dropdown

The dropdown has an extra property called Dropdown Options. The options consist of a tuple of a label and a value. The labels are used to display the options in the template editor, while the values are used in WEMscript and are of the text type. In technical terms, a dropdown is a static set of text enums.

Let’s assume a dropdown property called @StyleContext with the following set of options for UI context styles:

The value of the dropdown is simply a text value. Here’s an example of how to use it:

if @StyleContext = "success"
    /* Render success style */
elseif @StyleContext = "info"
    /* Render info style */
elseif @StyleContext = "warning"
    /* Render warning style */
else
    /* Render danger style */
end

Navigation Types

The navigation types include Button Exit, Flowchart, Hyperlink, and Navigation Item. These are always set statically.

Default Value

This is the initial value of the property. If it is not set, the initial value will be unknown.

Writable

This property is only available when the input type is Data Model. If you want to write values back to the data model, this should be set to true. The property becomes stricter when it is writable; you cannot use calculated fields.

Visible When

This property determines when the property should be visible in the template editor. It works in conjunction with literal boolean and dropdown properties. You will notice that if you have any of those as properties for a widget, the "Visible When" dropdown is populated with those properties. The "Visible When" feature is useful for hiding properties that are not required in certain contexts.

In previous chapters, we used events to refresh the page without writing any code for it, and to toggle between the collapsed and expanded states of our message box widget. In this chapter, we will create our own button and add different types of actions to it.

First, create a new widget and name it "Button." Use the following script:

<? register event @OnClick ?>
<button class="btn btn-default" onclick="<?attr @OnClick ?>">Click me</button>

Next, add a dropdown property called "Action" with the following options:

Then, add three additional properties called "Flowchart," "NavigationItem," and "ButtonExit," using the same property type as their names. Do you remember the "Visible when" property explained previously? Click on the "ButtonExit" property and change the "Visible when" setting from "Always visible" to "Action." Note that "Action" refers to the dropdown property we created with selectable options. For "ButtonExit," check the "follow" checkbox. Repeat this process for the other two properties. You will see this functionality in action once we display this widget in the template editor.

Now, create an event called "OnClick" and use the following example code:

if @Action = "execute"
	execute @Flowchart
elseif @Action = "navigate" 
	navigate to @NavigationItem
elseif @Action = "follow" 
	follow @ButtonExit
end

Three new statements are introduced here: execute, navigate, and follow. By now, you should be familiar with WEM terminology. If you read the code, you will find that these statements do exactly what you expect, and they should be self-explanatory.

Events also allow for the manipulation of the row position within a list. This functionality is similar to using the List node in the flowchart editor; however, not all features available in the List node are supported.

The basic syntax is as follows:

goto first row of @List

goto next row of @List

goto previous row of @List

goto last row of @List

The syntax is straightforward, so we won't go into detail about what each command does. However, as mentioned earlier, not every feature is available out of the box. For instance, if we want to create an event that navigates to a specific row, we can program it as follows: we create a numeric view state called "RowIndex" to store the current row index. Note that in this example, the indices start at 1, with the first row being index 1. Fortunately, the code is quite simple:

goto first row of @List

var @i := 1

while @i < @RowIndex
    goto next row of @List
    @i := @i + 1
end

In the previous chapters, you learned how to create basic widgets. In this chapter, we will delve deeper into the topics we previously covered. However, we will not go in-depth into certain aspects of WEMscript, as that requires a separate module of its own. By the end of this chapter, you will have a better understanding of Properties, View State, Styling, and Events. Once you have a detailed knowledge of these concepts, we will be ready to start writing advanced widgets in the following module.