This article shows how to apply Dynamic Selective Lists (DynSL) in {{UBIK}}.
Throughout this tutorial, you will learn how to set up
* A a new Dynamic Selective List (DynSL)* Items selective items for the DynSL* A a target property using the DynSL* A a dependency property ultimately deciding the items of the DynSL for a specific target* A a criterion for choosing the items depending on a dependency property value
Getting these configurations to the mobile client is a critical part as well.
Also, the technical background is explained, so you can understand what's going on in case of unexpected behavior.
{{Hint|Preconditions: We assume you're familiar with [[MetaClass|MetaClasses]], [[Classification|Classifications]], and [[ACM|Abstract Content Management (ACM)]]. In other words, you should be capable of creating a small mobile app with {{UBIK}} before you start with this tutorial. Also, please read the [[Offline_Query_(UBIK_WinX)|Offline Query]] article, since this technique is used for Dynamic Selective Lists.}}
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/Begin}}<!-- DO NOT REMOVE THIS -->
= Instructions =
<!-- DO NOT MODIFY THE NAME OF THIS SECTION, BUT REMOVE IT IF NOT REQUIRED -->
== Preconditions ==
We assume you're familiar with [[MetaClass|MetaClasses]], [[Classification|Classifications]], and [[ACM|Abstract Content Management (ACM)]]. In other words, you should be capable of creating a small mobile app with {{UBIK}} before you start with this tutorial.
== Goal 1: Create a new Dynamic Selective List ==
=== Getting it to the mobile client ===
Next, we want to make sure the mobile client receives your DynSL.
* Create a new [[QUERYSCOPE|query scope ]] instance for the DynSL. Let's call it "QCS_DYN_SL" for example.* Assign the DynSL instance to the new query scopeby dragging the DynSL instance onto the "QUERY" field of the scope instance.
* Add the [[SYSCLS_OFFLINE_QUERY|Offline Query Classification]] to the scope.
* Add the [[SYSCLS_DYNAMIC_SELECTIVE_LIST|Dynamic Selective List Classification]] to your scope as well.
* Add the "QCS_DYN_SL" to the scope list of your ACM [[CONTEXT|context]].
* Add the "DynSL" instance to the infrastructure list of your ACM context.
== Goal 2: Create items for the Dynamic Selective List ==
=== Getting them to the mobile client ===
Now, let's ship the items to the mobile client.
* Create a [[METACLASSSCOPE|meta class scope ]] "MCS_DYN_SL_ITEM" for the item meta class ("MC_DYN_SL_ITEM").
* Add the scope to the list of all scopes of your ACM context.
* Also, add all items ("Denise", "Bob", and "Hugo") to the infrastructure list of your ACM context. You may use a query for that, of course.
In our example, "Bob", "Denise", and "Hugo" are all options. But let's say, as an arbitrary example, for our target object "InstanceWithDynSL", only "Denise" and "Bob" should be selectable values of the property "LNK_WITH_DYN_SL".
In any case, we require somebody to blame for this decision. After all, "Hugo" could feel left out and send a complaint to management, so we better have a scape goatscapegoat. The goal of this section is to create something so we can justify why "Denise" and "Bob" can be possible values, but "Hugo" isn't. Also, for the DynSL to work, the mobile client requires this information as well.
Our line of argumentation will be: the department has a specific requirement for items to be selectable, so the department rules are the reason only "Denise" and "Bob" are qualified.
=== Basic definition ===
* First, we need a new meta class "MC_DEPARTMENT".
* Add a meta property "MP_REQUIREMENT" to the scape goat scapegoat class.
* You can use any property type for that, but we'll just stick to "String" for this example.
* Now let's create a specific department with concrete qualification requirements: Create an instance "Department Alpha", because that sounds cool and important.
* Since our items have gained a security clearance now, we also have to send it to the client. Add the new meta property to the scope "MCS_DYN_SL_ITEM".
* Of course, we also want to have our department on the client. Also, the department should be a root object, and our test object "InstanceWithDynSL" should be below that department in the content hierarchy on the client. We trust you know how to achieve this!
* The department scope "MCS_DEPARTMENT" should also have the new meta property "MP_REQUIREMENT" as a scoped meta property.
So now, we've created a dependency property telling us why some of our items can be selected and some of them can't.
{{Hint|The dependency object specifying the value influencing the selectable items must be either the target object (the one with the DynSL property), or anywhere above it in the hierarchy.}}
== Goal 5: Add a criterion to connect the dots ==
We know why "Denise" and "Bob" can be selected for "InstanceWithDynSL". They have the right security clearance after all, which is required by the department "Department Alpha", which is the department above "InstanceWithDynSL". But we haven't documented that yet! And if it isn't written downs illegible, it doesn't exist. Quick, let's define this rule before "Hugo" gets to file a complaint. In order for the DynSL to be evaluated correctly on the client, we need to make this logical connection processible anyway.
=== Basic definition ===
Now that we have documented our security clearance criterion, we just have to tell the client.
* For this purpose, create a meta class scope "MCS_DYN_SL_CRITERION" for the meta class "MC_DYN_SL_CRITERION".
* Add the [[SYSCLS_DYNAMIC_SELECTIVE_LIST_CRITERION|Dynamic Selective List Criterion Classification]] to the scope.
* All the meta properties described above should also be added to the scope.
* Add the scope to the list of all scopes of your ACM context.
* Add the criterion instance ("SecurityClearanceCriterion") to the list of infrastructure objects.
* The new criterion must also be reflected on the dynamic selective list scope, because we need it for the offline query aspect of this feature: Add the meta property "MP_SECURITY_CLEARANCE" to the DynSL scope "QCS_DYN_SL". The reason for this is, that the DynSL is an offline query and requires a property to contain the criterion value. This value is resolved using the DynSL criterion.
{{Hint|Multiple criteria with different dependencies are supported. It is also possible to omit the dependency class restriction, so the closest object with the dependency property (ignoring the meta class) is used as dependency.}}
{{AttentionHint|A criterion property (like "MP_SECURITY_CLEARANCE" in our example) on the Dynamic Selective Items also has to appear on the Dynamic Selective List scope, because technically, an offline query is used in the background. It's recommended to read the details about [[Offline_Query_(UBIK_WinX)|Offline Queries]] to understand this.}} {{Hint|Dependency objects are looked up in the parent hierarchy of the object with the DynSL property. The closest "ancestor" with the correct class and a matching property is chosen as dependency object (and its matching property as dependency property). If an object has multiple parents, there can be multiple closest matching dependency objects - this can lead to a larger amount of selectable items, because the results for all dependency objects are accumulated.}}
[[Category:Client|Configure Dynamic Selective Lists]]
[[Category:How-To|Configure Dynamic Selective Lists]]
[[Category:Studio|Configure Dynamic Selective Lists]]
[[Category:Web service|Configure Dynamic Selective Lists]]
== Releasing the ACM meta definitions ==
* Change the IS_MULTI_VALUE_STRING property of the "SecurityClearanceCriterion" to True.
Now, after releasing the ACM meta definitions and restarting the web service, all items with security clearance levels "A" and "B" are possible choices and all of them should appear when editing "InstanceWithDynSL"'s property "LNK_WITH_DYN_SL". {{Hint|The multi-value string criterion can be thought of as linking multiple criteria with an "OR" disjunction. If you have multiple regular criteria, all of them must match for a selective item to be accepted as a possible item. But only one of the comma-separated values of a multi-value criterion needs to fit for it to match!}}
== More possibilities ==
You can configure Dynamic Selective Lists to allow much more complex scenarios. For example, you can remove the restriction for the dependency class on the criterion. You can define the target object as the dependency object, too, so it depends on a different property of itself. You can even specify multiple criteria, potentially with different dependency objects. It is also possible to define multiple properties with dynamic selective lists depending on each other successively.
== Known issue workaround: Not ignoring NULL criteria doesn't work ==
One of the features of DynSL is to specify a criterion with the dependency value NULL that should only yield items with the criterion property value NULL (instead of just yielding every result). This can be achieved by setting the criterion's "IGNORE_NULL" property to False and the dependency property value to NULL.
Or rather, it should be achieved that way; there is a bug on the WinX client in version 4, which basically always ignores null values no matter the criterion configuration. Fortunately, there's a workaround:
If you override the dependency property in customizing programmatically, so it always returns any value definitely never occurring "in the wild" instead of NULL, and do the same for the item's criterion property, you achieve the desired result. We're working on fixing the bug, but in the meantime this should help you work around it.
<source lang = "csharp">
// do this for both the dependency property as well as the item's criterion property
var val = base.MY_PROPERTY;
return val ?? "NULL"; // this is the same as saying, 'If the value is not null, use it. Else, use whatever I wrote after the "??" operator'
</source>
Why does this work? Currently, the client handles NULL values differently than regular values (ignoring them, basically). However, with the above code you're changing a NULL into a regular value, so there's no extra behavior.
<!-- = Studio = -->
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/End}}<!-- DO NOT REMOVE THIS -->
[[Category:Client|Configure Dynamic Selective Lists]]
[[Category:How-To|Configure Dynamic Selective Lists]]
[[Category:Studio|Configure Dynamic Selective Lists]]
[[Category:Web service|Configure Dynamic Selective Lists]]
==See also==
* [[SYSCLS_DYNAMIC_SELECTIVE_LIST_CRITERION|Dynamic Selective List Criterion Classification]]
* [[Dynamic_Selective_List_(Client)]]
* [[Offline_Query_(UBIK_WinX)|Offline Queries]]
* [[HowTo:Configure_the_ACM]]
* [[HowTo:Make_an_Object_appear_on_the_Mobile_Client]]
* [[HowTo:Make_a_Property_editable_on_Mobile_Client]]
[[Category:Client|Configure Dynamic Selective Lists]]