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 ActiveList takes precedence when data is displayed on the client, and the SelectiveList is ignored.
Client Behavior
When the user opens an ActiveList:
- 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.
For more details see: Active List Client
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.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 ActiveList overrides the SelectiveList on the client.