Changes
Created page with "{{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 sel..."
{{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>
= 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.
= 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>
= 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.
