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, Events, and development flow of a widget. Once you have a detailed knowledge of these concepts, we will be ready to start writing advanced widgets in the following module.

A WEM widget can be built for different platforms, including iOS, Android, or the web. However, it is not mandatory to support all of them.

In the General tab, you will find the "Availability Settings" panel. Here, you can toggle whether the widget is supported on any of these platforms.

If a widget is not supported on a specific platform, it will be hidden in the modeler for that platform.

Great! You’ve made your first widget. Now, let’s take a step back to the General tab.

Here, you will find three sections: General Settings, Availability Settings, and Content Security Policy.

General Settings

This section is straightforward; here, you can rename the widget, but you can only rename it.

Availability Settings

This section indicates whether the widget is available for any of the following three WEM applications: the WEM web application, the WEM Android application, and the WEM iOS application.

For example, if you have a WEM web application and a widget that only supports Android, that widget will not be available for that project, even if you have imported the library it resides in.

You can always return to a widget to make it compatible with other platforms.

Content Security Policy

CSP (Content Security Policy) is a security feature implemented in WEM and web applications in general to help prevent various types of attacks, such as Cross-Site Scripting (XSS) and data injection attacks.

Any external sources that the widget uses should be included in the CSP. For instance, if you have the following HTML element:

That image will not load when CSP is enabled in your WEM portal unless you add the hostname https://some-website.com as an img-src directive in the CSP settings overlay behind the "Edit settings" button.

CSP allows web developers to specify which content sources are trusted and can be loaded by the browser when rendering a web page, thereby making the WEM application safer.

As of WEM 4.2, Content Security Policy features have been added. The widget documentation was written before this update, and some example code may not be compatible. This is one of the unfortunate side effects of enhancing application security. For now, to keep things simple, we will not use CSP in our examples. Just ensure that your WEM portal has CSP disabled at the moment for the example code to work.

We will delve deeper into these CSP settings later on.

I believe many programmers are familiar with the classic "Hello, World!" program.

When I was around 13 years old, I wrote my own "Hello, World!" program in QBasic 1.0, which came installed with MS-DOS on our computer. I remember changing the text "World" to my own name, "Vincent." After pressing F5 to run the program, I was thrilled to see my computer greeting me:

I was amazed! I felt the power in my fingertips and wanted to learn more. I used a dial-up modem to connect to various bulletin board systems (BBS) in search of QBasic source codes to study. My parents were not always pleased, as calling on a phone line was expensive back in those days. Not to mention, no one could use the phone while the modem was connected. And let's not forget the times when I wanted to download the latest shareware demo of a game that was just a few megabytes! If someone accidentally picked up the phone, I would have to start the download all over again. Good times!

Although WEM is a no-code platform, I love writing code. Creating widgets is for those who enjoy programming. If you are making widgets, you are engaging in traditional programming. You could even say that if you create widgets, you can call yourself a web developer, as building advanced widgets requires extensive knowledge of HTML, CSS, and JavaScript.

In this module, we will teach you the basics of building a functional widget. We will start simply by creating a "Hello, World!" widget, then extend it to make it more interactive, and eventually conclude with a fully functional widget.

Creating widgets opens up an unlimited array of possibilities, but it can also be quite challenging. I hope that by building widgets, you will feel as excited as I was when I wrote my first programs.

When we talk about widget events, we refer to a unique set of WEMscript that can follow a button click, execute a flowchart, navigate to a navigation item, or refresh the screen. It is also possible to change the view state, which we will discuss in later chapters.

Introduction to Events

When learning a new language, it is almost traditional to create a "Hello, World!" program as your first project. Let's do that too! Along the way, I will skip a few details here and there, but don't worry; I will explain them in detail in the upcoming chapters. So, let's create our first widget!

To create a widget, we need to open the Widget Editor and create a widget library first.

Opening the Widget Editor

1. Open or create a new WEM web project.

The development workflow for building a WEM project differs from that of building widgets. When developing a WEM project, you follow a cycle of developing, testing in preview, staging, and finally publishing it to live. This process is repeated whenever there is a new feature to implement or a bug to fix. In contrast, when building widgets, you have a development and testing stage, but once the widget is made available to the public, every change—whether it’s a bug fix or a new feature—is done live. While this approach is not uncommon, it requires caution.

Development and Testing

When you create a new widget, its status is "in development." This status will appear as a prefix at the end of the widget name, for example, "My Widget (in Development)." During this stage, the widget can be developed and tested in preview.

If you attempt to view this widget in a staging or live environment, an error will indicate that the widget is not available.

Do you have some spare time to enhance your widget by adding some JavaScript? While this is not mandatory for a functional widget, it can elevate the professionalism of your widget and, in some cases, improve the user experience (UX) in the Template Editor by providing visual feedback to users.

Please note that this code runs only within the Template Editor in the Modeler, not on a page in a previewed or published WEM runtime portal.

Updating the Information Card Widget

Let's update our "Information Card" widget with a Template Editor script.

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:

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

WEMscript is a statically strongly typed language. Before you can use a variable, it must be declared using the var statement, with a specific type either explicitly set or inferred from its value. Every variable is prefixed with an @ symbol. A variable's value is unknown when no value has been assigned yet.

The following types are available in WEMscript: boolean, concept, conceptset, datetime, duration, file, list,

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:

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:

One important aspect of a widget property is that it is read-only in WEMscript. To assign a new value to a property, you need to perform a postback. Let's look at some example code, assuming we have created a literal text widget property called @Name.

To assign a new value to the property, you need an HTML form. After a WEM event, the property is set to its new value if it has been correctly validated. Here is a short example of how this looks:

In the next chapters, we will provide a more in-depth explanation of what the statement register input and the function OutputId() do.

Finally, we will take a closer look at WEMscript. Although you have encountered some code previously, this time we will explore it in greater detail. WEMscript is a standalone module that acts as the glue connecting all the other components of a widget, and we will utilize these components throughout this module.

You have learned the basics of the concepts involved in building a widget. While we haven't gone in-depth yet, we have only scratched the surface. However, I hope you now have a foundational understanding of what it takes to create basic widgets. I also hope I didn’t scare you off with the last chapter. With almost daily news about data breaches and computers being compromised by ransomware, it is crucial to prioritize security in programming. While programming with security in mind has always been important, it is even more essential in today’s world.

Now that we have created a simple form, we can make the fields required. How does that work? It’s actually quite simple. We add the required property to a property when using register input. Now, when a WEM runtime event is triggered—such as a button click—and a property does not have a value, that event is ignored, and the WEM runtime remains on the same page.

Let's update our previous form script:

<? 
	register input @FirstName required = true
	register input @LastName required = true
?>
<? if @ShowErrors and IsEmpty(@FirstName) ?>
	<div class="alert alert-warning">Please fill in your first name.</div>
<? end ?>
<label>
	First name:
	<input type="text" name="<?attr OutputId(@FirstName) ?>" value="<?attr @FirstName ?>">
</label>
<? if @ShowErrors and IsEmpty(@LastName) ?>
	<div class="alert alert-warning">Please fill in your last name.</div>
<? end ?>
<label>
	Last name:
	<input type="text" name="<?attr OutputId(@LastName) ?>" value="<?attr @LastName ?>">
</label>
<?
	@ShowErrors := true
?>

Although it is not part of this chapter, we have added a @ShowErrors boolean view state field. This is to prevent errors from being displayed when the widget is first rendered, enhancing the user experience. We don’t want to show errors indicating that specific fields need to be filled in upon first viewing. We take advantage of the fact that, during the initialization of the widget, the view state properties are set to the value unknown.

Other than adding the required option to the register input, we didn’t do anything special. Fortunately, some features don’t have to be difficult to implement.

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;
}

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:

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:

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:

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:

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

If you are familiar with the Modeler and creating page templates, then you are probably acquainted with components such as Alert, Panel, Conditional, and others. To create a similar widget, we need an additional feature called Placeholders. This feature allows you to reserve a section in your widget for content that you can add in the Template Editor within the Modeler. Let's create a simplified Alert component to explain the concept of placeholders.

Creating the Information Card Widget

1. Create a new widget called "Information Card."

2. Select the Placeholders tab.

3. Click on "New placeholder."

4. Name it "Contents."

You can provide a label and a description if you wish; these will be displayed in the Template Editor.

1. Copy and paste the following script:

To keep this chapter simple, we are reusing the Alert Bootstrap classes. Other than that, there is one new statement here called render. As the name implies, this statement will render the contents of the @Contents placeholder. And that's it!

Now, place this widget on a template and notice that there is an additional container that was not previously shown in the other widgets we created. Try dragging some components, adding some text, or including other widgets in this container.

As you can see, placeholders are very easy to implement and incredibly powerful.

A veteran web developer knows that there are multiple ways to style HTML elements. For example, this can be done statically by including a <link rel="stylesheet" href="style.css">, or dynamically via JavaScript with element.style.backgroundColor = "tomato", to name a few. Yes! "Tomato" is, unironically, the best red color there is, in my personal opinion!

One way to style widgets is by using the Less editor under the Styles tab. Less is a CSS preprocessor that provides additional functionality on top of CSS. If you prefer not to write in Less, you can still write standard CSS without using any Less features.

If you do want to write in Less, you will also have access to built-in variables from Bootstrap 3, which can be very handy if you want to customize some of their components in a widget. You can find these variables in the right-side panel of the screen.

In this chapter, we are going to write a simple message box. If you are familiar with Bootstrap 3, you know they have an Alert component available out of the box, and we provide that as one of our base components. However, for the sake of this exercise, we will write one from scratch.

Creating the Message Widget

1. Create a new widget called "Message" in the "Widget Academy" library.

2. Copy and paste the following script:

1. Create a Literal Text Property called "Text" and place it in the General section.

2. Create a Dropdown Property called "Style" and place it in the Appearance section, with the following labels: "Info," "Success," and "Danger," and the corresponding values: "info," "success," and "danger." Note that the values are case-sensitive and should be in lowercase!

3. Finally, click on the Styles tab and copy and paste the following Less code:

Note that we are using the predefined Bootstrap branding color variables to ensure this widget adopts the color styles of the selected design template in a portal, making it look nice across various design templates. Additionally, we use two Less color functions: lighten() and darken() to differentiate the branding colors from the background, border, and text color of the message box.

My guess is that you are eager to build a widget on your own, and your fingers are itching to write some code! But as the great Uncle Ben from Peter Parker famously said, "With great power comes great responsibility." While this quote was ironically popularized by the movie Spider-Man, it holds true nonetheless. So, sit tight, and let’s have a candid discussion about the risks and responsibilities involved.

WEM is a no-code platform that allows you to create applications ten times faster than traditional methods. We are proud to share customer stories that prove this. With the development of AI, it’s not unreasonable to think that we will be able to build apps even faster. However, what people often overlook is that WEM implements numerous safety precautions, enabling you to build without worry while it handles the hard work in the background, allowing you to sleep soundly at night.

I’m referring to safety on a technical level. I’m not suggesting that WEM guarantees you will never create unsafe applications. For instance, someone might forget to add authorization to a sensitive page that displays client information openly. This is a user error that WEM cannot prevent. WEM provides you with tools built on universal standards to implement authorization, but it cannot ensure that you will implement it correctly. Think of WEM as a car equipped with bulletproof glass; it offers protection, but if a reckless driver looks too deeply into the glass, don’t be surprised if the car comes home with bumps and scratches.

"What does this have to do with widgets?" With widgets, you gain more control—essentially, more power. And you know what Uncle Ben said? Building widgets requires not only extensive knowledge of HTML, CSS, and JavaScript but also an understanding of how the WEM Runtime works. It’s a lot to take in, and if you’re not careful, you might inadvertently introduce XSS (cross-site scripting) vulnerabilities into your widget without even realizing it.

I take my job as a programmer very seriously, and you should too. I see too many people copying code from the internet and pasting it without understanding what it does. "It works, so it must be fine, right?" So, I want to ask you a question: Are you a good programmer, or a good Googler?

Do you know the dangers of using innerHTML? It seems safe to use, right? After all, any <script> tags are ignored, so it should be perfectly safe. Well, not quite.

Here’s something interesting. Do you know what the following CSS does?

That’s right! This is a stripped-down version of a keylogger written in CSS! What about this one?

Yes, if you are creative enough, you can even execute scripts without using <script> blocks. In the example above, because the image "x" does not exist, the onerror event will be triggered. So even if innerHTML ignores <script> blocks, there are still ways to execute all kinds of malicious actions.

From this point forward, a strong knowledge of HTML, CSS, and JavaScript is essential. I’m going to be more strict this time. If you don’t understand the dangers of using innerHTML, you should. If you don’t know why it’s important to encode output, you should. We are going to delve deeper and get more technical, so strap yourself in a little tighter, and let’s go!

In the previous module of the view state chapter on building the Message Widget, 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:

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:

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.

On this page, you will find example widgets that are created as you follow the chapters. You can download the widgets and then import them into your own library to take a look. You can even use and modify them to your liking if you wish.

Please note that the widgets created in the widget chapters are being updated to comply with CSP (Content Security Policy) standards. They are also being modified to prevent any collisions in the global scope.

Basics

Below are the widgets that you will create as you follow the basics module.

Hello, You!

A simple widget that demonstrates the use of the text property, HTML-encoded to output a name.

Six-Sided Die

A widget that simulates a six-sided die. To ensure that this widget is CSP (Content Security Policy) compliant, it utilizes the startupscript to add a click listener to the "Roll Again" button, which refreshes the page.

Message - Example 1

This widget is similar to the Alert component in Bootstrap. You can expand or collapse the message by clicking on it, demonstrating how the WEM view state fields functions.

Message - Example 2

This widget functions similarly to Example 1, but it utilizes the WEM Runtime.viewState JavaScript API instead.

Message - Example 3

This message widget uses sessionStorage to store the view state and employs an ES module that utilizes Shadow DOM to prevent global scope collisions.

Tickle

This widget demonstrates how to use the import() function to dynamically load script modules, preventing collisions in the global scope. It also utilizes the Shadow DOM to style the widget, further avoiding CSS conflicts.

Information Card

This widget demonstrates how easy it is to implement placeholders and highlights their powerful capabilities. It also provides an example of how to create a Template Editor Script.

Other Examples

More coming soon.

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 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

There is one important aspect to address before concluding this chapter. When you use widgets in a WEM project, the WEM runtime will render these widgets within the page, and the styles and JavaScript associated with the widget will be added in a global context. Therefore, you must be careful when naming your CSS selectors and JavaScript identifiers, just as you would when building a standard website.

While there are modern solutions to this issue, WEM does not yet support all of them. In later chapters, we will explore these solutions in greater detail. For now, let's take a brief look at the potential issues.

CSS

In CSS, naming collisions occur when two or more styles are defined with the same selector. This can lead to unexpected results, potentially overriding earlier styles. For example, consider the following:

Design systems like Bootstrap often use simple class names such as .btn

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.

A richtext type variable is used to represent and manipulate a sequence of characters that holds rich content.

Implicit HTML Encoding

When you concatenate a text value to a richtext variable, implicit encoding is applied to the text value. This is not always desired; therefore, the ToRichText() function can be used. Let’s dissect the example above.

This line declares the variable @rt as richtext

The concept is a special kind of type. The values of a concept are not known within the context of a widget. However, if you create a generic widget, you don't need to know them. Let’s take a look at the following WEMscript to illustrate this.

Throughout the examples, we will assume we have a concept data model property called ConceptProperty.

Notice that everything works except for the assignment of the 'Colors'.'Red' concept literal, which is unknown in the context of a widget and only recognized within a project. To assign a concept data model property a new value, we use arbitrary IDs by calling the ConceptId() function. Fortunately, these IDs are just integers and can be easily passed around in the code.

Now, let’s look at the following dropdown example widget that uses a range of concepts to set the @ConceptProperty:

A text type variable is used to represent and manipulate a sequence of characters.

Postback

Writing a widget that uses a text property is quite straightforward and is likely the easiest type to implement.

You don't need to do anything special when using the text type in JavaScript, as it is similar to the String type in JavaScript.

Finally, we no longer have to worry about naming collisions and overwriting other code when using ES Modules. We can use generic class names like Button or Note without adding extra noise to our code, making it much more enjoyable to read and write. However, is there a similar solution for CSS, like CSS Modules? Unfortunately, no. Nevertheless, the W3C seems to be working on it.

This is unfortunate, as we have found a way to encapsulate JavaScript code from other widgets, but our CSS still lacks this capability. However, there is a solution: we can style elements programmatically within JavaScript. While you can style elements using element.style.propertyName, a better approach is to use Web Components with the Shadow DOM.

If we modify the code of our Note widget to utilize the Shadow DOM, it would look something like this:

In this code, we use CSSStyleSheet and call the replaceSync() method to set the CSS. As you can see, we use very generic class names like .message

To maintain the state of the scroll position of an HTML element, the zoom position of a chart, or any state that is specific to the view when the widget needs to be redrawn, we can use the view state. This state is accessible when the widget is rendered on a template but is destroyed when the widget is no longer rendered. We will discuss this in more detail in later chapters. For now, let's extend our previous "Message" widget to include the ability to collapse and expand.

Extending the Message Widget

1. Copy and paste the following script:

Notice that we are registering an event again using register event @ToggleCollapseState. We will create an event later that will change the view state. In the second line, you will notice the @Collapsed variable. This is a view state variable (also called a view state field). We assign the @Collapsed variable to its original value, but when it is unknownboolean, we assign it the value false. This ensures that the toggle behavior functions correctly. More on that in the event we will create shortly.

Creating the View State Field

To create the view state field:

1. Click the "View state" tab.

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

3. Name it "Collapsed."

4. Select "Boolean" as the type.

Creating the Toggle Event

Now let's create the event:

1. Create the "ToggleCollapseState" event.

2. Copy and paste the following event code:

Notice that if we did not assign @Collapsed to false when it was unknownboolean, this event would not work, because assigning a variable with not unknownboolean still results in unknownboolean.

Updating the Less Style

The Less style of the widget has also been updated. Replace the existing style with the following:

Now, preview the widget, and you will see that it is clickable and toggles between an expanded and a collapsed state. Notice that if you refresh the page, the view state still exists. Maintaining the view state is essential for creating a good user experience (UX).

These are just the basics of view state. For instance, you can also manage view state via JavaScript using the WEM Runtime.viewState, or the native localStorage, and sessionStorage APIs, which we will explore in more detail in later chapters.

This function has multiple use cases and is essential for ensuring that the widget functions correctly. We previously used this function to create a unique identifier value for the id HTML attribute. Another important role of this function is to generate identifiers for HTML input fields, enabling two-way binding with writable data field properties of the widget. In other words, it facilitates sending data back.

Let's create a very simple form item to see it in action:

• Create a new widget and name it "Simple Form Example."

• Create two new data model text properties called "FirstName" and "LastName."

• Make both properties writable and required.

• Use the script below:

For those familiar with sending form data over the internet, there is nothing new here. Just like in regular HTML forms, we use the <input> element to edit and submit the data. One interesting aspect is the use of OutputId(@PropertyName) in the name attribute. We cannot simply use name="PropertyName" here, as that would lead to name collisions if there are multiple instances of this widget on the same page. In other words, OutputId(@PropertyName) ensures that we get a unique name for this property specific to each widget instance.

Next, we will write a more exciting widget: a note widget that you can drag around the screen. This will explain many concepts, especially those related to creating WEM widgets.

A boolean variable can be set using the keywords true, false, unknownboolean, or a WEM expression that returns a boolean type.

When performing a postback, it is essential to send the text "true", "false", or an empty string "" to update the property to the respective values of true, false, and unknownboolean. This requires careful attention when sending data back.

Let’s examine some examples and analyze them.

All examples feature a writable boolean data model property called BooleanProperty.

Boolean Textfield Postback Example

Aside from the poor user experience, this approach does not work because when the portal language is set to English, <?attr @BooleanProperty ?> will output "yes" when @BooleanProperty is true and "no" when it is false. These outputs are invalid boolean values for a postback. As a workaround, you could use <?js @BooleanProperty ?> instead, as it will output true, false, and unknownboolean as "true", "false", and "null" respectively. However, "null" is an invalid value, so it will be interpreted as unknownboolean. But please keep this workaround confidential.

Since we typically do not create a boolean text field, let’s explore more common boolean input fields.

Radio Buttons Postback Example

In this example, we register the input @BooleanProperty and create three radio buttons with the text values "true", "false", and an empty string "" to set the value to unknownboolean. We check the current state of @BooleanProperty and add the checked attribute if it corresponds to the option value. Note that if @BooleanProperty is unknown, checking whether it is true will always return false, so we do not need to use IsKnown(@BooleanProperty) for the "true" and "false" options.

Checkbox (True/Unknown) Postback Example

This checkbox will set @BooleanProperty to either true or unknownboolean. This behavior is due to how the browser sends post data. If the checkbox is not checked, the browser will ignore it, resulting in the property assigned to this checkbox being set to unknownboolean. This may not always be the desired outcome, so let’s look at an improved version to address this issue.

Checkbox (True/False) Postback Example

In this example, we introduce a hidden input field that will be used to send the data back, along with an intermediate checkbox to read the current checked state in the submitscript. Depending on whether the checkbox is checked, we set the hidden input field to "true" or "false".

Regardless of the type of widget you are building, even a simple boolean can become complicated if not carefully considered.

A duration type represents a measure of the interval between two events or points in time in a platform-independent format.

Print Output Overview

Let's assume we declared var @d: duration, which holds a duration of '1d23h45m6s'—representing 1 day, 23 hours, 45 minutes, and 6 seconds.

A datetime type represents a single moment in time in a platform-independent format.

Postback Format

When performing a postback, the WEM runtime expects the datetime to be in ISO date format. You can use the FormatDate() function with the Iso8601 constant as the second argument to convert the datetime to this format.

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.

Keep in mind that storing state in sessionStorage or localStorage is permanent throughout the browser session or on your local machine. This can be a useful feature. However, if you want to clean up the view state, you need to do that manually, which can be quite tricky to implement.

Creating a widget to upload a file is relatively straightforward. It can be as simple as the following two lines of code, along with including a @File data model property field:

However, it becomes a bit trickier when working with dynamically created binary data instead of a static file on the desktop. Nowadays, in JavaScript, you can only create a binary file programmatically because browsers have become more restricted due to security measures. Additionally, you can only assign a file to a file input through user interaction, such as a button click.

Let’s first look at how to do it the traditional way, and then follow that up with a more modern approach.

If you examine the code below, you may wonder where the base64 option in the register input comes into play. The reason for this is legacy. Previously, JavaScript did not have an out-of-the-box solution for creating native files; it only offered emulation using a string or an array of numbers. This is how WEM could provide a way to upload files in base64 format. Let’s examine our script below using base64 as an option:

Looks pretty cool, right? You simply encode the "Hello" text, and you're good to go. However, be aware that several issues can arise if you're not careful; we are using a simple "Hello" text as an example. Let’s walk through the process.

When we refer to a resource, we mean any type of file that will be embedded with the widget. This can include images, sounds, PDF documents, JavaScript, CSS, XML files, and more.

In this chapter, we are going to create a CSS file, a JavaScript file, embed a video, and add them as resources to our widget. Let's get started!

A conceptset type holds a set of items of type concept. This conceptset has no predefined range and accepts any concept, which distinguishes it from a concept data field that does have a range.

Checkbox List Example

In this example, we register input for our @ConceptSetProperty

We have seen that if you are not careful, it can be very easy to overwrite classes and functions. Is there really no way to solve this? Yes! The solution lies in ES Modules. Unfortunately, WEM widgets were built before ES Modules became widely adopted. However, while it may not be perfect, using the building blocks that WEM provides can get you close enough if you know what you are doing. ES Modules is a feature in JavaScript that helps encapsulate code, making it possible to use imports and exports to manage sections of code. Let’s see how this can help us fix naming collisions once and for all!

Let’s imagine we have two separate JavaScript modules, each containing a function with the same name.

Normally, we would encounter a problem if we embedded these files using scriptreference. The first issue is naming collisions, and the second is that the export keyword is reserved for use in a module. To use both functions, we need to import them. There are two ways to do this: one is with <script type="module">, and the other is with the import() function. Unfortunately, while using the <script> tag is the easiest method, we cannot use it due to the way the WEM runtime handles loading dynamic scripts. Therefore, we are limited to using

A number type variable holds a numeric value in literal forms such as 255 or 3.14159.

Postback

To create a widget that performs a simple postback, you would write something like this:

In the example above, we created a simple text field that outputs the value of @NumberProperty. This example is culture-independent, and the WEM runtime checks the culture settings of the portal, using the appropriate number format for validation. For instance, if you set the culture settings to Dutch, the number will be formatted as

In the previous chapter, we were introduced to the specific types of script blocks and when to use them. Within these blocks, we use window[Symbol.for(<?js OutputId() ?>)] to assign it to the instance of the Note widget. But what is the purpose of this? Let's examine what is happening under the hood to understand it better.

Let’s take the following widget as an example and see how the final rendered page output will look:

When inspecting the code output of the page and observing how this widget has been rendered, it roughly translates to the following stripped-down output:

A few interesting things are happening here. The scriptmodule is JavaScript code inside a <script> tag that has been added to the <head> section. The scriptreference behaves similarly. The regular <script> blocks are rendered as part of the page body content. However, you will notice that the code inside the other script blocks is registered at the end of the <body> in anonymous functions.

It is therefore crucial that your function and class names are unique when used in a scriptmodule or scriptreference. To clarify, consider these two widgets created by Bob and Jane:

This will output roughly to:

In this case, Bob's button is overwritten by Jane's, which is problematic. The scriptreference faces the same issue, as the script is loaded externally instead of being embedded within the page itself.

We resolved this issue in the Note widget by using class WemAcademyNote instead of class Note. While this is not a perfect solution, it helps minimize naming collisions.

There are other ways to address this naming collision, but they come with trade-offs. I will explain those later. First, let’s take a closer look at window[Symbol.for(<?js OutputId() ?>)]. Notice that the startupscript, submitscript, and unloadscript are anonymous functions. But what if we need access to context outside their local scope? This was the problem we encountered in the Note widget. To achieve this, we need a way to share state between those functions, which requires a global context. However, this can be very risky if not handled carefully.

Let's examine a stripped-down version of initializing and disposing of the Note widget from the previous chapter in a potentially dangerous way:

This will output roughly to:

In this example, we declared a global variable note, which can be risky. If another piece of JavaScript code uses a global variable with the same name, we may encounter undefined behavior. In this case, we could inadvertently overwrite someone else's note variable. This is a classic pitfall of using global variables!

However, there is a way to make this global variable "hidden." Let's dissect window[Symbol.for(<?js OutputId() ?>)] using the following code:

This will output to the following:

Here, we see that <? OutputId() ?> has printed "cc1". As we learned in previous chapters, OutputId() creates a unique identifier for each instance of the widget on the page. This means that if we add multiple instances of this widget, the identifiers will be "cc2", "cc3", and so on. Note that we use "cc1" as an example, and it is bound to the implementation of the WEM Runtime, so it can be anything.

The window object is the global object in JavaScript, and the Symbol class is particularly interesting here. It creates symbols that are guaranteed to be unique. In our case, we use it to create a unique key that we store in window, effectively creating our "hidden" global variable. In other words, this approach provides a form of weak encapsulation or weak information hiding.

You might wonder, "What if we navigate to the next page? Wouldn't we potentially have another instance of a widget called cc1?" Yes, that is true, but it does not matter because we disposed of the instance of the note in the previous unloadscript. Therefore, it is acceptable to overwrite the contents of window[Symbol.for("cc1")].

In our Note widget, we implemented the following:

To ensure that we clean everything up, we also delete our "hidden" global variable, as shown above. This helps the JavaScript garbage collector free up memory space. More importantly, it ensures that we do not have access to the variable after it has been used.

Encoding is an essential aspect of building widgets and web development in general for several reasons, primarily related to security and data integrity. If you are not careful, your widget can pass along incorrect values to a JavaScript library, resulting in a broken layout or even making it vulnerable to the injection of malicious scripts.

Encoding is automatically handled for you with the print statement; however, you still need to exercise caution. Common scenarios requiring encoding include displaying user input from a text field or configuring a JavaScript instance with the property values of the widget.

WEMscript offers three methods of encoding: HTML encoding, HTML attribute encoding, and JavaScript encoding. You can achieve these by calling the print statement with the first arguments html, attr, and js, respectively. There is also a fourth method: printing without encoding, often referred to as printing raw.

Shorthand Notations

Since you will frequently use the print statement, WEMscript provides a few shorthand notations to simplify your work. We have already used some of these, and you should be familiar with them:

The WEMscript above can be rewritten more concisely as follows:

From now on, we will use shorthand notation whenever possible.

Raw

The simplest yet most dangerous way to print output is to do so without any encoding. This method should be handled with extreme caution. Here is an example of how not to use raw printing:

The above example is very risky. Using raw printing can lead to errors if you are not careful, not to mention the security risks! For instance, if the property @Name is set to the value: Bob<script> runMaliciousScript(); </script>, the output would be vulnerable to XSS.

We can mitigate this risk by using HTML encoding.

HTML

HTML has special characters that are reserved for specific meanings (e.g., < for opening tags, > for closing tags). If these characters are included in user input without encoding, they can disrupt the structure of the HTML document. We need to convert these characters into their corresponding HTML entities (e.g., < becomes <, > becomes >), preserving the intended content and ensuring it is displayed correctly. We can make the previous code safer by changing <?raw to <?=, as shown below:

If a hacker attempts to insert <script> blocks, they will be printed as <script> and will not be parsed as script blocks but rather as the literal text "<script>".

HTML Attribute

HTML attributes are similar to HTML and should always be encoded using either print attr "value" or <?attr "value" ?>. In the following example, we encode the title attribute:

JavaScript

Encoding in JavaScript is somewhat unique because you also have to consider the language settings of the portal in which the application is running. For instance, the number 3.14159 is written as 3,14159 in Dutch (note the comma). If we print a boolean value without encoding, we will receive the values yes and no in English, while in Dutch, we get ja and nee, respectively. All of these are invalid boolean values in JavaScript. Therefore, it is crucial to encode values correctly in JavaScript. Here is a bad example that demonstrates the consequences of not encoding JavaScript values.

This will translate to the following JavaScript code in the runtime if we run it with Dutch as the portal language setting.

As you can see, many issues arise in this code, and some errors may even go unnoticed! Note the comma operator (,) when trying to assign the variable b. This is not a syntax error; it is a valid operator that is rarely used in JavaScript.

Now, let’s consider what happens if we change the portal language to English.

Once again, we encounter multiple errors. However, this time the number variable b is set correctly by accident. Let’s fix this by properly encoding the JavaScript values:

This translates to:

The values are now correctly set, regardless of the portal language settings in the context of JavaScript. Note that you do not need to include quotes for text values.

CSS (Hack)

You might expect that there is a similar method for CSS, such as <?css ?>, but unfortunately, WEMscript does not provide this. It is quite non-trivial. However, although it may seem hacky, there are cases where you can use <?js and <?=, but you need to be cautious. Additionally, since CSS is heavily unit-based (e.g., 20px, 4vw), you often need to manually add the units in most print statements.

Let’s look at the following example, assuming that @Width and @Height are both widget number properties:

Let’s set the @Width and @Height properties to 320 and 200, respectively. This will translate to:

This works. But what if the properties are of type unknownnumber? In that case, both values would be nullpx, resulting in an invalid CSS property value. This may need to be fixed, depending on the widget.

What if you want to set a more flexible value for a CSS property? For instance, a margin value like auto or 8px 16px 8px? We can use a text property for this case, but make sure to HTML encode it. Let’s consider the following example, assuming we have a @Margin widget text property:

If we have the text value 16px 8px for our margin, it will translate to:

Now, what if we think like a hacker and set the text value to auto;}</style><script>console.log('Hacked!')</script> as our margin?

As you can see, once again, the <?raw method is very dangerous and must be used with caution. In this case, using <?= is the better option. While it can result in CSS syntax errors if an incorrect value is set, it is far preferable to leaving the widget vulnerable to XSS attacks!

In this chapter, we will create a Note widget. It is a relatively simple widget to build, but we need to address a few challenges to ensure it functions correctly as a WEM widget.

As mentioned previously, adding widgets will introduce CSS and JavaScript into a global space. This can be quite challenging for more advanced widgets, as we want to avoid overriding and breaking existing CSS and JavaScript. Therefore, we will start with some scaffolding to see how we can prevent these issues.

We will learn about invariant culture, naming collisions, cleaning up the widget, and a few other concepts along the way. Let's get started!

• Create a new widget and name it "Note."

• Copy and paste the following CSS into a new file called "note.css."