View source for 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{{Version/ServerSince|5.0.0.0}}.

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'''":

<syntaxhighlight lang="csharp">
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");
        }
    }
} </syntaxhighlight>

[[Category:ActiveList|UBIK Active Lists]]
[[Category:Server|UBIK Active Lists]]

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

[[Category:Server|UBIK Active Lists]]
[[Category:ActiveList|UBIK Active Lists]]