Loading...

What are Group Values?

Group Values are only of interest for those who use the Web Server feature with the optional feature "Unlimited Web Clients" in Widget Designer. The Web Server allows to view your Widget Designer interface with an external web browser. As you can "load" the programmed interface in several browsers, you can see and use it in various places.
Sometimes, you might not want all those interfaces to show exactly the same thing, e.g. when one participant moves a fader, the faders in the other interfaces should not move. You might want to use each fader in each browser, or even in each browser tab, independently from each other, and you might want to be able to read out every single fader value.

This is what Group Values are for. If a Widget is assigned to a Group, it creates instances of itself. Instances can be synchronized or differ from other instances. Two fader instances for example can have the same or a different value. Label instances can be even more multifaceted: two label instances can display the same text but have different text colors. In other words, if a Label is assigned to a group, its text and its color property become Group Values that can differ within the Group. The Fader value and the Label color depend on the place where you see and use the interface.

Before we have a deeper look at the meaning of "Groups", just bear in mind that every Widget supports different Group Values. A Fader supports only a multifaceted value (handle position) whilst a Label supports also some multifaceted properties but a CustomScript button cannot be assigned to a group i.e. has no Group Values at all. A CustomScript button can only be used globally. As nodes are also operating globally only, the usage of those in a Group context is not possible.

Working with Group Values requires being familiar with the concept of Context object notation. In this chapter, you will also find a list and description of context based members dealing with clients and Group Values.

What is a Group and a Key?

Each widget can belong to exactly one Group. Within the WD project however, you can define multiple Groups that you use for different widgets and windows. Per default, a widget is not assigned to a Group at all, which means that it is synchronized in all interfaces (the main Widget Designer interface and all browsers that connect to it).

Widget Designer offers four default Groups, and on top you can create custom ones.
This default Group consists of two Group sections, the first is called "Internal" and the other "External". The Internal Group section refers to the main Widget Designer user interface and cannot be subdivided further. The external section however refers to all interfaces outside of WD. Every browser that connects to the Web Server to render our widgets is part of the external Group section. Per definition, the widget's Group Values are synchronized when they belong to the same section, which means they are synchronized in all browsers. The main WD is the internal section and can differ from the external one.
The explanation of this behavior introduces the term "Key". By assigning a widget to a Group, instances are created. Each instance is identified by a so called Key. The Keys in the InternalExternal Group are simply called "internal" and "external". So there is a set of widget instances that have the "internal" Key and there is a set that has the "external" Key. The main Widget Designer displays the widgets instance with the internal Key, all other browsers get a copy of the widget instances with the external Key. For other Groups it is possible that every single widget instance gets a different Key when it is displayed in another interface, those Keys are less readable as they are a strings with letters and numbers.

Default Groups

There are four default Groups which generate Keys automatically for each object. The Keys are always created for any client accessing the interface, no matter which version of Widget Designer is running.

However, only the Unlimited Webclients version enables you to make use of Groups and Group Values, including differing instances of the same object.

 
- Client:
Each tab inside a single browser equals one Client. Even if you refresh a browser tab, a new Client Key is generated for this tab. The Key consists of a string of hexadecimal characters, e.g. "c21e4700-11aa-22bb-33cc-44dd55ee66ff"

- Session:
Each browser that connects to the Widget Designer generates a new Session Key. This Key looks similar to a Client Key, e.g. "5e551040-f00f-e99e-d88d-c7b6a55a6b7c".

This is probably the most used group as it covers the majority of applications and additionally offers you the possibility to store and retrieve data. Please also have a look at the chapter Session and Session Value for an introduction to this powerful tool.
This also means that a second, different browser creates a new Session and a new Client, while a new tab of the same browser only generates a new Client Key. It still belongs to the same Session as the first tab.

- InternalExternal:
"Internal" comprises all objects inside the main Widget Designer user interface, "external" describes every object accessed from an external browser (even on the same PC). The Keys here are simply "internal" and "external".

- IPAddress:
This Group distinguishes between different IP addresses for assigning Keys. The key here equals the participating IP address, or "localhost" if it is the Main GUI.

How to assign Groups

For a better understanding of the previous point, the workflow of assigning Groups will be explained with the help of a short exercise, it will only take you about ten minutes.

First, open a new project and create four faders next to each other. Open the the faders' property dialogs and assign each of them to one of the four default Groups. This can be done by opening the Group Values tab and selecting the respective Group in the drop-down. For having a better overview, you can add optional labels for each fader showing which Group it belongs to.

Next, open a browser on the same PC and access the project with "localhost\Window1#Page1". Open a second tab in the same browser and enter the same address. You have now created one Session with two clients. Open a second, different browser and access the project again, you have now created a second Session with one client. Regarding the Internal/External Group, you have now one client with the Key "internal", which is the Main GUI, and three clients with the Key "external".

Now, go back to the Widget Designer and set the faders to different values whilst looking at the faders in the different tabs and browsers to see which faders are linked. Of course, you can also move a "web" fader. You can also add more tabs to the browsers or refresh a tab and see what happens. If you open the Group Values List (Fader Item Properties > Group Values > Show Group Values or Edit > Web Server Settings > Group Values), you can see all values of all fader instances and their respective Keys. The list does not update automatically, so you will have to press "Refresh" once in a while. If you have the possibility to add a second computer to your network, you can also access the project with this one, to see that the fader with the "IP" Group now also has another instance.

Custom Groups

Widget Designer also offers you the possibility to create your own Groups and assign your own Keys. These are called "Custom Groups".

To create Custom Groups, simply go to Edit > Web Server Settings > Global Settings.
If you want to change anything there, you have to stop the Web Server first by clicking the "Stop" button in the top left corner.

Enter the names of your custom groups in the respective field, multiple Group names can be separated either by a comma or a white space. Use only letters (capital or lowercase), numbers and underscores for your group names, the name has to start with a letter.

Do not forget to start the Web Server again after doing your settings.

Now let us add this feature to our test project with the faders. Add a Custom Group "Sea" to your project and create a fifth fader. Assign this fader the new Group, which was automatically added to the Group drop-down.

What you have to consider when using Custom Groups, is that the Key here is not automatically generated, you have to assign your own Key manually to each client participating the project. We will now choose three different Keys, "Octopus", "Swordfish" and "Orca". To assign them, create three different CustomScript buttons and label them respective to the Key they generate. The script that will assign the Custom Key is:

Context.Client.Groups.Sea = "Key"

Put this script in each button's On Press Script field and replace "Key" with "Octopus", "Swordfish" and "Orca". If you press one of those buttons now, you assign this Key to this client. This specific browser tab (the script has to be executed for each new client) now has e.g. the Key "Swordfish" for all widgets belonging to the Group "Sea". Of course you can change this Key anytime by pressing one of the other buttons. The Context object makes sure that the script is executed ONLY in this single client and not globally for every client, although the button is indeed pressed simultaneously in all clients (the CustomScript button cannot have Group Values). For more information about context in general and the Context object, please refer to the chapter Project and Context Member.

Now try out the buttons and see how the "Sea"-faders are linked when the clients have the same Key for this Group.

This is of course a training example without any use in a real project. But imagine a game show, where there are three different teams, "Red", "Green" and "Blue". All members of these teams have to solve different tasks and each participant has a tablet PC where he or she has to enter the results, adding up a score. You can then create a Custom Group "Team" and use the Keys "TeamRed", "TeamGreen" and "TeamBlue" to synchronize the score for each group, while every member still can operate his or her own interface. Exchanging data or information between the team members is also imaginable.

Summary: A Custom Group is initialized in the Web Server Settings. To assign a Widget to a Group, open its Item Properties in the Main WD Interface. To initialize a key and assign all Widget instances to it, execute a command in the remote interface or main WD.

Accessing Widget Properties with Group Values

If you want to access the values of different instances of one widget with a script, you need to comply with a special syntax. If you used the normal object property, like e.g. "Label1.Text", it would set or return only the one global value. The global value of every widget is still active, even when a Group is set, but Group Values will always override it.

As soon as you have assigned a Group to a widget, you will notice that the Script Assistant will offer you four more members for it:

As all of these members return values like strings, doubles, list, etc., the respective data type members can be used in addition to that.
E.g.: "Fader5.GroupValues.Value.Avg" returns the average fader value of all Group Values of this fader.

With those members, you can proceed scripting like before, you can set and retrieve any Group Value property like a normal property. You can store them in variables for evaluation or integrate them in your application. An extremely useful tool for a user login system is the Session Value, of course it can also be used in combination with Group Values.

The Context object provides additional members for working with Keys and Session Values, you can e.g. find out which Client Key is used from which IP address or generate a list of Session Keys. Please refer to the chapter Project and Context Member for more information and examples.

Group Items

Each widget that is able to hold Group Values has a specific set of properties affected by the Group Values. They can be either read out or set like any other property.