{{Hint|There's no way to commit changes without saving them locally first. Therefore, the "AutoSave" parameter will be ignored when "AutoCommit" is set to true.}}
Here's an example of the command usage. It tries to set the property called "VALUE" to a double value 50 regardless of its current state and then automatically save and commit the change.
<br />
<source lang = "xml">
<AppBarButton xmlns:example="using:UBIK.WinX.Controls" ...<Button Command="{Binding SetPropertyValueCommand}" Icon Style="Edit{StaticResource UBIKButtonStyle}" Label Content="Set to 50%Property"> <AppBarButtonButton.CommandParameter> <examplecontrols:KeyValueList> <examplecontrols:KeyValueParameter Key="PropertyName" Value="VALUEMP_PROPERTY" /> <examplecontrols:KeyValueParameter Key="PropertyValue"> <example:KeyValueParameter.Value> <x:Double>50</x:Double> </example:KeyValueParameter.="My Value> <" /example:KeyValueParameter> <examplecontrols:KeyValueParameter Key="OnlyForUnvalidated" Value="false" /> <examplecontrols:KeyValueParameter Key="AutoSave" Value="true" /> <examplecontrols:KeyValueParameter Key="AutoCommit" Value="true" /> </examplecontrols:KeyValueList> </AppBarButtonButton.CommandParameter> </AppBarButtonButton>
</source>
{{Hint|It is advised to provide typed values like <nowiki><x:Double>50</x:Double></nowiki>. But for For simple types, you can try writing them in the text format like <nowiki><examplecontrols:KeyValueParameter Key="PropertyValue" Value="50" /></nowiki> and {{UBIK}} will try to find the right type. For advanced property types, it is advised to provide typed values like <nowiki><x:Boolean>true</x:Boolean></nowiki>.}}
<br>
==== Set a Binding as PropertyValue ====
There is a known issue in XAML where Behaviors and KeyValueLists do not inherit the binding context of the control they are attached to. Simply put, trying to use a binding directly in the PropertyValue part of the command; '''<nowiki><controls:KeyValueParameter Key="PropertyValue" Value="{Binding BindingPath}" /></nowiki>''', would lead to the client setting the value of MP_PROPERTY to null.
Luckily, there is a simple way to link this Binding to a context. Using the above example as a foundation, adapt the button as shown below:
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
The above code uses the x:Name of the button to specify the viewmodel from which we wish to begin our binding path.<br>
You do not need to follow this exact syntax, all that is necessary is to provide a connection to the BindingContext of an observable control.
==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.
<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>
<tab name="Xamarin">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</tab>
</tabs>
<br>
=== SaveAndCommitCommand ===
<br>
<br>
==== Localizing UI Texts ====
The most efficient practice is to use pre-localized texts from the standard client, however, this is not always possible, especially in custom UIs. The ObjectByUID indexer was therefore initially developed as a technique to allow localization of custom UI label texts.
The concept is to create an infrastructure object that carries metaproperties for localized texts, then bind to this infrastructure object using ObjectByUID, and bind to a specific metaproperty to receive it's localized Description text as follows:
<source lang = "xml">
"{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].Description}"
</source>
From here there are two approaches; the database-leaning one is to add one metaproperty per UI label, and simply bind to the Description of it. However, this shifts maintenance effort to the UBIK Studio after the initial adding of the label in XAML. Another approach would be to use the metaproperty to provide a "tag" that the xaml customizer can then use to differentiate between hardcoded labels.
A third approach would be to create one infrastructure object per label, however, this can lead to many objects being loaded upon startup.
{| class="wikitable"
|-
! Approach !! Implementation !! Maintenance Effort !! Recommendation
|-
| One metaproperty per UI Label || Bind the label text to the metaproperty Description || Database / UBIK Studio || Recommended for UWP, customizings with fewer UI texts, finalized customizings.
|-
| One metaproperty delivering a localization "tag" (such as: "EN" / "DE") || Use something like DataTrigger (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>
== Showing Images and Icons ==
=== Icons ===
UBIK comes equipped with a collection of icons that can be easily used in your customizing. [[Icon_Font|Here is an indepth explanation on cirrect usage in UBIK]].
In the case that you require an icon that is not included in our icon font file, there is the possibility to use SVG path data to render your required icon in the UI.
</tab>
</tabs>
<br>
<br>
== Default Tab Selection ==
The tab selection in UBIKContentView defaults to the first tab, which is Children objects. However, for cases where it makes more sense to display Properties or Documents by default, it is possible to change the tab selection using the following classifications:
* [[SYSCLS_SHOWDOCUMENTS]]
* [[SYSCLS_SHOWPROPERTIES]]
<br>{{Attention| Adding the classification to a metaclass is enough for UWP. However, Xamarin currently requires additional customizing to make use of the TabSelector property.}}
==== Implementation in Xamarin ====
One approach is to add a DataTrigger to the SfTabView found in UBIKContentArea that is triggered by the value of the TabSelector property, as shown below;
<source lang = "xml">
<tabView:SfTabView VisibleHeaderCount="3" >
<!-- tabView:SfTabItems ... -->
<tabView:SfTabView.Triggers>
<DataTrigger TargetType="tabView:SfTabView" Binding="{Binding TabSelector}" Value="PropertiesTab">
<Setter Property="SelectedIndex" Value="1"/>
</DataTrigger>
<DataTrigger TargetType="tabView:SfTabView" Binding="{Binding TabSelector}" Value="DocumentsTab">
<Setter Property="SelectedIndex" Value="2"/>
</DataTrigger>
</tabView:SfTabView.Triggers>
</tabView:SfTabView>
</source>
<br>
<br>
== FlipView ==
</tab>
</tabs>
== Device and Platform Responsiveness ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.
'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).
When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />''.
Instead, we should either use the '''multi-tag syntax''' or the '''inline syntax''' for OnPlatform / OnIdiom.
==== Multi-tag syntax ====
Here it is mandatory to add '''x:TypeArguments="TheType"''' with the proper type to OnPlatfrom/OnIdiom. ''Default="..."'' is optional.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<OnPlatform x:TypeArguments="Thickness" Default="20">
<On Platform="iOS, WinUI" Value="0,20,0,0" />
<On Platform="Android" Value="10,20,20,10" />
</OnPlatform>
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<OnIdiom x:TypeArguments="Thickness" Default="20">
<OnIdiom.Desktop>0,60,0,0</OnIdiom.Desktop>
</OnIdiom>
</source>
</tab>
</tabs>
If OnPlatform Values contain multiple subtags, the following syntax can be used:
<source lang = "XML">
<ControlTemplate x:Key="ExampleControlTemplate">
<Grid>
<OnPlatform x:TypeArguments="View">
<On Platform="Android">
<Button
...
Text="Button A" />
...
</On>
<On Platform="iOS">
<Button
...
Text="Button B" />
...
</On>
<On Platform="WinUI">
<Grid>
<Button
...
Text="Button C" />
<Label Text="Example" />
...
</Grid>
</On>
</OnPlatform>
</Grid>
</ControlTemplate>
</source>
{{Attention|When using ''GridLength'' as a type in OnPlatform/OnIdiom, it should only be used in combination with the inline syntax.}}
==== Inline syntax ====
When using the inline syntax, the type should not be specified. ''Default='' is optional.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<BoxView Color="{OnPlatform Default=Yellow, iOS=Red, Android=Green}" />
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<BoxView Color="{OnIdiom Default=Yellow, Phone=Red, Tablet=Green}" />
</source>
</tab>
</tabs>
If the value contains any special characters like '''"''' or ''',''' or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between ' '. But be careful with using apostrophes - when using them around curly brackets {} it can lead to an error.
<tabs>
<tab name="Don't">
<source lang = "XML">
Margin="{OnIdiom 10,2, Phone=2,0}"
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Margin="{OnIdiom '10,2', Phone='2,0'}"
</source>
</tab>
</tabs>
=== Complex values ===
If the OnPlatform/OnIdiom value contains a '''Binding''', '''StaticResource''' or any other complex value in curly brackets, it is recommended to use the '''inline syntax'''. Although there is no official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't seem to work always for such cases. DynamicResource values seem not to be supported in OnIdiom / OnPlatform.
<tabs>
<tab name="Don't">
<source lang = "XML">
<OnIdiom x:TypeArguments="..." Default="{Binding ...}">
<OnIdiom.Phone>{Binding ...}</OnIdiom.Phone>
</OnIdiom>
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Header="{OnIdiom Default={Binding ...}, Phone={Binding ...}}"
</source>
</tab>
</tabs>
{{Attention|Unreliable Support: Behavior may vary when using bindings or complex resources. Although it seems to work with the inline syntax according to our experiences, it is recommended to test these edge cases thoroughly.}}
{{UnderConstructionEnd}}
[[Category:Client|XAML Tips]]