UBIK Active Lists

UBIK^® ActiveLists provide the possibility to configure instance-specific lists for integer MetaProperties.

Purpose

In some cases it is required to define a list of selectable values for an integer MetaProperty that is specific to a single instance rather than globally defined at the MetaClass level. For example, two instances of the same MetaClass can offer different selectable values for the same MetaProperty.

UBIK^® ActiveLists are the representation of such lists. They update dynamically on the client side without requiring an ACM rebuild and can be maintained per instance through server methods.

If a MetaProperty has both a SelectiveList and an ActiveList, the SelectiveList takes precedence when data is displayed on the client, and the ActiveList is ignored.

Client Behavior

When an integer MetaProperty has an ActiveList defined, the property is displayed using the existing icon (the same icon applied to properties with a SelectiveList), followed by the property's display string and the label of the currently selected list item in a closed drop-down component.

For editing, the client uses a dropdown menu UI component. The dropdown menu enables users to select exactly one value for the MetaProperty from the ActiveList. When the user opens the dropdown:

• All available options from the ActiveList are displayed as text labels.
• The label for each option is shown in the language configured on the web service. If a translation for the configured language is unavailable, the label is displayed in the default language.
• Each option in the ActiveList has an associated unique integer value that is set to the MetaProperty when selected.
• Only one option can be selected at a time. Selecting an option updates the MetaProperty value immediately.

Sorting of items in the dropdown:

• If all options in the ActiveList have unique sort order values, they are displayed in ascending order of these sort order values.
• If sort orders are not unique, options with the same sort order are sorted in ascending order by their label.

Server-Side Concept

ActiveLists are stored in serialized JSON form in the ACTIVE_LISTS property of the instance.

• Each list is associated with exactly one integer MetaProperty of the instance.
• An instance can have multiple ActiveLists, one for each integer MetaProperty.
• ActiveLists can be viewed in UBIK.Studio in the Object Explorer under “ActiveLists” for the instance, but they cannot be edited there.

Managing UBIK^® ActiveLists

ActiveLists are managed entirely through server methods. The most relevant methods are:

AddOrUpdateActiveList(metaProperty, value, labels, sortOrder)

Adds a new list item or updates the labels of an existing one. Optionally repositions the item according to sortOrder.

SortActiveList(metaProperty, orderedValues)

Reorders the items of a list according to the specified sequence. Items not included in orderedValues are appended in their current order.

RemoveActiveListItem(metaProperty, value)

Removes a single list item by its integer value.

RemoveActiveList(metaProperty)

Removes the entire list for the given MetaProperty.

GetActiveLists()

Returns all ActiveLists defined on the instance as UbikActiveList objects, each containing the MetaProperty name and its list items.

Who-Bert Example

The following Who-Bert snippet demonstrates how to work with an ActiveList for a MetaProperty named "MP_INT_A":

using System;
using System.Windows.Forms;
using System.Linq;
using System.Collections.Generic;
using UBIK.Kernel;
using UBIK.Runtime;
using UBIK.Runtime.Sys;
using UBIK.Compiler;
using UBIK.Content;

namespace Studio
{
    public class ObjectTest
    {
        public void TestObject(params BaseClass\[] InVariables)
        {
            Debugger.Output(this, "\*\*\* Started ActiveList Example");
            foreach (BaseClass obj in InVariables)
            {
                ContentClass c = obj as ContentClass;

                var labels1 = new Dictionary<string, string> { { "en", "One" }, { "de", "Eins" } };
                var labels2 = new Dictionary<string, string> { { "en", "Two" }, { "de", "Zwei" } };
                var labels3 = new Dictionary<string, string> { { "en", "Three" }, { "de", "Drei" } };

                // Add items
                c.AddOrUpdateActiveList("MP_INT_A", 1, labels1);
                c.AddOrUpdateActiveList("MP_INT_A", 2, labels2);
                c.AddOrUpdateActiveList("MP_INT_A", 3, labels3);

                // Update labels and move item 3 to index 0
                var labels3Updated = new Dictionary<string, string> { { "en", "Three Updated" }, { "de", "Drei Aktualisiert" } };
                c.AddOrUpdateActiveList("MP_INT_A", 3, labels3Updated, 0);

                // Sort items: 2, 1, 3
                c.SortActiveList("MP_INT_A", new int[] { 2, 1, 3 });

                // Remove item 1
                c.RemoveActiveListItem("MP_INT_A", 1);

                c.Save();
            }
            Debugger.Output(this, "*** Finished ActiveList Example");
        }
    }
}

Further Notes

• ActiveLists are designed for lightweight, instance-specific value lists that can be updated without ACM rebuilds.
• They are ideal for use cases where list content varies between instances of the same MetaClass.
• When both an ActiveList and a SelectiveList are defined for the same MetaProperty, the SelectiveList overrides the ActiveList on the client.