Jump to: navigation, search

Difference between revisions of "Traits"

Line 1: Line 1:
−
= {{UBIK}} Traits (Client) =
+
= Traits =
  
−
'''{{UBIK}} Traits''' provide the ability to define a dynamic list of lightweight properties for individual instances ({{UBIK}} objects). Unlike traditional {{UBIK}} Properties, which are rigidly bound to a [[MetaClass|MetaClass]], instances of the same entity can contain a different list of traits.  
+
'''{{UBIK}} Traits''' provide the ability to define a dynamic list of properties for individual instances ({{UBIK}} objects). Unlike traditional {{UBIK}} Properties, which are rigidly bound to a [[MetaClass|MetaClass]], instances of the same entity can contain a different list of traits.  
  
−
This feature is particularly useful for data that only becomes known at runtime or varies significantly from instance to instance.
+
This feature is particularly useful for data that only becomes known at runtime or varies significantly from instance to instance. Please note that traits do not use lazy loading, making them act rather "heavy weight" from a user's perspective.
  
 
{{Attention|This feature must be used wisely, too many traits could impact the performance. Traits do not replace properties.}}
 
{{Attention|This feature must be used wisely, too many traits could impact the performance. Traits do not replace properties.}}
Line 10: Line 10:
 
To work with traits in the UI (XAML), the <code>ContentViewModel</code> provides several dedicated accessors and collections.  
 
To work with traits in the UI (XAML), the <code>ContentViewModel</code> provides several dedicated accessors and collections.  
  
−
=== 1. ValueAccessors (Recommended for Read/Write) ===
+
=== 1. ValueAccessors (Read/Write) ===
−
The <code>ValueAccessors</code> acts as a combined dynamic value resolver. It is the '''preferred way''' to read or edit values in the UI because of its built-in fallback logic:
+
The <code>ValueAccessors</code> acts as a combined dynamic value resolver. It provides a built-in fallback logic:
 
# '''Trait Lookup:''' First attempts to resolve the value via a trait with the specified name.
 
# '''Trait Lookup:''' First attempts to resolve the value via a trait with the specified name.
−
# '''Property Fallback:''' If no trait is found, it queries a regular {{UBIK}} Property with that name.
+
# '''Property Fallback:''' If no trait is found, it queries a regular {{UBIK}} Property with that name (see [[PropertyByName]]).
 
# '''Default:''' If neither exists, it returns <code>null</code>.
 
# '''Default:''' If neither exists, it returns <code>null</code>.
 +
 +
{{Attention|'''Caution:''' Be careful when using ValueAccessors. If you mistype a property name in XAML, you might not notice the error immediately and spend unnecessary time debugging. If you know you strictly need properties, use standard property bindings.}}
 +
 +
'''XAML Example (Reading a value):'''
 +
<syntaxhighlight lang="xml">
 +
<Entry Text="{Binding ValueAccessors[NAME]}" />
 +
</syntaxhighlight>
 +
''(Replace NAME with the placeholder of your actual trait or property name)''
  
 
=== 2. TraitByName (Traits Only) ===
 
=== 2. TraitByName (Traits Only) ===
Line 20: Line 28:
 
* '''Usage:''' When you explicitly want to query ''only'' traits (e.g., read-only display in the UI).
 
* '''Usage:''' When you explicitly want to query ''only'' traits (e.g., read-only display in the UI).
  
−
 
+
'''XAML Example (Reading only Trait):'''
−
 
+
<syntaxhighlight lang="xml">
−
 
+
<Entry Text="{Binding TraitByName[TRAIT_NAME]}" />
 +
</syntaxhighlight>
 +
''(Replace TRAIT_NAME with the placeholder of your actual trait)''
  
 
=== 3. Values (Raw Data) ===
 
=== 3. Values (Raw Data) ===
 
This is a combined getter that returns the raw value directly from the dictionary, instead of providing a complex <code>TraitViewModel</code> or <code>PropertyViewModel</code>.
 
This is a combined getter that returns the raw value directly from the dictionary, instead of providing a complex <code>TraitViewModel</code> or <code>PropertyViewModel</code>.
 
* '''Usage:''' For pure display purposes or evaluations.
 
* '''Usage:''' For pure display purposes or evaluations.
 +
 +
'''XAML Example (Reading raw data):'''
 +
<syntaxhighlight lang="xml">
 +
<Entry Text="{Binding Values[NAME]}" />
 +
</syntaxhighlight>
 +
''(Replace NAME with the placeholder of your actual trait or property name)''
  
 
----
 
----
−
 
−
 
−
 
−
 
  
 
== Commands (Set & Create Values) ==
 
== Commands (Set & Create Values) ==
Line 40: Line 52:
 
* '''If the trait exists:''' The value will be overwritten.
 
* '''If the trait exists:''' The value will be overwritten.
 
* '''If a property exists:''' The property's value will be overwritten (if it is not locked/read-only).
 
* '''If a property exists:''' The property's value will be overwritten (if it is not locked/read-only).
−
* '''If neither exists:''' A new <code>TraitViewModel</code> is created and added to the {{UBIK}} content.
+
* '''If neither exists:''' A trait is added to the {{UBIK}} content.
  
−
----
+
'''XAML Example (Setting a value):'''
 +
To create traits entirely from scratch (or explicitly overwrite an existing value), pass the <code>Name</code> and <code>Value</code> parameters to the <code>SetValueCommand</code>.
  
−
== XAML Customizing / UI Integration ==
 
−
 
−
To display traits in custom XAML templates, make them editable, or create new ones, standard {{UBIK}} controls like <code>[[EvalExpression|EvalExpression]]</code> or <code>SfListViewExt</code> are used.
 
−
 
−
=== 1.Displaying all Traits in a List View (read-only) ===
 
−
If you simply want to display all traits of an object, you can bind directly to <code>Content.Traits</code>. Here it is combined with the Syncfusion ListView (<code>SfListViewExt</code>):
 
−
{{Attention| Bindings persist only on DataModel level which means changes on ViewModel level are only visible after saving.}}
 
 
<syntaxhighlight lang="xml">
 
<syntaxhighlight lang="xml">
−
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
 
−
 
−
<controls:SfListViewExt ItemsSource="{Binding Content.Traits}">
 
−
    <controls:SfListViewExt.ItemTemplate>
 
−
        <DataTemplate>
 
−
                <Grid ColumnDefinitions="0.4*, 0.6*">
 
−
                    <Label Grid.Column="0" Text="{Binding Name}" />
 
−
                    <Label Grid.Column="1" Text="{Binding Value}" />
 
−
                </Grid>
 
−
        </DataTemplate>
 
−
    </controls:SfListViewExt.ItemTemplate>
 
−
</controls:SfListViewExt>
 
−
</syntaxhighlight>
 
−
 
−
=== 2. Editing a single Trait or Property via ValueAccessors ===
 
−
To dynamically query and edit a specific trait, an <code>[[EvalExpression|EvalExpression]]</code> with the <code>ValueAccessors</code> Context should be used. The <code>TwoWay</code> binding ensures that changes are written directly back to the ViewModel.
 
−
 
−
<syntaxhighlight lang="xml">
 
−
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
 
−
 
−
<controls:EvalExpression x:Name="EvalS2" Context="{Binding ValueAccessors}" Expression="Context[P0]">
 
−
    <controls:EvalExpressionParameter Name="P0" Value="{Binding Path=Text, Source={x:Reference S2NameInput}}" />
 
−
</controls:EvalExpression>
 
−
 
−
<Entry x:Name="S2NameInput" />
 
−
 
−
<Entry x:Name="S2ValueInput" Text="{Binding Result.Value, Source={x:Reference EvalS2}, Mode=TwoWay}" />
 
−
</syntaxhighlight>
 
−
 
−
=== 3. Deleting a Trait ===
 
−
Deleting a trait does not require a dedicated command. Instead an event behavior can be used to directly invoke the <code>Delete</code> method on the evaluator's result..
 
−
 
−
<syntaxhighlight lang="xml">
 
−
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
 
−
 
−
<Button Text="Delete">
 
−
    <Button.Behaviors>
 
−
        <behaviors:EventHandlerBehavior EventName="Clicked">
 
−
            <behaviors:InvokeMethodAction TargetObject="{Binding Result, Source={x:Reference EvalS2}}" MethodName="Delete" />
 
−
        </behaviors:EventHandlerBehavior>
 
−
    </Button.Behaviors>
 
−
</Button>
 
−
</syntaxhighlight>
 
−
 
−
=== 4. Creating or overwriting a Trait via SetValueCommand ===
 
−
To create traits entirely from scratch (or to explicitly overwrite an existing value), the <code>SetValueCommand</code> of the <code>ContentViewModel</code> should be used. A <code>[[KeyValueList|KeyValueList]]</code> must be passed to this Command.
 
−
 
−
<syntaxhighlight lang="xml">
 
−
<Grid ColumnDefinitions="*, Auto" ColumnSpacing="10">
 
−
    <Entry x:Name="S4NameInput" Placeholder="Name of the (new) trait..." />
 
−
    <Entry x:Name="S4ValueInput" Grid.Column="0" Placeholder="Enter value to set..." />
 
−
   
 
−
    <Button Grid.Column="1" Command="{Binding SetValueCommand}" Text="Set">
 
−
        <Button.CommandParameter>
 
−
            <classes:KeyValueList>
 
−
                <classes:KeyValueParameter Key="PropertyName" Value="{Binding Text, Source={x:Reference S4NameInput}}" />
 
−
                <classes:KeyValueParameter Key="PropertyValue" Value="{Binding Text, Source={x:Reference S4ValueInput}}" />
 
−
            </classes:KeyValueList>
 
−
        </Button.CommandParameter>
 
−
    </Button>
 
−
</Grid>
 
−
</syntaxhighlight>
 
−
 
−
=== 5. Editing specific Data Types (e.g., DatePicker) ===
 
−
Traits store actual underlying Data types (such as <code>DateTime</code>). This means you can bind regular UI controls like a <code>DatePicker</code> directly to the result of the <code>[[EvalExpression|EvalExpression]]</code>.
 
−
 
−
<syntaxhighlight lang="xml">
 
−
<controls:EvalExpression x:Name="EvalDateTime" Context="{Binding}" Expression="Context.ValueAccessors[P0]">
 
−
    <controls:EvalExpressionParameter Name="P0" Value="{Binding Path=Text, Source={x:Reference DateTraitNameInput}}" />
 
−
</controls:EvalExpression>
 
−
 
−
<Entry x:Name="DateTraitNameInput" Text="TRAIT_DATETIME" />
 
−
 
−
<DatePicker x:Name="DateTestPicker" Date="{Binding Result.Value, Source={x:Reference EvalDateTime}}" Format="dd.MM.yyyy" />
 
−
 
 
<Button Command="{Binding SetValueCommand}" Text="Set">
 
<Button Command="{Binding SetValueCommand}" Text="Set">
 
     <Button.CommandParameter>
 
     <Button.CommandParameter>
 
         <classes:KeyValueList>
 
         <classes:KeyValueList>
−
             <classes:KeyValueParameter Key="PropertyName" Value="{Binding Text, Source={x:Reference DateTraitNameInput}}" />
+
             <classes:KeyValueParameter Key="Name" Value="MY_TRAIT_NAME" />
−
             <classes:KeyValueParameter Key="PropertyValue" Value="{Binding Date, Source={x:Reference DateTestPicker}}" />
+
             <classes:KeyValueParameter Key="Value" Value="My Trait Value" />
 
         </classes:KeyValueList>
 
         </classes:KeyValueList>
 
     </Button.CommandParameter>
 
     </Button.CommandParameter>
 
</Button>
 
</Button>
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
''(Note: Customizers can replace the static string placeholders with dynamic bindings to controls like Entry or DatePicker as needed)''
  
 
----
 
----

Revision as of 06:48, 28 April 2026

Traits

UBIK® Traits provide the ability to define a dynamic list of properties for individual instances (UBIK® objects). Unlike traditional UBIK® Properties, which are rigidly bound to a MetaClass, instances of the same entity can contain a different list of traits.

This feature is particularly useful for data that only becomes known at runtime or varies significantly from instance to instance. Please note that traits do not use lazy loading, making them act rather "heavy weight" from a user's perspective.

IC Attention.pngThis feature must be used wisely, too many traits could impact the performance. Traits do not replace properties.

ViewModel Architecture & Data Access

To work with traits in the UI (XAML), the ContentViewModel provides several dedicated accessors and collections.

1. ValueAccessors (Read/Write)

The ValueAccessors acts as a combined dynamic value resolver. It provides a built-in fallback logic:

  1. Trait Lookup: First attempts to resolve the value via a trait with the specified name.
  2. Property Fallback: If no trait is found, it queries a regular UBIK® Property with that name (see PropertyByName).
  3. Default: If neither exists, it returns null.
IC Attention.png'Caution:' Be careful when using ValueAccessors. If you mistype a property name in XAML, you might not notice the error immediately and spend unnecessary time debugging. If you know you strictly need properties, use standard property bindings.

XAML Example (Reading a value):

<Entry Text="{Binding ValueAccessors[NAME]}" />

(Replace NAME with the placeholder of your actual trait or property name)

2. TraitByName (Traits Only)

TraitByName is a dedicated collection (ObservableTraitDictionary) that exclusively loads and initializes traits. Unlike the ValueAccessors, this does not fall back to regular properties.

  • Usage: When you explicitly want to query only traits (e.g., read-only display in the UI).

XAML Example (Reading only Trait):

<Entry Text="{Binding TraitByName[TRAIT_NAME]}" />

(Replace TRAIT_NAME with the placeholder of your actual trait)

3. Values (Raw Data)

This is a combined getter that returns the raw value directly from the dictionary, instead of providing a complex TraitViewModel or PropertyViewModel.

  • Usage: For pure display purposes or evaluations.

XAML Example (Reading raw data):

<Entry Text="{Binding Values[NAME]}" />

(Replace NAME with the placeholder of your actual trait or property name)

Commands (Set & Create Values)

SetValueCommand

This command on the ContentViewModel orchestrates value assignments and handles the creation of new traits if necessary.

  • If the trait exists: The value will be overwritten.
  • If a property exists: The property's value will be overwritten (if it is not locked/read-only).
  • If neither exists: A trait is added to the UBIK® content.

XAML Example (Setting a value): To create traits entirely from scratch (or explicitly overwrite an existing value), pass the Name and Value parameters to the SetValueCommand.

<Button Command="{Binding SetValueCommand}" Text="Set">
    <Button.CommandParameter>
        <classes:KeyValueList>
            <classes:KeyValueParameter Key="Name" Value="MY_TRAIT_NAME" />
            <classes:KeyValueParameter Key="Value" Value="My Trait Value" />
        </classes:KeyValueList>
    </Button.CommandParameter>
</Button>

(Note: Customizers can replace the static string placeholders with dynamic bindings to controls like Entry or DatePicker as needed)

Retrieved from "https://wiki.augmensys.com/index.php?title=Traits&oldid=29749"