UBIK Wiki / Augmensys - User contributions [en]

Sync Mode

2026-09-24T10:11:45Z

CWI: /* Behavior on connection loss */

Sync mode is a user configurable setting which affects the way {{UBIK}} client communicates with {{UBIK}} server. More specifically, it determines when and how the client fetches/commits {{UBIK}} content, or whether to have data communication at all.

== Possible sync modes ==
There are three/four different modes in {{UBIK}}. Here are their names and defined behaviors:
* Auto / Online: content is fetched/committed automatically;
* Manual Commit: content is fetched automatically; commit only happens when triggered by users;
* Offline: content is only fetched/committed when triggered by users;
<gallery widths="64" heights="64">
File:UI_Android_AutomaticMode.jpg|Auto / Online
File:UI_Android_ManualCommitMode.jpg|Manual Commit
File:UI_Android_OfflineMode.jpg|Offline
</gallery>

== Mode switch & indicator ==
[[File:UI_Android_ModeSwitchAndIndicator.png|thumb|alt=Mode Switch and Indicator|Mode Switch and Indicator]]
In the [[UBIK Client Basics#Navigation Drawer|navigation drawer]] of any standard {{UBIK}} client applications, there are three buttons for switching between the different modes. Clicking one of them allows users to switch {{UBIK}} to the corresponding sync mode.

In case users choose to download some content before switching to offline mode, the offline button will display the prepare mode icon until the download is finished.

{{Clear}}

{{UnderConstructionStart}}
== Behavior on connection loss ==
If network connectivity is lost while the Client is running in Auto/Online mode, the client switches to Offline as soon as the next data operation (fetch/commit) is attempted. It then checks for connectivity every 5 seconds. Once the connection has been stable for 15 seconds, it automatically switches back to Auto/Online mode (usually 15-20 seconds after connectivity returns).

{{Hint|This automatic recovery only happens if the Client was already in Auto/Online (or Manual) mode when the connection dropped. If the Client is started or logged in while no network connection is available, it starts directly in Offline mode and stays there, even once connectivity returns. It then needs to be switched to Auto/Online or Manual mode manually.}}
{{UnderConstructionEnd}}

[[Category:Client|Sync Mode]]

== See also ==
* [[HowTo:Switch to Offline Mode]]

[[Category:Client|Sync Mode]]

Sync Mode

2026-09-24T10:09:21Z

CWI:

Sync mode is a user configurable setting which affects the way {{UBIK}} client communicates with {{UBIK}} server. More specifically, it determines when and how the client fetches/commits {{UBIK}} content, or whether to have data communication at all.

== Possible sync modes ==
There are three/four different modes in {{UBIK}}. Here are their names and defined behaviors:
* Auto / Online: content is fetched/committed automatically;
* Manual Commit: content is fetched automatically; commit only happens when triggered by users;
* Offline: content is only fetched/committed when triggered by users;
<gallery widths="64" heights="64">
File:UI_Android_AutomaticMode.jpg|Auto / Online
File:UI_Android_ManualCommitMode.jpg|Manual Commit
File:UI_Android_OfflineMode.jpg|Offline
</gallery>

== Mode switch & indicator ==
[[File:UI_Android_ModeSwitchAndIndicator.png|thumb|alt=Mode Switch and Indicator|Mode Switch and Indicator]]
In the [[UBIK Client Basics#Navigation Drawer|navigation drawer]] of any standard {{UBIK}} client applications, there are three buttons for switching between the different modes. Clicking one of them allows users to switch {{UBIK}} to the corresponding sync mode.

In case users choose to download some content before switching to offline mode, the offline button will display the prepare mode icon until the download is finished.

{{Clear}}

{{UnderConstructionStart}}
== Behavior on connection loss ==
If network connectivity is lost while the Client is running in Auto/Online mode, the client switches to Offline as soon as the next data operation (fetch/commit) is attempted. It then checks for connectivity every 5 seconds. Once the connection has been stable for 15 seconds, it automatically switches back to '''Auto/Online''' mode (usually 15-20 seconds after connectivity returns).

{{Hint|This automatic recovery only happens if the Client was already in Auto/Online (or Manual) mode when the connection dropped. If the Client is started or logged in while no network connection is available, it starts directly in Offline mode and stays there, even once connectivity returns. It then needs to be switched to Auto/Online or Manual mode manually.}}
{{UnderConstructionEnd}}

== See also ==
* [[HowTo:Switch to Offline Mode]]

[[Category:Client|Sync Mode]]

Version 5.3 (Mobile)

2026-09-24T07:36:08Z

CWI: /* 5.3.? on 202?-??-?? */

Version 5.2 (Mobile)

2026-09-15T12:24:05Z

CWI: /* Release */

{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.x. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.}}

{{Attention|UBIK 5 clients can only connect to {{UBIK}} Servers of [[Version 3.6(Server)|version 3.6]] and higher!}}

{{Attention|The minimum supported OS versions are:
* Android 9;
* iOS 12.}}

== Availability ==
{{key press|Android: Store}}{{key press|iOS: Store}}: Publicly available in Google Play Store / Apple App Store.

{{key press|Android: Store Beta}}: Publicly available in Google Play Store as beta versions. You can opt in or out of the beta at any time in the store.

{{key press|Android: Store Preview}}: Available through Google Play Store's [https://play.google.com/store/apps/details?id=com.augmensys.ubik.go invitation link].

{{key press|iOS: Store Beta}}: Available through Apple App Store's [https://testflight.apple.com/join/Kmb1HG9E invitation link].

{{key press|iOS: Store Preview}}: Available through Apple App Store's [https://testflight.apple.com/join/yHRnbYbt invitation link].

{{key press|Windows: Store Preview}}: The mobile Windows client is not an official product and is only distributed as test versions upon request and/or in our [https://release.augmensys.com/download/modules/client/mobile/ release portal].
<br/>

{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with a ⚠️}}

= Release Notes =

== Release ==

=== 5.2.? on 2026-??-?? ===
* The [[MROCLS_TEXT_TASK|TextTaskClassification]] and [[MROCLS_SIGNATURE_TASK|SignatureTaskClassification]] have now a proper UID.
* Added [[MROCLS_INTEGER_TASK|IntegerTaskClassification]] and [[MROCLS_INTERFACE_TASK|InterfaceTaskClassification]].

=== 5.2.5 on 2026-09-01 {{key press|Android: Store}} 5.2.10 on 2026-09-09 {{key press|iOS: Store}} ===
* {{UBIK}} now supports credentials containing accented (and other special) characters, enabling users to authenticate successfully with a wider range of credential formats. (This must be paired with the [[Version_5.2.0_(Server)|5.2 service version]].)
* Fixed an issue where clients displayed extremely large or small values using scientific notation.
* Fixed an issue where POIs for scanned 2D codes are not stable and jump a lot.

=== 5.2.3 on 2026-08-04 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where documents did not reload properly.
* Fixed an issue where it was not possible to toggle the text input scanner from within the string edit dialog, and added [[Editors#String_value_editor|a button]] to do so to the default UI.

=== 5.2.2 on 2026-07-21 {{key press|Android: Store Beta}}{{key press|iOS: Store Beta}} ===
* Added support for [[Login_View#Offline_SSO_Login|Offline SSO Login]], allowing users to securely access the UBIK Client in offline mode after a successful online SSO authentication.
* UBIK LABs (Experimental) The update interval for live value updates (LiveValueUpdateIntervalMs) can be configured in profiles.
* Updated all client localization translations.
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.
* Fixed an issue where DocumentViewModel.ShowDocumentCommand did not work when combined with InvokeCommandAction.

[[Category:Client|Version 5.2 (Mobile)]]
[[Category:Mobile|Version 5.2 (Mobile)]]
[[Category:Version 5.2|Version 5.2 (Mobile)]]

== Known issues ==
* On some Android devices (Pixel 7A, iSafe 930.1 as we know), the app doesn't recognize the device cameras on the first launch after fresh installations. If this happens, please simply restart the app and it should be fine from then on.
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true. In Mobile, deleting the last annotation does not correctly update the editor's internal edit state. As a result, the Save button may remain visible even though no edits exist.
* When changing the device orientation during attaching a photo on iOS, the app gets stuck. This is an issue Microsoft confirmed in .NET9 and will fix in .NET10.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Currently, the Samsung keyboard doesn't show {{key press|,}} at all, regardless of the current language/locale setting of the device. Please use a different virtual keyboard (e.g. Gboard from Google) instead if {{key press|.}} is unacceptable.
* The periodic execution of background pushes is not guaranteed on iOS (the native push feature doesn't have this issue).
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* It is currently not possible to select which camera to use for AR views (e.g. scan page) on Windows.
* SfPullToRefresh was removed due to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_Mobile_client|existing issues]], and replaced with a Refresh option in the Context menu.

= ⚠️ XAML Notes =

* [[Editors#String_value_editor|UBIKEditString]] now uses ScanningIsActive rather than CallingViewModel.ScanToInput to show/hide the text input scanner/QR reader. Backwards compatibility is retained for existing customizings, inlcuding that of a [[EditPropertyValueCommand#Scan_to_Input|scan to input]] button to trigger property editing. However, the ScanningIsActive binding is more dynamic and can be toggled in realtime, whereas the CallingViewModel.ScanToInput is only applied once when the page is first rendered.

<headertabs />

[[Category:Client|Version 5.2 (Mobile)]]
[[Category:Mobile|Version 5.2 (Mobile)]]
[[Category:Version 5.2|Version 5.2 (Mobile)]]

Version 5.2 (WinX)

2026-09-15T12:23:02Z

CWI: /* Release */

Version 5.3 (Mobile)

2026-09-15T12:17:09Z

CWI: /* 5.3.? on 202?-??-?? */

Version 5.3 (WinX)

2026-09-15T12:17:01Z

CWI: /* 5.3.? on 202?-??-?? */

XAML Tips

2026-09-14T12:36:15Z

CWI: /* TabView */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

=== Default Tab Selection ===
The tab selection in UBIKContentArea 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]]
For new objects, the Properties tab is selected by default.

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====
The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
{{Attention|The order of TabItems matters, as the selection is evaluated via the index of the related TabItem.}}
</tab>
</tabs>

{{Hint|If it is required to preselect a tab e.g. based on a MetaClass or Property without the TabSelector functionality, it is also possible to use a DataChangedBehavior with SetPropertyAction, see [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|here]].}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

Version 5.3 (Mobile)

2026-09-14T12:12:39Z

CWI: /* 5.3.? on 202?-??-?? */

Version 5.3 (WinX)

2026-09-14T12:12:24Z

CWI: /* 5.3.? on 202?-??-?? */

Version 5.3 (Mobile)

2026-09-14T09:54:46Z

CWI: /* 5.3.? on 202?-??-?? */

XAML Tips

2026-09-14T08:36:30Z

CWI: /* Default Tab Selection */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== Default Tab Selection ===
The tab selection in UBIKContentArea 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]]
For new objects, the Properties tab is selected by default.

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====
The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
{{Attention|The order of TabItems matters, as the selection is evaluated via the index of the related TabItem.}}
</tab>
</tabs>

{{Hint|If it is required to preselect a tab e.g. based on a MetaClass or Property without the TabSelector functionality, it is also possible to use a DataChangedBehavior with SetPropertyAction, see [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|here]].}}

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-07T09:57:28Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== 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]]
For new objects, the Properties tab is selected by default.

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====
The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
{{Attention|The order of TabItems matters, as the selection is evaluated via the index of the related TabItem.}}
</tab>
</tabs>

{{Hint|If it is required to preselect a tab e.g. based on a MetaClass or Property without the TabSelector functionality, it is also possible to use a DataChangedBehavior with SetPropertyAction, see [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|here]].}}

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-07T08:56:29Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== 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]]
For new objects, the Properties tab is selected by default.

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====
The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
{{Attention|The order of TabItems matters, as the selection is evaluated via the index of the related TabItem.}}
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-07T08:51:14Z

CWI: /* Default Tab Selection */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== 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]]
For new objects, the Properties tab is selected by default.

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====
The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-07T07:59:22Z

CWI: /* Default Tab Selection */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== 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]]

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
Since {{Version/MobileSince|5.3}}, adding the classification to a metaclass is enough for Mobile. Prior this version, it is additionally necessary to bind the TabSelector to the SelectedIndex as follows:
<source lang = "xml">
<controls:UBIKTabView
...
SelectedIndex="{Binding TabSelector}">
...
</controls:UBIKTabView>
</source>

</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{Attention|The default tab preselection with the TabSelector and the Classifications only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, there need to be some Xaml adaptations in order to work, see [[XAML_Tips#Preselection_of_customized_Tabs|Preselection of customized Tabs]].}}

==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents - in this order). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-07T07:34:37Z

CWI: /* TabView */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionStart}}
=== 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]]

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-03T14:41:38Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

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

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{UnderConstructionStart}}
==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...), which only matches the enum index in the default tab set. Once tabs are added, removed, or reordered, the Expression needs to translate each TabSelector value into the tab's actual position in the current layout, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-03T14:37:53Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

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

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{UnderConstructionStart}}
==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (index 0 -> ChildrenTab, index 1 -> PropertiesTab, index 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list, which equals the enum index, starting from 0 (0, 1, 2, ...). So the Expression needs to translate each TabSelector value into the position of the matching tab, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">

<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-03T14:30:56Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

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

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{UnderConstructionStart}}
==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (0 -> ChildrenTab, 1 -> PropertiesTab, 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...). So the Expression needs to translate each TabSelector value into the position of the matching tab, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">

<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "MyObjectTitle" ? "CUSTOM" : (TabSelector.ToString() == "ChildrenTab" ? "CHILDREN" : "PROPERTIES")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CHILDREN}" />
<RadioButton
x:Name="CustomTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=CUSTOM}" />
<RadioButton
x:Name="PropertiesTabRadioButton"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PROPERTIES}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">
<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "MyObjectTitle" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-03T13:57:51Z

CWI: /* Preselection of customized Tabs */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

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

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{UnderConstructionStart}}
==== Preselection of customized Tabs ====

The TabSelector approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on. The example below shows how a customized tab can be preselected in such cases, without losing the functionality of the TabSelector.

{{Hint|TabSelector is an enum (0 -> ChildrenTab, 1 -> PropertiesTab, 2 -> DocumentsTab). In the Mobile Client, tabs are selected by their position in the list (0, 1, 2, ...). So the Expression needs to translate each TabSelector value into the position of the matching tab, as shown in the example below. UWP matches tabs by name instead, so no such mapping is needed there.}}

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">
<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "03 Property Editing" ? "TestTab" : (TabSelector.ToString() == "ChildrenTab" ? "ChildrenTab" : "PropertiesTab")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=ChildrenTab}" />
<RadioButton
x:Name="TestTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=TestTab}" />
<RadioButton
x:Name="PropertiesTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PropertiesTab}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">
<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "03 Property Editing" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

XAML Tips

2026-09-03T13:19:52Z

CWI: /* TabView */

== Attachable behaviors ==
It's quite often that you need to attach behaviors to certain XAML elements. For example, on a Grid, you want to attach a behavior which executes a command upon a Tapped event, or you want to execute a command when a certain property on a UBIK object changes.

Notice that in the following examples, "Interactivity" and "Core" are both namespaces and you have to make sure that they are defined at the root of your XAMLs:

<source lang = "xml">
<DataTemplate
...
xmlns:Core="using:Microsoft.Xaml.Interactions.Core"
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity">
...
</DataTemplate>
</source>
<br>

=== Event Triggered ===
With an EventTriggerBehavior, you can react on changes/events of UI Elements:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding NavigateToChildrenCommand}" />
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>

=== Data Triggered ===
If you want to react on changes of the underlying data (ViewModel), you can use DataTriggerBehavior instead. The following example, when used in the ''UBIKSplashArea'' template, automatically navigates to the root objects once the login process is finished and the user was successfully authenticated:

<source lang = "xml">
<Grid>
<Interactivity:Interaction.Behaviors>
<Core:DataTriggerBehavior Binding="{Binding IsLoggedIn}" Value="True">
<Core:InvokeCommandAction Command="{Binding NavigateToRootPageCommand}" />
</Core:DataTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Content creation ==
=== Child item creation ===
{{Version/WinXSince|3.5.5}}
To directly create an object on a child of the current object, you can define a Button as follows. The method "Item.IsTypeCreationAllowed" used in the expression gets the uid of the type that should be created below a child, if a child does not allow the creation of that type underneath it, the child will be hidden in the selection dialog. To actually create the object, the "CreateChildItemCommand" needs to be passed a KeyValueList with two parameters: The Parent-key is the UID or the ContentViewModel of the child underneath the object should be created, the Type-key is the type of object which should be created--this should match the uid passed to the "Item.IsTypeCreationAllowed" method.

<source lang = "xml">
xmlns:uc="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="6D733909-1742-4110-8619-237849BFE453"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<source lang = "xml">
<x:String x:Key="PlantMap">Item.IsTypeCreationAllowed("21fc990a-d064-4bee-8d48-3293351f827a")</x:String>
<cv:ListCollectionView x:Key="PlantMapView" Expression="{StaticResource PlantMap}" ItemsSource="{Binding Children.Items}" />

<AppBarButton>
<AppBarButton.Flyout>
<Flyout Placement="Full">
<ListView ItemsSource="{Binding Source={StaticResource PlantMapView}}">
<ListView.ItemTemplate>
<DataTemplate>
<Button Content="{Binding Header}" Command="{Binding CreateChildItemCommand}" x:Name="CreateButton" Tag="{Binding}">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Parent" Value="{Binding Tag, ElementName=CreateButton}"/>
<uc:KeyValueParameter Key="Type" Value="21fc990a-d064-4bee-8d48-3293351f827a"/>
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>
</Flyout>
</AppBarButton.Flyout>
</AppBarButton>
</source>

<br/>
Additionally, the following optional parameters can be added as well.
* CreateOnly (optional, defaults to false): When set to true, the client will not automatically navigate to the created content, rather automatically save and commit it. If set to true, this overrides the following parameters;
* AutoNavigate (optional, defaults to true): When set to false, the client will not automatically navigate to the created content;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and the database, and then committed to the server.
<br>

=== Creating multiple documents ===
To upload multiple documents at once, the CreateChildItemsCommand can be used. The list of supported command parameters are similar to those of the CreateChildItemCommand (single item). Except that anything other than AutoNavigate=false and AutoCommit=true do not make sense in multi-creation scenario. Therefore, those parameters are fixed and any received from XAML will be ignored.


<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding CreateChildItemsCommand}"
Content="Create multiple documents">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Type" Value="6170a068-2314-4444-ad62-0da99769a048" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

<br>
<br>

=== Disable FilloutCriteria ===
{{Version/WinXSince|3.5}}
To enable/disable the automatic filtering of a query based on the ParentObject, there is the possibility to specify EnableFillOutCriteria--if it is not set, it defaults to false. Additionaly "SkipDialog" can be set to true, to not display a dialog.

<source lang="xml">
<Grid x:Name="selectionGrid" Tag="{Binding MetaUID}">
<Interactivity:Interaction.Behaviors>
<Core:EventTriggerBehavior EventName="Tapped">
<Core:InvokeCommandAction Command="{Binding ElementName=ChildAreaGrid, Path=DataContext.AddTemplatableDataCommand}" >
<Core:InvokeCommandAction.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="{Binding Tag,ElementName=selectionGrid}"/>
<uc:KeyValueParameter Key="EnableFillOutCriteria" Value="false"/>
<uc:KeyValueParameter Key="SkipDialog" Value="false"/>
</uc:KeyValueList>
</Core:InvokeCommandAction.CommandParameter>
</Core:InvokeCommandAction>
</Core:EventTriggerBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</source>
<br>
<br>

== Hotspotting ==
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
The hotspotting command is used for hotspotting as well as for annotating, to configure the button for hotspotting, the commandparameter "Mode" should be set to "HotSpotting", for annotating the "Mode" should be "Annotate". The parameter commit is optional, if set to true, the changes get automatically persisted when leaving the editing mode.

<source lang = "xml">
<AppBarToggleButton
IsChecked="{Binding EditingAnnotation, Mode=TwoWay}"
IsEnabled="{Binding IsAnnotatable}"
Command="{Binding HotSpottingCommand}">
<AppBarToggleButton.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Mode" Value="Annotate"/>
<uc:KeyValueParameter Key="Commit" Value="true"/>
</uc:KeyValueList>
</AppBarToggleButton.CommandParameter>
</AppBarToggleButton>
</source>
<br>
<br>

== Remember scroll positions of list views ==

=== Version 3.7 & later {{Version/WinXSince|3.7}} ===
Starting from this version,
* The precision of scroll position remembering is improved(by pixel offsets instead of by items);
* It also works for other scrollable lists (instead of just for content object lists).
<br />
To enable this feature, you should make sure the following.
* The SelectionBoundListView is used instead of the standard ListView. Its {{UBIK}} namespace is <code>UBIK.WinX.Controls</code>;
* The SelectionBoundListView's <code>RememberScrollPosition</code> property is not set to "false"; (It's "true" by default.)
* The SelectionBoundListView's <code>x:Name</code> property value is unique.
<br>

=== Version 3.6 {{Version/WinXSince|3.6}} ===
The UBIK-Client does include a function to remember the position in a list (ListView) when navigating away from it. This function is only available when the list (ListView) has a unique name as a property (x:Name). When browsing back to the previously visited list UBIK scrolls back to the last position. The function does not save scroll positions over different sessions.
Implementing the function to remember the scroll position in a ListView one has to consider that the list elements (Children) could depend on a other UI-element. If the list elements do depend on a other UI-elemente, this element has to be created above the ListView in the XAML.

<source lang = "xml">
<DataTemplate xmlns:behaviors="using:UBIK.WinX.Behaviors" xmlns:uc="using:UBIK.WinX.Controls">
...
<uc:SelectionBoundListView x:Name="ChildListView">
<Interactivity:Interaction.Behaviors>
<behaviors:FirstVisibleItemPersistenceBehavior FirstVisibleItems="{Binding ScrollItems}" />
</Interactivity:Interaction.Behaviors>
</uc:SelectionBoundListView>
</DataTemplate>
</source>
<br>
<br>

== MultiBinding {{Version/WinXSince|3.6}} ==
Very often we want to display some UI elements (e.g. a Grid) depending on whether multiple criteria are met. It's much easier to achieve this by using a MultiBindingBehavior like the following.
<source lang = "xml">
<DataTemplate
xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:behaviors="using:UBIK.WinX.Behaviors">
...
<Grid>
<Interactivity:Interaction.Behaviors>
<behaviors:MultiBindingBehavior Converter="{StaticResource VisLogicAndConverter}" PropertyName="Visibility">
<behaviors:MultiBindingItem Value="{Binding MassEditViewModel, Converter={StaticResource NullToVisConverter}}" />
<behaviors:MultiBindingItem Value="{Binding Documents.Items.Count, Converter={StaticResource ItemCountToVisConverter}}" />
</behaviors:MultiBindingBehavior>
</Interactivity:Interaction.Behaviors>
</Grid>
</DataTemplate>
</source>
The behavior makes sure the container Grid is set to Visibile only if the mass editing mode is not turned on (MassEditViewModel is null) and the context object has child document(s) (Documents.Items.Count is greater than 0. You can combine any number of binding results (MultiBindingItem) using the VisLogicAndConverter (the name should be self explanatory).
<br>
<br>

== Other Commands ==
=== InvokeOnItemsCommand {{Version/WinXSince|3.6}} ===
Available on all ListViewModels, this command allows executing a specified command on a collection of list items. It can be used in combination with features such as [[Mass_Edit_(UBIK_WinX)|mass editing]] and [[XAML_Changes_in_UBIK_WinX_3.5#After_3.5|expression based collection filtering]]. Examples for both combinations are provided below.

{{Attention|The command specified through the "Command" parameter is executed on list items and, therefore, must be available in the list item contexts (view models). If in doubt, the [[Developer_Mode|developer mode]] can be used to inspect if a command is available in a certain context.}}

{{Hint|Parameter "Command" and "SelectedItemsOnly" are specific to the InvokeOnItemsCommand. What other parameters to define or whether to define them at all depends on the type of command to be executed on the items.}}
<br>

==== Invoke on selected items ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}
This example demonstrates how you can use the mass editing feature to select certain objects from the child list and then execute the SetPropertyValueCommand for those selected.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* You should insert the following code snippet into the default UBIKChildArea template;
* If the parameter "SelectedItemsOnly" is missed or set to "False", the command will be executed on all child items;
* To enable selection, click on the "Mass Edit" button below the property list.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Children.InvokeOnItemsCommand}"
Content="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Children.InvokeOnItemsCommand}"
Text="Set to 50%">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="SelectedItemsOnly" Value="False" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue">
<example:KeyValueParameter.Value>
<x:Double>50</x:Double>
</example:KeyValueParameter.Value>
</example:KeyValueParameter>
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>
<br>

==== Invoke on filtered results ====
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

* First, you need to setup a filtered list
**UWP: Setup a ListCollectionView in the Resources section of a UI element (e.g. Grid). This list is only available/visible within that UI element (the Grid in this case).
**Mobile: Setup a String with a filtering expression & a SfDataSourceExt in the ResourceDictionary of the ContentView. For the Expression property of the SfDataSourceExt refer to the created expression String.

* The ItemsSource uses Children.Items. Use the [[Developer_Mode|developer mode]] if necessary to find out if this is available where you intend to define the list;
* The example expression filters for any items that don't contain the text "EXAMPLE" in their Title texts. You can filter differently by altering the expression.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid xmlns:CV="using:UBIK.WinX.UI.CollectionView">
<Grid.Resources>
<CV:ListCollectionView
x:Key="Filtered"
Expression="!Item.Title.Contains("EXAMPLE")"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
...
</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">!Item.Title.Contains("EXAMLPLE")</x:String>
<controls:SfDataSourceExt x:Key="Filtered" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
</ContentView>
</source>
</tab>
</tabs>

<br />
With the filtered list configured, you can then insert the following code snippet to execute the SetPropertyValueCommand for the filtered result items.
* The example code assumes that the child objects have an editable property called "VALUE" and tries to set 50 as their value;
* The "Filtered" refers to the ListCollectionView (UWP) or SfDataSourceExt (Mobile) configured above.
<br />

<tabs>
<tab name="UWP">
<source lang = "xml">
<AppBarButton
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Icon="AllApps"
Label="Set to 50"
Style="{ThemeResource UBIKActionAppBarButton}">
<AppBarButton.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</AppBarButton.CommandParameter>
</AppBarButton>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding Source={StaticResource Filtered}, Path=ListViewModel.InvokeOnItemsCommand}"
Text="Set to 50">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="Command" Value="SetPropertyValueCommand" />
<example:KeyValueParameter Key="PropertyName" Value="VALUE" />
<example:KeyValueParameter Key="PropertyValue" Value="50" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

{{Attention|The binding <code>ListViewModel.InvokeOnItemsCommand</code> should be updated to <code>BulkOperation.InvokeOnItemsCommand</code> starting from version 4.3.}}
<br>

==== Support for old styled commands ====
Some old commands might not support KeyValueLists as parameters. In that case, just define the parameter value under the "CommandParameter" key, e.g.
<br />
<source lang = "xml"><example:KeyValueParameter Key="CommandParameter" Value="some string value for example" /></source>.
This single value is then passed as the command parameter instead of the entire KeyValueList.
<br>
<br>

=== SetPropertyValueCommand {{Version/WinXSince|3.6}} ===
{{Attention|To use a binding in the KeyValueParameter, it has to be applied like in the example provided here: [[KeyValueList]]}}

This command existed before but was implemented differently. In the newer version(s), it is improved to provide customizers more control over the things that happen during/after the property value changes.
The available command parameters are:
* PropertyName: the name of the property to set a new value to;
* PropertyValue: the value to be set to the above mentioned property;
* OnlyForUnvalidated (optional, defaults to false): When set to true, the value will only be set if the property is not yet validated;
* AutoSave (optional, defaults to false): When set to true, the change(s) will be saved to the local cache and database;
* AutoCommit (optional, defaults to false): When set to true, the change(s) will be committed to the server.

{{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">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
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="My Value" />
<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|For simple types, you can try writing them in the text format like <nowiki><controls: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:
<tabs>
<tab name="UWP">
<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>
</tab>

<tab name="Mobile">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
... >
<Button.CommandParameter>
<classes:KeyValueList>
...
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.BindingPath, Source={x:Reference SetDynamicPropertyButton}}" />
...
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

{{Hint|Replace ''BindingPath'' in the above snippets with your required binding path, for example, ''AppStatus.CurrentUser.RawDetails[...]''. }}
</tabs>

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

==== 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="Mobile">
<source lang="xml">
<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>
</source>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
With the ''SaveAndCommitCommand'' it is possible to save and commit unsaved changes on a ContentViewModel.

* ForceCommit CommandParameter (optional, defaults to false): Normally when the App is in Online mode, changes are automatically committed when saved. This is not the case when the App is in Manual mode. Setting the ''ForceCommit'' parameter to true makes it possible to commit the changes when saved in Manual mode.
* {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} PropertyNameToSave CommandParameter (optional, defaults to null): Delivers the Property Name as String of a specific Property that should be saved. E.g. when called via PropertyViewModel.ResetCommand or PropertyViewModel.DeleteCommand, the ''PropertyNameToSave'' parameter is used to only apply the SaveAndCommitCommand on the related PropertyViewModel called from, and not on other unsaved changes on this ContentViewModel.
<br/>
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
xmlns:example="using:UBIK.WinX.Controls"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button
xmlns:example="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding SaveAndCommitCommand}">
<Button.CommandParameter>
<example:KeyValueList>
<example:KeyValueParameter Key="ForceCommit" Value="True" />
</example:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display cutom views]].
<br>

=== TeachInCommand ===
With the '''TeachInCommand''' you're allowed to set your device's current location ("teach-in", "TeachIn") as the value of the context object's [[SYSCLS_GEO|geo property]].
This command is available in both '''ContentViewModel''' and '''PropertyViewModel'''.
* ContentViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the context object's [[SYSCLS_GEO|geo property]]. Saves and commits the change;
* PropertyViewModel.TeachInCommand: If possible, sets the current location of the device as the value of the current property if it's a geo property (not necessarily the [[SYSCLS_GEO|geo property]]). Addtionally supports a boolean command parameter:
** False (default): The change is not automatically saved.
** True: The change is saved.
<br/> {{hint| Make sure you use the correct binding path for your command depending on your current context view model. E.g., if the context view model is already the ContentViewModel then your binding path should simply be TeachInCommand. You can use the [[Developer_Mode|developer mode]] to find out the current view model in a view.}}
<br>

===UpdateArbitraryObjectCommand {{Version/WinXSince|4.7}}===
The "UpdateArbitraryObjectCommand" is responsible for updating an arbitrary object based on a set of provided parameters. The command is accessible in the AppStatusViewModel (as '''ViewModel.AppStatus''').
<br />
The available command parameters are:
* Uid (Mandatory): UID of the object to be updated;
* UpdateChildDepth (Optional): Child depth/level to update (defaults to 1);
* UpdateParentDepth (Optional): Parent depth/level to update (defaults to 0);
* UpdateIgnoreExpiry (Optional): Ignore update expiry (defaults to false);

{{Hint|Note that if you set the UpdateChildDepth property to "-1" you are also able to update a whole branch with this command.}}

Here is an example of the command usage:
<br />
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button ...
xmlns:uc="using:UBIK.WinX.Controls"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Button ...
xmlns:uc="using:clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL"
Command="{Binding UpdateArbitraryObjectCommand}"
Content="Update Arbitrary Object">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="Uid" Value="...valid UID..." />
<uc:KeyValueParameter Key="UpdateChildDepth" Value="2" />
<uc:KeyValueParameter Key="UpdateParentDepth" Value="0" />
<uc:KeyValueParameter Key="UpdateIgnoreExpiry" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>
<br>

=== Access to an arbitrary object {{Version/WinXSince|4.6}} {{Version/XamarinSince|4.6}} ===
With the ObjectByUID feature it is possible to access any local arbitrary object by its UID and, for example, display a value of it.
It can be accessed from ContentViewModel, AuthenticationViewModel, and RootPageViewModel levels.

To display a string of e.g. a property of an arbitrary object from ContentViewModel, AuthenticationViewModel & RootPageViewModel, the following syntax can be used in related XAMLs:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>

For Property Dialogs the CallingViewModel prefix is needed to access an arbitrary object:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBlock Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Label Text="{Binding CallingViewModel.ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].DisplayValue}" />
</source>
</tab>
</tabs>
<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 (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
In UBIK, there are two types of image;
* The thumbnail image assigned to a UBIK object, delivered using the <nowiki>{Binding Icon...}</nowiki> binding, in combination with a ByteToImageConverter. Examples can commonly be found on UBIKChildItem templates.
* Custom image shown with a specific purpose, such as a company logo or icon on a button/UI element.
<br>

==== Paths as string resources ====
When using custom images in your UI, it is a good idea not to hardcode path data into your Image control but instead to create a string resource in UBIKThemes that holds the image path, and use this string resource in your Image control. The benefit of the indirect connection between image file and usage is that the "file is in use" issue (sometimes experienced when either manual, or auto-deployment of xamls, tries to change image files when UBIK is running) is avoided this way.

Sample:
<tabs>
<tab name="UWP">
'''UBIKThemes:'''
<source lang = "xml"><x:String x:Key="MainLogo">ms-appdata:///local/xaml/Images/MainLogo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
<Image
x:Name="LogoImage"
Height="32"
Stretch="Uniform"
Source="{Binding Source={StaticResource MainLogo}, Converter={StaticResource PathToImageConverter}}" />
</source>
</tab>

<tab name="Mobile(Xamarin)">
'''UBIKThemes:'''
<source lang = "xml">
<x:String x:Key="Logo_Image">IMG_Logo.png</x:String>
</source>
<br>
'''Usage:'''
<source lang = "xml">
xmlns:customimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...
<customimage:FileImage
HeightRequest="140"
Aspect="AspectFit"
FileName="{StaticResource BorealisLogo_Image}"
FolderName="xaml" />
</source>
</tab>
</tabs>
<br>

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

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

==== Custom Icons ====
Here referring to icons which are not included as standard icons un UBIK.

'''Path data''' is a collection of points, which combined together form a vector image. Vector images, compared to raster images like a PNG or JPG, are scalable, because they are always rendered from path data, and not from a bitmap, which has to be stretched or squished to fit your defined size. Described below two approaches.

===== Using (SVG) Files =====
<br>
The '''UWP approach''' involves adding an SVG icon file to your xaml project and render it using an Image control.
<source lang = "xml">
<Image Width="14" Height="14" Margin="0,0,0,1">
<Image.Source >
<SvgImageSource UriSource="{StaticResource PP_Issued}" />
</Image.Source>
</Image>
</source>
<br><br>

===== Using Path Data =====
<br>
The '''Mobile(Xamarin) approach''' shows how to use svg data directly using a Path control.

The first step is to generate path data for your icon. The easiest way is to download the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse all installed icon files for your icon of choice. Once selected, use Tools > Xaml / Xamarin Forms to show various useful aspects of the icon.

{{Attention|The first time you launch CharacterMap you will need to use the button in the bottom right of the selected icon pane to reveal the Xamarin.Forms code generator.}}

With an icon selected, the Path Geometry section can be used to generate a path data that can be pasted directly in your xaml as follows:

<source lang = "xml">
<Path Fill="{StaticResource UBIKAccentColor}" Data="F1 M 8.75 1.25 L 18.75 1.25 L 18.75 18.75 L 1.25 18.75 L 1.25 8.75 L 5 8.75 L 5 6.25 L 1.25 6.25 L 1.25 1.25 L 6.25 1.25 L 6.25 5 L 8.75 5 Z M 10 2.5 L 10 5 L 12.5 5 L 12.5 2.5 Z M 2.5 5 L 5 5 L 5 2.5 L 2.5 2.5 Z M 6.25 6.25 L 6.25 8.75 L 8.75 8.75 L 8.75 6.25 Z M 2.5 10 L 2.5 12.5 L 5 12.5 L 5 10 Z M 17.5 17.5 L 17.5 2.5 L 13.75 2.5 L 13.75 6.25 L 10 6.25 L 10 10 L 6.25 10 L 6.25 13.75 L 2.5 13.75 L 2.5 17.5 Z " />
</source>

Once you have your Path control, you can customize it as [https://learn.microsoft.com/en-us/previous-versions/xamarin/xamarin-forms/user-interface/shapes/path| documented by Microsoft] (Maui documentation: [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/shapes/path?view=net-maui-9.0| see here]). Path data generated using the above method will most likely need a Fill attribute, for example <nowiki>Fill="{StaticResource UBIKAccentColor}"</nowiki>.

{{Hint|More complicated icons will have longer and more complicated paths.}}

<br>
<br>

== TabView ==

=== UI virtualization ===
When using the TabView control in your XAML code, UI virtualization can greatly improve initial loading performance, based on the scenario.Here's how to enable it:

<tabs>
<tab name="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

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

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(Maui)">
tbd!
</tab>
<tab name="Mobile(Xamarin)">
Xamarin currently requires additional customizing to make use of the TabSelector property. 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: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>
</tab>
</tabs>
<br>
<br>

{{UnderConstructionStart}}
==== Preselection of customized Tabs ====

The approach shown above only works with the default tab set (Children, Properties, Documents). If a tab is added, removed, or reordered, this default mechanism can no longer be relied on.

<tabs>
<tab name="UWP">
Add an EvalExpression into the content area, processing the x:Name of the tab that should be checked. Bind the expression to every RadioButton's IsChecked.
<source lang="xml">
<controls:EvalExpression
x:Name="CustomTabSelector"
Visibility="Collapsed"
Expression="Title == "03 Property Editing" ? "TestTab" : (TabSelector.ToString() == "ChildrenTab" ? "ChildrenTab" : "PropertiesTab")">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<RadioButton
x:Name="ChildrenTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=ChildrenTab}" />
<RadioButton
x:Name="TestTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=TestTab}" />
<RadioButton
x:Name="PropertiesTab"
GroupName="Tabs"
IsChecked="{Binding Path=Result, ElementName=CustomTabSelector, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=PropertiesTab}" />
</source>
</tab>

<tab name="Mobile(MAUI)">
Add an EvalExpression evaluating the tab index, and bind it to the TabView SelectedIndex:
<source lang="xml">
<controls:EvalExpression
x:Key="CustomTabSelector"
Context="{Binding}"
Expression="Title == "03 Property Editing" ? 1 : (TabSelector.ToString() == "ChildrenTab" ? 0 : 2)">
<controls:EvalExpressionParameter Name="Title" Value="{Binding Title}" />
<controls:EvalExpressionParameter Name="TabSelector" Value="{Binding TabSelector}" />
</controls:EvalExpression>

<tabView:SfTabView SelectedIndex="{Binding Source={StaticResource CustomTabSelector}, Path=Result}">

</tabView:SfTabView>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

== FlipView ==

=== UI virtualization ===
When using the FlipView control in your XAML code, it's better to enable [https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview#ui-virtualization UI virtualization]. The difference in performance gets more obvious as the number of items in the FlipView increases. Here's how to enable it.

<source lang = "xml">
<FlipView
...
VirtualizingStackPanel.VirtualizationMode="Standard">
<Flipview.ItemsPanel>
<ItemsPanelTemplate>
<VirtualizingStackPanel Orientation="Horizontal" />
</ItemsPanelTemplate>
</Flipview.ItemsPanel>
</FlipView>
</source>

VirtualizingStackPanel.VirtualizationMode offers two possibilities: Standard & Recycling. In case you are interested, here are their [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.virtualizationmode?view=netframework-4.7.2 differences].

=== Delayed loading {{Version/WinXSince|4.7}} ===
By default the FlipView control (UWP only) doesn't have a delayed loading mechanism.
Imagine if you flip through a large list of documents quickly, the control would actually end up loading every single one of them even if you just want to look at the content of the last one. This has a very negative effect that the app wastes a lot of resources loading documents for nothing, while struggling to display the content you care about. In some extreme case, this can even lead to an app hang/crash.

We added such a delayed loading mechanism to this control. With it, the item content only starts to load when you stay on it for a while (1 second). If you are using the content of UBIKDocumentFlipView.xaml from an older version (before 4.7) and therefore experience such a performance/stability issue, please check the FlipView related section in the newer default templates of it.

=== Auto saving {{Version/WinXSince|4.6}} ===
Unsaved changes on the document (e.g. Annotations) are gonna be saved and committed automatically when flipping the page in the FlipView.

{{Attention|Changes are lost when leaving the page without flipping the document first.}}

{{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} If you want to keep the changes when leaving the page by e.g. navigating away without flipping the document first, there is a boolean property called ''AutoSaveDocumentsOnPageClose'' (default value: false) which enables this behavior. It can be activated by adding the property to (or editing it in) the custom UBIKThemes as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom {{Version/MobileSince|5.0}} ==

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for Mobile 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="..." />'' like it was usual in Xamarin.

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 and can be added like in the following example if a default value needs to be defined.
<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 <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. 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 it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all 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.}}

= Known issues =

== FontIcon does not update when set dynamically using Behaviors ==
{{Version/WinXSince|4.0}} DataTriggerBehavior does not reliably change the Glyph property of a FontIcon. To recreate in UWP the behavior of dynamically displaying icons based on a binding state, which in Mobile xaml can easily be achieved using a DataTrigger, use TextBlock with the FontFamily set to UBIKSymbols instead. Then, the DataTriggerBehavior can be used normally. An example can be seen in the UBIKPropertyDirectItemMinMax.xaml

<tabs>
<tab name="Won't Work">
<source lang = "XML">
<FontIcon Glyph="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Glyph" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
<TextBlock FontFamily="{StaticResource UBIKSymbols}" Text="{Binding Numpad, Source={StaticResource UBIKIcons}}">
<interactivity:Interaction.Behaviors>
<core:DataTriggerBehavior Binding="{Binding MinMaxType, Converter={StaticResource EqualToTrueConverter}, ConverterParameter=Min}" Value="true">
<core:ChangePropertyAction PropertyName="Text" Value="{Binding DownLined, Source={StaticResource UBIKIcons}}" />
</source>
</tab>
</tabs>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|XAML Tips]]

Mobile XAML

2026-08-31T11:06:19Z

CWI: /* Known issues */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

<source lang = "xml">
Mobile(Xamarin):


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>

==== DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} ====

A DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a Maui-specific behavior change.

{{Hint|Maui ranks a value applied by an active DataTrigger's Setter higher than a manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

One common use case that cannot be used directly in Maui is [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|Pre-selecting a tab based on a metaclass or property]].

As a workaround, do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing '''DataChangedBehavior''' and '''SetPropertyAction''' pattern instead. For an example click [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|here]].

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, for example:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, ListView.SelectedItem, RadioButton.IsChecked
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|Use a DataChangedBehavior with SetPropertyAction instead of a DataTrigger if the property it sets should remain user-changeable afterwards. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

HowTo:Convert Xamarin XAMLs to Maui

2026-08-31T11:05:12Z

CWI: /* UBIKTabView */

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
There are some other properties that have changed their names on '''SfListView/SfListViewExt'''. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">ItemHolding</syntaxhighlight>
| <syntaxhighlight lang="xml">ItemLongPress</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">LeftSwipeTemplate, RightSwipeTemplate</syntaxhighlight>
| <syntaxhighlight lang="xml">StartSwipeTemplate, EndSwipeTemplate</syntaxhighlight>
|-
| <syntaxhighlight lang="xml"><sync:SfListView.LayoutManager></syntaxhighlight>
| <syntaxhighlight lang="xml"><sync:SfListView.ItemsLayout></syntaxhighlight>
|-
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

=== SfTabView ===
{{Attention|In UBIK Maui, [[HowTo:Convert_Xamarin_XAMLs_to_Maui#UBIKTabView|UBIKTabView]]{{Version/MobileSince|5.1}} should be used instead of the SfTabView going forward, as it supports lazy loading (a performance-boosting feature that only loads tab content on demand). This section is therefore informational only. }}

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

==== Remove Obsolete Converters ====
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

==== Add StringFormatConverter ====
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

==== FontImageSource Styling ====
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

==== TabView Structure ====
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

==== Property Changes ====
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== SfPullToRefresh ===

{{Attention|Due to issues in the SfPullToRefresh control it was removed from all standard UBIK UIs and should not be used in customizings. For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button, simply to strip the PTR wrapper is enough.}}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

==== Rename SfPullToRefresh properties ====
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

==== Avoid multiple SfPullToRefresh controls ====
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Highly Recommended ==
=== Performance improvements for UBIKContentView or ContentControl ===
UBIKContentView has been updated with performance improving measures, namely the possibility for [[Mobile_XAML#Delay_and_LazyLoading|LazyLoading or Delaying content rendering]].
{{Attention|These performance improvements only work when used with the TemplateConverter syntax documented in the next section!}}

* A default delay of 50 milliseconds was added to all content rendered via UBIKContentView or ContentControl which was conversely found to increase client reactivity. This can be adjusted using the Delay attribute on any such control.
* It is recommended to add LazyLoading="True" UBIKContentView or ContentControl that are not immediately displayed in the UI (a similar concept to our [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Recommended_Usage|LoadNextLevel]] recommendation).
** When used in the content of a UBIKTabView tab, the LazyLoading is handled automatically when the tab is activated (see: UBIKContentArea).
** LazyLoading can be manually triggered on any contentview outside of UBIKTabView by triggering the TriggerLazyLoad() method.

=== TemplateConverter for UBIKContentView or ContentControl ===
The recommended syntax for embedding templates within other templates has changed due to performance improvements from Delay or LazyLoading the rendering of content. Note that this refers only to directly mentioned templates, rather than when using TemplateSelectors. A good example can be seen in the tab contents of UBIKContentArea for Properties and Documents.

<syntaxhighlight lang="xml">
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}" ✅
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</syntaxhighlight>

Note how the above example uses the new TemplateConverter together with the name of the desired template, in this case UBIKPropertyArea.

The former syntax would have been: <syntaxhighlight lang="xml">❌ Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}"</syntaxhighlight>.
This 'hardcoded' syntax bypasses the template selection mechanism which includes the various performance improvements mentioned above.

=== New name for Root item templates ===
The template formerly called UBIKMainItem has been renamed to UBIKRootItem for consistency.
The renaming is not mandatory in customizing, however, ensure that the ItemTemplate requested in UBIKRootArea matches the file intended to be used for visualizing root items.

=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

For more customizing options refer to the [https://help.syncfusion.com/maui-toolkit/tabview/tab-item-customization Syncfusion Documentation].

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

==== Pre-selecting a tab based on a metaclass or property ====

In Maui, an active DataTrigger permanently blocks the user from manually switching tabs. For this reason, instead of using a DataTrigger to set the SelectedIndex, a DataChangedBehavior with SetPropertyAction should be used, which sets SelectedIndex once when the relevant data changes and leaves the tab freely user-changeable afterwards.

See [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for the full explanation.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

The DataChangedBehavior and SetPropertyAction Binding, ConverterParameter, and Value need to match the target tab index and condition for the specific customizing. The SetPropertyAction TargetObject must reference the UBIKTabView via x:Reference (e.g. x:Name="ContentTabs" on the UBIKTabView).

{{Attention|This replacement applies to any property a DataTrigger sets that should stay user-changeable afterwards, not just SelectedIndex on a TabView, see [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for other affected controls and scenarios.}}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}

== Information Only ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

Version 5.3 (Mobile)

2026-08-27T07:44:56Z

CWI: /* 5.3.? on 202?-??-?? */

Version 5.3 (WinX)

2026-08-27T07:44:15Z

CWI: /* 5.3.? on 202?-??-?? */

Mobile XAML

2026-08-26T12:56:33Z

CWI: /* DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

<source lang = "xml">
Mobile(Xamarin):


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>

{{UnderConstructionStart}}
==== DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} ====

A DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a Maui-specific behavior change.

{{Hint|Maui ranks a value applied by an active DataTrigger's Setter higher than a manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

One common use case that cannot be used directly in Maui is [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|Pre-selecting a tab based on a metaclass or property]].

As a workaround, do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing '''DataChangedBehavior''' and '''SetPropertyAction''' pattern instead. For an example click [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Pre-selecting_a_tab_based_on_a_metaclass_or_property|here]].

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, for example:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, ListView.SelectedItem, RadioButton.IsChecked
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|Use a DataChangedBehavior with SetPropertyAction instead of a DataTrigger if the property it sets should remain user-changeable afterwards. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

{{UnderConstructionEnd}}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

HowTo:Convert Xamarin XAMLs to Maui

2026-08-26T12:34:52Z

CWI: /* Pre-selecting a tab based on a metaclass or property */

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
There are some other properties that have changed their names on '''SfListView/SfListViewExt'''. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">ItemHolding</syntaxhighlight>
| <syntaxhighlight lang="xml">ItemLongPress</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">LeftSwipeTemplate, RightSwipeTemplate</syntaxhighlight>
| <syntaxhighlight lang="xml">StartSwipeTemplate, EndSwipeTemplate</syntaxhighlight>
|-
| <syntaxhighlight lang="xml"><sync:SfListView.LayoutManager></syntaxhighlight>
| <syntaxhighlight lang="xml"><sync:SfListView.ItemsLayout></syntaxhighlight>
|-
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

=== SfTabView ===
{{Attention|In UBIK Maui, [[HowTo:Convert_Xamarin_XAMLs_to_Maui#UBIKTabView|UBIKTabView]]{{Version/MobileSince|5.1}} should be used instead of the SfTabView going forward, as it supports lazy loading (a performance-boosting feature that only loads tab content on demand). This section is therefore informational only. }}

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

==== Remove Obsolete Converters ====
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

==== Add StringFormatConverter ====
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

==== FontImageSource Styling ====
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

==== TabView Structure ====
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

==== Property Changes ====
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== SfPullToRefresh ===

{{Attention|Due to issues in the SfPullToRefresh control it was removed from all standard UBIK UIs and should not be used in customizings. For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button, simply to strip the PTR wrapper is enough.}}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

==== Rename SfPullToRefresh properties ====
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

==== Avoid multiple SfPullToRefresh controls ====
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Highly Recommended ==
=== Performance improvements for UBIKContentView or ContentControl ===
UBIKContentView has been updated with performance improving measures, namely the possibility for [[Mobile_XAML#Delay_and_LazyLoading|LazyLoading or Delaying content rendering]].
{{Attention|These performance improvements only work when used with the TemplateConverter syntax documented in the next section!}}

* A default delay of 50 milliseconds was added to all content rendered via UBIKContentView or ContentControl which was conversely found to increase client reactivity. This can be adjusted using the Delay attribute on any such control.
* It is recommended to add LazyLoading="True" UBIKContentView or ContentControl that are not immediately displayed in the UI (a similar concept to our [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Recommended_Usage|LoadNextLevel]] recommendation).
** When used in the content of a UBIKTabView tab, the LazyLoading is handled automatically when the tab is activated (see: UBIKContentArea).
** LazyLoading can be manually triggered on any contentview outside of UBIKTabView by triggering the TriggerLazyLoad() method.

=== TemplateConverter for UBIKContentView or ContentControl ===
The recommended syntax for embedding templates within other templates has changed due to performance improvements from Delay or LazyLoading the rendering of content. Note that this refers only to directly mentioned templates, rather than when using TemplateSelectors. A good example can be seen in the tab contents of UBIKContentArea for Properties and Documents.

<syntaxhighlight lang="xml">
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}" ✅
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</syntaxhighlight>

Note how the above example uses the new TemplateConverter together with the name of the desired template, in this case UBIKPropertyArea.

The former syntax would have been: <syntaxhighlight lang="xml">❌ Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}"</syntaxhighlight>.
This 'hardcoded' syntax bypasses the template selection mechanism which includes the various performance improvements mentioned above.

=== New name for Root item templates ===
The template formerly called UBIKMainItem has been renamed to UBIKRootItem for consistency.
The renaming is not mandatory in customizing, however, ensure that the ItemTemplate requested in UBIKRootArea matches the file intended to be used for visualizing root items.

=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

For more customizing options refer to the [https://help.syncfusion.com/maui-toolkit/tabview/tab-item-customization Syncfusion Documentation].

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

{{UnderConstructionStart}}

==== Pre-selecting a tab based on a metaclass or property ====

In Maui, an active DataTrigger permanently blocks the user from manually switching tabs. For this reason, instead of using a DataTrigger to set the SelectedIndex, a DataChangedBehavior with SetPropertyAction should be used, which sets SelectedIndex once when the relevant data changes and leaves the tab freely user-changeable afterwards.

See [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for the full explanation.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

The DataChangedBehavior and SetPropertyAction Binding, ConverterParameter, and Value need to match the target tab index and condition for the specific customizing. The SetPropertyAction TargetObject must reference the UBIKTabView via x:Reference (e.g. x:Name="ContentTabs" on the UBIKTabView).

{{Attention|This replacement applies to any property a DataTrigger sets that should stay user-changeable afterwards, not just SelectedIndex on a TabView, see [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for other affected controls and scenarios.}}

{{UnderConstructionEnd}}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}

== Information Only ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

HowTo:Convert Xamarin XAMLs to Maui

2026-08-26T12:16:00Z

CWI: /* DataTrigger permanently blocks manual changes (use DataChangedBehavior instead) */

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
There are some other properties that have changed their names on '''SfListView/SfListViewExt'''. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">ItemHolding</syntaxhighlight>
| <syntaxhighlight lang="xml">ItemLongPress</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">LeftSwipeTemplate, RightSwipeTemplate</syntaxhighlight>
| <syntaxhighlight lang="xml">StartSwipeTemplate, EndSwipeTemplate</syntaxhighlight>
|-
| <syntaxhighlight lang="xml"><sync:SfListView.LayoutManager></syntaxhighlight>
| <syntaxhighlight lang="xml"><sync:SfListView.ItemsLayout></syntaxhighlight>
|-
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

=== SfTabView ===
{{Attention|In UBIK Maui, [[HowTo:Convert_Xamarin_XAMLs_to_Maui#UBIKTabView|UBIKTabView]]{{Version/MobileSince|5.1}} should be used instead of the SfTabView going forward, as it supports lazy loading (a performance-boosting feature that only loads tab content on demand). This section is therefore informational only. }}

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

==== Remove Obsolete Converters ====
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

==== Add StringFormatConverter ====
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

==== FontImageSource Styling ====
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

==== TabView Structure ====
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

==== Property Changes ====
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== SfPullToRefresh ===

{{Attention|Due to issues in the SfPullToRefresh control it was removed from all standard UBIK UIs and should not be used in customizings. For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button, simply to strip the PTR wrapper is enough.}}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

==== Rename SfPullToRefresh properties ====
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

==== Avoid multiple SfPullToRefresh controls ====
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Highly Recommended ==
=== Performance improvements for UBIKContentView or ContentControl ===
UBIKContentView has been updated with performance improving measures, namely the possibility for [[Mobile_XAML#Delay_and_LazyLoading|LazyLoading or Delaying content rendering]].
{{Attention|These performance improvements only work when used with the TemplateConverter syntax documented in the next section!}}

* A default delay of 50 milliseconds was added to all content rendered via UBIKContentView or ContentControl which was conversely found to increase client reactivity. This can be adjusted using the Delay attribute on any such control.
* It is recommended to add LazyLoading="True" UBIKContentView or ContentControl that are not immediately displayed in the UI (a similar concept to our [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Recommended_Usage|LoadNextLevel]] recommendation).
** When used in the content of a UBIKTabView tab, the LazyLoading is handled automatically when the tab is activated (see: UBIKContentArea).
** LazyLoading can be manually triggered on any contentview outside of UBIKTabView by triggering the TriggerLazyLoad() method.

=== TemplateConverter for UBIKContentView or ContentControl ===
The recommended syntax for embedding templates within other templates has changed due to performance improvements from Delay or LazyLoading the rendering of content. Note that this refers only to directly mentioned templates, rather than when using TemplateSelectors. A good example can be seen in the tab contents of UBIKContentArea for Properties and Documents.

<syntaxhighlight lang="xml">
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}" ✅
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</syntaxhighlight>

Note how the above example uses the new TemplateConverter together with the name of the desired template, in this case UBIKPropertyArea.

The former syntax would have been: <syntaxhighlight lang="xml">❌ Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}"</syntaxhighlight>.
This 'hardcoded' syntax bypasses the template selection mechanism which includes the various performance improvements mentioned above.

=== New name for Root item templates ===
The template formerly called UBIKMainItem has been renamed to UBIKRootItem for consistency.
The renaming is not mandatory in customizing, however, ensure that the ItemTemplate requested in UBIKRootArea matches the file intended to be used for visualizing root items.

=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

For more customizing options refer to the [https://help.syncfusion.com/maui-toolkit/tabview/tab-item-customization Syncfusion Documentation].

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

{{UnderConstructionStart}}

==== Pre-selecting a tab based on a metaclass or property ====

In Maui, an active DataTrigger permanently blocks the user from manually switching tabs. For this reason, instead of using a DataTrigger to set the SelectedIndex, a DataChangedBehavior with SetPropertyAction should be used instead, which sets SelectedIndex once when the relevant data changes and leaves the tab freely user-changeable afterwards.

See [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for the full explanation.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

The DataChangedBehavior and SetPropertyAction Binding, ConverterParameter, and Value need to match the target tab index and condition for the specific customizing. The SetPropertyAction TargetObject must reference the UBIKTabView via x:Reference (e.g. x:Name="ContentTabs" on the UBIKTabView).

{{Attention|This replacement applies to any property a DataTrigger sets that should stay user-changeable afterwards, not just SelectedIndex on a TabView, see [[Mobile_XAML#DataTrigger_permanently_blocks_manual_changes|XAML Known Issues: DataTrigger permanently blocks manual changes]] for other affected controls and scenarios.}}

{{UnderConstructionEnd}}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}

== Information Only ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

Mobile XAML

2026-08-26T10:33:18Z

CWI: /* DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

<source lang = "xml">
Mobile(Xamarin):


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>

{{UnderConstructionStart}}
==== DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} ====

A DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a Maui-specific behavior change.

{{Hint|Maui ranks a value applied by an active DataTrigger's Setter higher than a manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

In the example below a DataTrigger is used to set the selected tab based on the record's metaclass. The initial selection works correctly, but afterwards the user can never manually switch to a different tab. Tapping another tab header highlights it, but the content never switches, and SelectedIndex silently reverts.

As a workaround, do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing '''DataChangedBehavior''' and '''SetPropertyAction''' pattern instead.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, for example:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, ListView.SelectedItem, RadioButton.IsChecked
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|Use a DataChangedBehavior with SetPropertyAction instead of a DataTrigger if the property it sets should remain user-changeable afterwards. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

{{UnderConstructionEnd}}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

Mobile XAML

2026-08-26T10:19:15Z

CWI: /* DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

<source lang = "xml">
Mobile(Xamarin):


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>

{{UnderConstructionStart}}
=== DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} ===

A DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a Maui-specific behavior change.

{{Hint|Maui ranks a value applied by an active DataTrigger's Setter higher than a manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

In the example below a DataTrigger is used to set the selected tab based on the record's metaclass. The initial selection works correctly, but afterwards the user can never manually switch to a different tab. Tapping another tab header highlights it, but the content never switches, and SelectedIndex silently reverts.

As a workaround, do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing '''DataChangedBehavior''' and '''SetPropertyAction''' pattern instead.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, for example:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, ListView.SelectedItem, RadioButton.IsChecked
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|Use a DataChangedBehavior with SetPropertyAction instead of a DataTrigger if the property it sets should remain user-changeable afterwards. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

{{UnderConstructionEnd}}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

Mobile XAML

2026-08-26T10:12:03Z

CWI: /* DataTrigger Issues */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

<source lang = "xml">
Mobile(Xamarin):


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>

{{UnderConstructionStart}}
=== DataTrigger permanently blocks manual changes {{Version/MobileSince|5.0.0}} ===

A DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a Maui-specific behavior change.

{{Hint|Maui ranks a value applied by an active DataTrigger's Setter higher than a manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

In the example below a DataTrigger is used to set the selected tab based on the record's metaclass. The initial selection works correctly, but afterwards the user can never manually switch to a different tab. Tapping another tab header highlights it, but the content never switches, and SelectedIndex silently reverts.

'''Workaround:''' Do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing '''DataChangedBehavior''' and '''SetPropertyAction''' pattern instead.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, e.g.:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, CollectionView/ListView.SelectedItem, RadioButton.IsChecked, Shell.CurrentItem
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|When converting a Xamarin DataTrigger, if the property it sets should remain user-changeable afterwards, convert it into a DataChangedBehavior with SetPropertyAction. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

{{UnderConstructionEnd}}

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

HowTo:Convert Xamarin XAMLs to Maui

2026-08-26T07:27:41Z

CWI: /* DataTrigger permanently blocks manual changes (use DataChangedBehavior instead) */

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
There are some other properties that have changed their names on '''SfListView/SfListViewExt'''. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">ItemHolding</syntaxhighlight>
| <syntaxhighlight lang="xml">ItemLongPress</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">LeftSwipeTemplate, RightSwipeTemplate</syntaxhighlight>
| <syntaxhighlight lang="xml">StartSwipeTemplate, EndSwipeTemplate</syntaxhighlight>
|-
| <syntaxhighlight lang="xml"><sync:SfListView.LayoutManager></syntaxhighlight>
| <syntaxhighlight lang="xml"><sync:SfListView.ItemsLayout></syntaxhighlight>
|-
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

=== SfTabView ===
{{Attention|In UBIK Maui, [[HowTo:Convert_Xamarin_XAMLs_to_Maui#UBIKTabView|UBIKTabView]]{{Version/MobileSince|5.1}} should be used instead of the SfTabView going forward, as it supports lazy loading (a performance-boosting feature that only loads tab content on demand). This section is therefore informational only. }}

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

==== Remove Obsolete Converters ====
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

==== Add StringFormatConverter ====
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

==== FontImageSource Styling ====
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

==== TabView Structure ====
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

==== Property Changes ====
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== SfPullToRefresh ===

{{Attention|Due to issues in the SfPullToRefresh control it was removed from all standard UBIK UIs and should not be used in customizings. For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button, simply to strip the PTR wrapper is enough.}}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

==== Rename SfPullToRefresh properties ====
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

==== Avoid multiple SfPullToRefresh controls ====
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Highly Recommended ==
=== Performance improvements for UBIKContentView or ContentControl ===
UBIKContentView has been updated with performance improving measures, namely the possibility for [[Mobile_XAML#Delay_and_LazyLoading|LazyLoading or Delaying content rendering]].
{{Attention|These performance improvements only work when used with the TemplateConverter syntax documented in the next section!}}

* A default delay of 50 milliseconds was added to all content rendered via UBIKContentView or ContentControl which was conversely found to increase client reactivity. This can be adjusted using the Delay attribute on any such control.
* It is recommended to add LazyLoading="True" UBIKContentView or ContentControl that are not immediately displayed in the UI (a similar concept to our [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Recommended_Usage|LoadNextLevel]] recommendation).
** When used in the content of a UBIKTabView tab, the LazyLoading is handled automatically when the tab is activated (see: UBIKContentArea).
** LazyLoading can be manually triggered on any contentview outside of UBIKTabView by triggering the TriggerLazyLoad() method.

=== TemplateConverter for UBIKContentView or ContentControl ===
The recommended syntax for embedding templates within other templates has changed due to performance improvements from Delay or LazyLoading the rendering of content. Note that this refers only to directly mentioned templates, rather than when using TemplateSelectors. A good example can be seen in the tab contents of UBIKContentArea for Properties and Documents.

<syntaxhighlight lang="xml">
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}" ✅
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</syntaxhighlight>

Note how the above example uses the new TemplateConverter together with the name of the desired template, in this case UBIKPropertyArea.

The former syntax would have been: <syntaxhighlight lang="xml">❌ Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}"</syntaxhighlight>.
This 'hardcoded' syntax bypasses the template selection mechanism which includes the various performance improvements mentioned above.

=== New name for Root item templates ===
The template formerly called UBIKMainItem has been renamed to UBIKRootItem for consistency.
The renaming is not mandatory in customizing, however, ensure that the ItemTemplate requested in UBIKRootArea matches the file intended to be used for visualizing root items.

=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

For more customizing options refer to the [https://help.syncfusion.com/maui-toolkit/tabview/tab-item-customization Syncfusion Documentation].

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

{{UnderConstructionStart}}

=== DataTrigger permanently blocks manual changes (use DataChangedBehavior instead) ===

In .NET MAUI, a DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a MAUI-specific behavior change.

{{Hint|MAUI ranks a value applied by an active DataTrigger's Setter higher than a plain manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true.}}

In the example below a DataTrigger is used to set the selected tab based on the record's metaclass. The initial selection works correctly, but afterwards the user can never manually switch to a different tab. Tapping another tab header highlights it, but the content never switches, and SelectedIndex silently reverts.

'''Workaround:''' Do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing DataChangedBehavior and SetPropertyAction pattern instead.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, e.g.:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, CollectionView/ListView.SelectedItem, RadioButton.IsChecked, Shell.CurrentItem
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

{{Hint|When converting a Xamarin DataTrigger, if the property it sets should remain user-changeable afterwards, convert it into a DataChangedBehavior with SetPropertyAction. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.}}

{{UnderConstructionEnd}}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}

== Information Only ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

HowTo:Convert Xamarin XAMLs to Maui

2026-08-25T12:13:25Z

CWI: /* Highly Recommended */

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
There are some other properties that have changed their names on '''SfListView/SfListViewExt'''. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">ItemHolding</syntaxhighlight>
| <syntaxhighlight lang="xml">ItemLongPress</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">LeftSwipeTemplate, RightSwipeTemplate</syntaxhighlight>
| <syntaxhighlight lang="xml">StartSwipeTemplate, EndSwipeTemplate</syntaxhighlight>
|-
| <syntaxhighlight lang="xml"><sync:SfListView.LayoutManager></syntaxhighlight>
| <syntaxhighlight lang="xml"><sync:SfListView.ItemsLayout></syntaxhighlight>
|-
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

=== SfTabView ===
{{Attention|In UBIK Maui, [[HowTo:Convert_Xamarin_XAMLs_to_Maui#UBIKTabView|UBIKTabView]]{{Version/MobileSince|5.1}} should be used instead of the SfTabView going forward, as it supports lazy loading (a performance-boosting feature that only loads tab content on demand). This section is therefore informational only. }}

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

==== Remove Obsolete Converters ====
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

==== Add StringFormatConverter ====
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

==== FontImageSource Styling ====
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

==== TabView Structure ====
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

==== Property Changes ====
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== SfPullToRefresh ===

{{Attention|Due to issues in the SfPullToRefresh control it was removed from all standard UBIK UIs and should not be used in customizings. For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button, simply to strip the PTR wrapper is enough.}}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

==== Namespace Update ====
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

==== Rename SfPullToRefresh properties ====
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

==== Avoid multiple SfPullToRefresh controls ====
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Highly Recommended ==
=== Performance improvements for UBIKContentView or ContentControl ===
UBIKContentView has been updated with performance improving measures, namely the possibility for [[Mobile_XAML#Delay_and_LazyLoading|LazyLoading or Delaying content rendering]].
{{Attention|These performance improvements only work when used with the TemplateConverter syntax documented in the next section!}}

* A default delay of 50 milliseconds was added to all content rendered via UBIKContentView or ContentControl which was conversely found to increase client reactivity. This can be adjusted using the Delay attribute on any such control.
* It is recommended to add LazyLoading="True" UBIKContentView or ContentControl that are not immediately displayed in the UI (a similar concept to our [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Recommended_Usage|LoadNextLevel]] recommendation).
** When used in the content of a UBIKTabView tab, the LazyLoading is handled automatically when the tab is activated (see: UBIKContentArea).
** LazyLoading can be manually triggered on any contentview outside of UBIKTabView by triggering the TriggerLazyLoad() method.

=== TemplateConverter for UBIKContentView or ContentControl ===
The recommended syntax for embedding templates within other templates has changed due to performance improvements from Delay or LazyLoading the rendering of content. Note that this refers only to directly mentioned templates, rather than when using TemplateSelectors. A good example can be seen in the tab contents of UBIKContentArea for Properties and Documents.

<syntaxhighlight lang="xml">
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}" ✅
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</syntaxhighlight>

Note how the above example uses the new TemplateConverter together with the name of the desired template, in this case UBIKPropertyArea.

The former syntax would have been: <syntaxhighlight lang="xml">❌ Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}"</syntaxhighlight>.
This 'hardcoded' syntax bypasses the template selection mechanism which includes the various performance improvements mentioned above.

=== New name for Root item templates ===
The template formerly called UBIKMainItem has been renamed to UBIKRootItem for consistency.
The renaming is not mandatory in customizing, however, ensure that the ItemTemplate requested in UBIKRootArea matches the file intended to be used for visualizing root items.

=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

For more customizing options refer to the [https://help.syncfusion.com/maui-toolkit/tabview/tab-item-customization Syncfusion Documentation].

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

{{UnderConstructionStart}}

=== DataTrigger permanently blocks manual changes (use DataChangedBehavior instead) ===

In .NET MAUI, a DataTrigger that sets a property the user can also change interactively will permanently block that manual change as long as the trigger's condition stays true. This did not happen in Xamarin - it is a MAUI-specific behavior change.

'''Symptom:''' A DataTrigger is used to set e.g. the selected tab based on the record's metaclass. The initial selection works correctly, but afterwards the user can never manually switch to a different tab - tapping another tab header highlights it, but the content never switches and SelectedIndex silently reverts.

'''Cause (short version):''' MAUI ranks a value applied by an active DataTrigger's Setter higher than a plain manual property write (e.g. a user's tap). Every manual write attempt is silently discarded while the trigger's condition remains true - no error, no exception, it just never takes effect.

'''Workaround:''' Do not use DataTrigger for a property that should be data-driven once and then freely user-editable afterwards. Use the existing DataChangedBehavior and SetPropertyAction pattern instead - it performs a single, plain, imperative write the moment the underlying data changes, and never competes with later manual changes.

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:50%;" | Xamarin
! style="width:50%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKTabView.Triggers>
<DataTrigger TargetType="controls:UBIKTabView"
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
Value="True">
<Setter Property="SelectedIndex" Value="1" />
</DataTrigger>
</controls:UBIKTabView.Triggers>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"
...
<controls:UBIKTabView.Behaviors>
<behaviors:DataChangedBehavior
Binding="{Binding Content.MetaUID, Converter={StaticResource EqualityToBool}, ConverterParameter='b82accb3-7437-429d-aed9-08dfdd5a9e59'}"
ComparisonCondition="Equal"
Value="True">
<behaviors:SetPropertyAction
PropertyName="SelectedIndex"
TargetObject="{Binding Source={x:Reference ContentTabs}}"
Value="1" />
</behaviors:DataChangedBehavior>
</controls:UBIKTabView.Behaviors>
</syntaxhighlight>
|-
|}
Result: the tab still auto-selects correctly based on the data, and the user can freely switch tabs afterward.

{{Attention|This is not limited to tab selection. The same problem can occur wherever a DataTrigger, Trigger, MultiTrigger sets a property that a user (or code-behind) is also meant to change afterwards, e.g.:}}
* Selection controls: Picker.SelectedIndex/SelectedItem, CollectionView/ListView.SelectedItem, RadioButton.IsChecked, Shell.CurrentItem
* Toggle/input controls: Switch.IsToggled, CheckBox.IsChecked, Entry/Editor.Text
* Expand/collapse state on any control the user can also expand/collapse manually
* Implicit/global Style.Triggers - the riskiest case, since it silently affects every control of that type on a page
* Code-behind writes executed after the trigger has already applied a value (not just touch input)

'''Rule of thumb:''' when converting a Xamarin DataTrigger, if the property it sets should remain user-changeable afterwards, convert it into a DataChangedBehavior with SetPropertyAction. Keep DataTrigger/Style.Triggers only for properties that should stay continuously data-driven and don't conflict with user input.

{{UnderConstructionEnd}}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}

== Information Only ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

List of Versions

2026-07-30T08:55:37Z

CWI:

[[File:IC_MainPage-20.png]] '''Future versions'''
<hr/>
<div class="table" style="width:100%;">
{{Item/Version|2026-??-??| {{Version/Server|5.2.0}}}}
{{Item/Version|202?-??-??| {{Version/WinX|5.3}}}}
{{Item/Version|202?-??-??| {{Version/Mobile|5.3}}}}
</div>
{{Check mark}} '''Released versions'''
<hr/>
<div class="table" style="width:100%;">
{{Item/Version|2026-07-21| {{Version/WinX|5.2}}}}
{{Item/Version|2026-07-21| {{Version/Mobile|5.2}}}}
{{Item/Version|2026-07-13| {{Version/Server|5.1.0}}}} Service Pack
{{Item/Version|2026-04-01| {{Version/Server|5.1.0}}}}
{{Item/Version|2026-02-10| {{Version/WinX|5.1}}}}
{{Item/Version|2026-02-10| {{Version/Mobile|5.1}}}}
{{Item/Version|2026-02-02| {{Version/Server|5.0.0}}}}
{{Item/Version|2025-09-29| {{Version/WinX|5.0}}}}
{{Item/Version|2025-09-27| {{Version/Mobile|5.0}}}}
{{Item/Version|2025-03-14| {{Version/Server|4.9.0}}}}
{{Item/Version|2025-02-05| {{Version/WinX|4.9}}}}
{{Item/Version|2025-02-05| {{Version/Xamarin|4.9}}}}
{{Item/Version|2024-09-14| {{Version/Server|4.8.1}}}}
{{Item/Version|2024-09-11| {{Version/WinX|4.8}}}}
{{Item/Version|2024-09-11| {{Version/Xamarin|4.8}}}}
{{Item/Version|2024-05-16| {{Version/Xamarin|4.7}}}}
{{Item/Version|2024-05-16| {{Version/WinX|4.7}}}}
{{Item/Version|2024-05-07| {{Version/Server|4.7.0}}}}


</div>



[[Category:Release notes|List of Versions]]
[[Category:Version|List of Versions]]

Version 5.3 (Mobile)

2026-07-30T08:53:44Z

CWI:

Category:Version 5.3

2026-07-30T08:53:23Z

CWI:

[[Category:Version]]

Version 5.3 (Mobile)

2026-07-30T08:50:16Z

CWI:

Version 5.3 (Mobile)

2026-07-30T08:49:46Z

CWI: Created page with "{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.x. Please refer to HowTo:Convert_Xamarin_XAMLs_to_Maui for migrating them to the new client..."

Version 5.3 (WinX)

2026-07-30T08:43:44Z

CWI:

Category:Version 5.3

2026-07-30T08:42:15Z

CWI: Created blank page

Version 5.3 (WinX)

2026-07-30T08:38:53Z

CWI: Created page with "{{Attention|This version requires [https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1809_(October_2018_Update) Windows 10 build 17763] or higher}} == Availabi..."

Version 5.2 (Mobile)

2026-07-23T08:06:36Z

CWI: /* Release */

{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.x. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.}}

{{Attention|UBIK 5 clients can only connect to {{UBIK}} Servers of [[Version 3.6(Server)|version 3.6]] and higher!}}

{{Attention|The minimum supported OS versions are:
* Android 9;
* iOS 12.}}

== Availability ==
{{key press|Android: Store}}{{key press|iOS: Store}}: Publicly available in Google Play Store / Apple App Store.

{{key press|Android: Store Beta}}: Publicly available in Google Play Store as beta versions. You can opt in or out of the beta at any time in the store.

{{key press|Android: Store Preview}}: Available through Google Play Store's [https://play.google.com/store/apps/details?id=com.augmensys.ubik.go invitation link].

{{key press|iOS: Store Beta}}: Available through Apple App Store's [https://testflight.apple.com/join/Kmb1HG9E invitation link].

{{key press|iOS: Store Preview}}: Available through Apple App Store's [https://testflight.apple.com/join/yHRnbYbt invitation link].

{{key press|Windows: Store Preview}}: The mobile Windows client is not an official product and is only distributed as test versions upon request and/or in our [https://release.augmensys.com/download/modules/client/mobile/ release portal].
<br/>

{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with a ⚠️}}

= Release Notes =

== Release ==

=== 5.2.? on 2026-07-?? ===
* Fixed an issue where documents did not reload properly.

=== 5.2.2 on 2026-07-21 {{key press|Android: Store Beta}}{{key press|iOS: Store Beta}} ===
* Added support for [[Login_View#Offline_SSO_Login|Offline SSO Login]], allowing users to securely access the UBIK Client in offline mode after a successful online SSO authentication.
* UBIK LABs (Experimental) The update interval for live value updates (LiveValueUpdateIntervalMs) can be configured in profiles.
* Updated all client localization translations.
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.
* Fixed an issue where DocumentViewModel.ShowDocumentCommand did not work when combined with InvokeCommandAction.

[[Category:Client|Version 5.2 (Mobile)]]
[[Category:Mobile|Version 5.2 (Mobile)]]
[[Category:Version 5.2|Version 5.2 (Mobile)]]

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true. In Mobile, deleting the last annotation does not correctly update the editor's internal edit state. As a result, the Save button may remain visible even though no edits exist.
* When changing the device orientation during attaching a photo on iOS, the app gets stuck. This is an issue Microsoft confirmed in .NET9 and will fix in .NET10.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Currently, the Samsung keyboard doesn't show {{key press|,}} at all, regardless of the current language/locale setting of the device. Please use a different virtual keyboard (e.g. Gboard from Google) instead if {{key press|.}} is unacceptable.
* The periodic execution of background pushes is not guaranteed on iOS (the native push feature doesn't have this issue).
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* It is currently not possible to select which camera to use for AR views (e.g. scan page) on Windows.
* SfPullToRefresh was removed due to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_Mobile_client|existing issues]], and replaced with a Refresh option in the Context menu.

= ⚠️ XAML Notes =

<headertabs />

[[Category:Client|Version 5.2 (Mobile)]]
[[Category:Mobile|Version 5.2 (Mobile)]]
[[Category:Version 5.2|Version 5.2 (Mobile)]]

Version 5.1 (Mobile)

2026-07-07T08:36:45Z

CWI: /* Release */

{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.1. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.}}

{{Attention|UBIK 5 clients can only connect to {{UBIK}} Servers of [[Version 3.6(Server)|version 3.6]] and higher!}}

{{Attention|The minimum supported OS versions are:
* Android 9;
* iOS 12.}}

== Availability ==
{{key press|Android: Store}}{{key press|iOS: Store}}: Publicly available in Google Play Store / Apple App Store.

{{key press|Android: Store Beta}}: Publicly available in Google Play Store as beta versions. You can opt in or out of the beta at any time in the store.

{{key press|Android: Store Preview}}: Available through Google Play Store's [https://play.google.com/store/apps/details?id=com.augmensys.ubik.go invitation link].

{{key press|iOS: Store Beta}}: Available through Apple App Store's [https://testflight.apple.com/join/Kmb1HG9E invitation link].

{{key press|iOS: Store Preview}}: Available through Apple App Store's [https://testflight.apple.com/join/yHRnbYbt invitation link].

{{key press|Windows: Store Preview}}: The mobile Windows client is not an official product and is only distributed as test versions upon request and/or in our [https://release.augmensys.com/download/modules/client/mobile/ release portal].
<br/>

{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with a ⚠️}}

= Release Notes =

== Release ==

=== 5.1.?? on 2026-07-?? ===
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.

=== 5.1.54 on 2026-07-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* You can now specify a boolean command parameter for ContentViewModel.DiscardContentCommand in order to skip the confirmation dialog.

=== 5.1.52 2026-06-23 {{key press|Android: Store Beta}} / 5.1.53 2026-06-24 {{key press|iOS: Store Beta}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where [[XAML_Tips#InvokeOnItemsCommand|BulkOperation.InvokeOnItemsCommand]] was not always applied to all items in the collection.
* Fixed an issue where the app sometimes redirects to the login page on certain Android devices. For example, when the device rotates or a physical keyboard is attached.
* Fixed an issue where the task value editing field is unlimited in space and covers everything else.
* Fixed an issue where filtering was not possible in query popups.
* Fixed an issue where it was not possible to set N/A via editors.
* Fixed an issue where the Properties UI was not refreshed properly after reverting changes.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.
* Fixed an issue where it's impossible to show document files externally from list items.
* (iOS) Fixed an issue where the NFC button in the side menu looked like a toggle button while it's not.
* Fixed an issue where the Unit of a Task value has been clipped.

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true. In Mobile, deleting the last annotation does not correctly update the editor's internal edit state. As a result, the Save button may remain visible even though no edits exist.
* When changing the device orientation during attaching a photo on iOS, the app gets stuck. This is an issue Microsoft confirmed in .NET9 and will fix in .NET10.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Currently, the Samsung keyboard doesn't show {{key press|,}} at all, regardless of the current language/locale setting of the device. Please use a different virtual keyboard (e.g. Gboard from Google) instead if {{key press|.}} is unacceptable.
* The periodic execution of background pushes is not guaranteed on iOS (the native push feature doesn't have this issue).
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* It is currently not possible to select which camera to use for AR views (e.g. scan page) on Windows.
* SfPullToRefresh was removed due to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_Mobile_client|existing issues]], and replaced with a Refresh option in the Context menu.

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

Version 5.1 (WinX)

2026-07-07T08:35:28Z

CWI: /* Release */

{{Attention|This version requires [https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1809_(October_2018_Update) Windows 10 build 17763] or higher}}

== Availability ==
{{key press|Store}}: Publicly available in Microsoft Store.

{{key press|Store Beta}} / {{key press|Store Preview}}: Publicly available in Microsoft Store as beta or preview versions to those whose account email is participating in our beta or preview test. To join, please send an email to testing@augmensys.com and provide an email address to add to the list as well as the information which test you want to join. Alternatively you can contact the Augmensys staff and submit your chosen email address.

Example: Please add my email account example@example.com to the '''Beta''' test group for the '''WinX''' client.

<br/>
{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with ⚠️}}

= Release Notes =

== Release ==

=== 5.1.?? on 2026-07-?? ===
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.

=== 5.1.17 on 2026-07-02 {{key press|Store}} ===
* Fixed an issue where ContentViewModel.Values did not display the values in the [[Developer Mode|developer mode]].
* You can now specify a boolean command parameter for ContentViewModel.DiscardContentCommand in order to skip the confirmation dialog.

=== 5.1.16 on 2026-06-23 {{key press|Store Beta}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Provided a visual difference between suggested and actual values in DateTime and Geo property direct edit fields via a [[XAML#Custom_VisualState_Trigger|Custom VisualState Trigger]].
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems.
* Fixed an issue that caused dialogs to remain open when refreshing, causing problems.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.

=== 5.1.9 on 2026-04-22 {{key press|Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.6 on 2026-02-10 {{key press|Store}} ===
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where certain documents couldn't be loaded anymore.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed an issue where the UI did not update properly when committing a direct edit input task.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the Chart Thresholds didn't update.
* Added a [[XAML#UBIKWebView|UBIKWebView]] control that includes a fix in the WebView2 where some links could not be opened.
* Fixed issue that caused input fields to be focused but not editable.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

[[Category:Version 5.1|Version 5.1 (WinX)]]

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Free Text Annotations that where created in former sessions cannot be selected and therefore cannot be edited any more.
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* Known issues regarding the [[Documents_(Client)#Remember_Document_Settings|Remember Document Settings]] feature:
** Saving the Zoom value via touch gestures is not supported.
** Due to a third-party framework issue it can't be guaranteed that saving the Zoom level is always working properly. We reported this issue and will update our solution as soon as it is resolved on their side.
<br/>

= ⚠️ XAML Notes =
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

{{Category/Version2|{{PAGENAME}}}}

[[Category:Version 5.1|Version 5.1 (WinX)]]

Version 5.1 (Mobile)

2026-06-18T12:59:00Z

CWI: /* 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} */

{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.1. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.}}

{{Attention|UBIK 5 clients can only connect to {{UBIK}} Servers of [[Version 3.6(Server)|version 3.6]] and higher!}}

{{Attention|The minimum supported OS versions are:
* Android 9;
* iOS 12.}}

== Availability ==
{{key press|Android: Store}}{{key press|iOS: Store}}: Publicly available in Google Play Store / Apple App Store.

{{key press|Android: Store Beta}}: Publicly available in Google Play Store as beta versions. You can opt in or out of the beta at any time in the store.

{{key press|Android: Store Preview}}: Available through Google Play Store's [https://play.google.com/store/apps/details?id=com.augmensys.ubik.go invitation link].

{{key press|iOS: Store Beta}}: Available through Apple App Store's [https://testflight.apple.com/join/Kmb1HG9E invitation link].

{{key press|iOS: Store Preview}}: Available through Apple App Store's [https://testflight.apple.com/join/yHRnbYbt invitation link].

{{key press|Windows: Store Preview}}: The mobile Windows client is not an official product and is only distributed as test versions upon request and/or in our [https://release.augmensys.com/download/modules/client/mobile/ release portal].
<br/>

{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with a ⚠️}}

= Release Notes =

== Release ==
=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where [[XAML_Tips#InvokeOnItemsCommand|BulkOperation.InvokeOnItemsCommand]] was not always applied to all items in the collection.
* Fixed an issue where the app sometimes redirects to the login page on certain Android devices. For example, when the device rotates or a physical keyboard is attached.
* Fixed an issue where the task value editing field is unlimited in space and covers everything else.
* Fixed an issue where filtering was not possible in query popups.
* Fixed an issue where it was not possible to set N/A via editors.
* Fixed an issue where the Properties UI was not refreshed properly after reverting changes.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.
* Fixed an issue where it's impossible to show document files externally from list items.
* (iOS) Fixed an issue where the NFC button in the side menu looked like a toggle button while it's not.
* Fixed an issue where the Unit of a Task value has been clipped.

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true. In Mobile, deleting the last annotation does not correctly update the editor's internal edit state. As a result, the Save button may remain visible even though no edits exist.
* When changing the device orientation during attaching a photo on iOS, the app gets stuck. This is an issue Microsoft confirmed in .NET9 and will fix in .NET10.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Currently, the Samsung keyboard doesn't show {{key press|,}} at all, regardless of the current language/locale setting of the device. Please use a different virtual keyboard (e.g. Gboard from Google) instead if {{key press|.}} is unacceptable.
* The periodic execution of background pushes is not guaranteed on iOS (the native push feature doesn't have this issue).
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* It is currently not possible to select which camera to use for AR views (e.g. scan page) on Windows.
* SfPullToRefresh was removed due to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_Mobile_client|existing issues]], and replaced with a Refresh option in the Context menu.

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

Version 5.1 (Mobile)

2026-05-20T10:02:02Z

CWI: /* 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} */

{{Attention|Existing pre 5.0 XAMLs are not compatible with UBIK Mobile client 5.1. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.}}

{{Attention|UBIK 5 clients can only connect to {{UBIK}} Servers of [[Version 3.6(Server)|version 3.6]] and higher!}}

{{Attention|The minimum supported OS versions are:
* Android 9;
* iOS 12.}}

== Availability ==
{{key press|Android: Store}}{{key press|iOS: Store}}: Publicly available in Google Play Store / Apple App Store.

{{key press|Android: Store Beta}}: Publicly available in Google Play Store as beta versions. You can opt in or out of the beta at any time in the store.

{{key press|Android: Store Preview}}: Available through Google Play Store's [https://play.google.com/store/apps/details?id=com.augmensys.ubik.go invitation link].

{{key press|iOS: Store Beta}}: Available through Apple App Store's [https://testflight.apple.com/join/Kmb1HG9E invitation link].

{{key press|iOS: Store Preview}}: Available through Apple App Store's [https://testflight.apple.com/join/yHRnbYbt invitation link].

{{key press|Windows: Store Preview}}: The mobile Windows client is not an official product and is only distributed as test versions upon request and/or in our [https://release.augmensys.com/download/modules/client/mobile/ release portal].
<br/>

{{Attention|Some customized XAMLs might need an update to work properly. These changes are marked with a ⚠️}}

= Release Notes =

== Release ==
=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* UBIK Client now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
* Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true. In Mobile, deleting the last annotation does not correctly update the editor's internal edit state. As a result, the Save button may remain visible even though no edits exist.
* When changing the device orientation during attaching a photo on iOS, the app gets stuck. This is an issue Microsoft confirmed in .NET9 and will fix in .NET10.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Currently, the Samsung keyboard doesn't show {{key press|,}} at all, regardless of the current language/locale setting of the device. Please use a different virtual keyboard (e.g. Gboard from Google) instead if {{key press|.}} is unacceptable.
* The periodic execution of background pushes is not guaranteed on iOS (the native push feature doesn't have this issue).
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* It is currently not possible to select which camera to use for AR views (e.g. scan page) on Windows.
* SfPullToRefresh was removed due to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_Mobile_client|existing issues]], and replaced with a Refresh option in the Context menu.

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

[[Category:Client|Version 5.1 (Mobile)]]
[[Category:Mobile|Version 5.1 (Mobile)]]
[[Category:Version 5.1|Version 5.1 (Mobile)]]

MRO Objects (Client)

2026-05-11T11:08:24Z

CWI: /* Organisational Status */

[[File:MRO_WinX.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:MRO_MAUI1.jpeg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

[[File:TechStats_WinX.png|100px|Technical Status Indicator (Winx & Mobile)]]

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:OrgaStatusIndicatorWinX.PNG|Organisational Status Indicator (WinX)
File:ConfirmedWP_WinX.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:ConfirmedWP_MAUI.jpeg|MRO Workpackage Confirmed Indicator (Mobile)
</gallery>

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:ConfirmingWP_WinX.png|MRO Workpackage confirm button (WinX)
File:MRORevoke_WinX.png|MRO Workpackage revoke confirmation button (WinX)
File:ConfirmingWP_MAUI.jpeg|MRO Workpackage confirm button (Android)
File:MRORevoke_MAUI.jpeg|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

==== Signature Task {{Version/MobileSince|5.1}}{{Version/WinXSince|5.1}} ====

The Signature Task is a task type that is completed by capturing a handwritten signature from the user. The task contains an editor field that serves as the entry point for the signing process. When the user clicks (or taps) on the editor field, a signature dialog opens. Within this dialog, the user can provide their signature. After confirming the input, the signature is saved and the task is automatically marked as completed.

If the task is signed while the client is online:
* The User (signee) is resolved immediately by the server and displayed.
* The ValidationTimestamp is generated and displayed.
* Both values are shown directly in the editor field after signing.

{{Hint|The User only gets resolved by the server and displayed once you're in online mode}}

If the displayed User and/or ValidationTimestamp cannot be fully shown due to limited space in the editor field, the complete information can be accessed via a Popup.
To show the Popup displaying the full User and ValidationTimestamp without truncation, click on the editor field.

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

==== Picture Task {{Version/MobileSince|5.1}}{{Version/WinXSince|5.1}} ====

A [[MROCLS_PICTURE_TASK|picture task]] is a check task which can only be finished when it has at least one child document containing a valid file. In the UI, an additional photo button is presented next to the check so users can easily take photos before finishing the tasks.
* As any other objects, picture tasks can carry and display [[SYSCLS_CHILDINFOOWNER|child count information]]. But that is not a mandatory part of the feature. Even when it's not configured and not visible in the UI, you can still finish the tasks.
* In WinX/UWP, the UI also presents an expander which allows you to display the child documents of picture tasks. This is not present by default in the Mobile app due to the screen size limit but [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Show_NextLevel_Children.2FDocuments|can be easily customized]].

{{Hint|The task is named as such because pictures are the most commonly used types, but the child documents can be of other types as well. }}

When a user tries to finish a picture task by tapping the check, the app might perform some data synchronization first if in online mode, which includes
* Syncing the child objects (including documents) of the task.
* Downloading the file(s) of the child documents.
During data synchronization, the check button on that task turns into a wait indicator. Afterwards, the app checks if the prerequisites to finish the task are met.
* If there are no child documents or no local files for the child documents, the task remains unfinished and the user gets informed about the reasons.
* Otherwise, the task gets finished and the photo button gets disabled.

{{Hint|Setting NA (not applicable) on a picture task is always possible, regardless of the condition of child documents.}}

==== Numeric Task {{Version/MobileSince|5.1}}{{Version/WinXSince|5.1}} ====

A [[MROCLS_MRO_NUMERIC_TASK|numeric task]] is a task which records a double value (e.g. from a temperature sensor). Entering the value (including Not Applicable) completes the task.
* The value is compared against an accaptable value range which is not editable on the client.
* Deviation from this range results in visual feedback as well as the [[#Tech Status|tech status]] being set to display an issue.
* If the configured value range is invalid (e.g. min > max) and the user enters a value, the [[#Tech Status|tech status]] will also be set to display an issue.
* A numeric task also has a special value unit that can be set per task instance. If set, it overrides the standard value unit defined on the [[MetaProperty#Unit_Item|MetaProperty]].

==== Pick List Task {{Version/MobileSince|5.1}}{{Version/WinXSince|5.1}} ====

A [[MROCLS_PICK_LIST_TASK|Pick List task]] looks and behaves the same like a standard Integer Task with SelectiveList. Other than the standard Integer Task, the Pick List Task has an [[UBIK_Active_Lists|Active List]] defined on instance level to pick from for its value property. The task counts as finished as soon as a list item has been selected, or when pressing ''Not Applicable''.

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)
* [[MROCLS_PICK_LIST_TASK]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

File:OrgaStatusIndicatorWinX.PNG

2026-05-11T11:08:03Z

CWI:

File:OrgStatusIndicator.png

2026-05-11T11:06:08Z

CWI: CWI uploaded a new version of File:OrgStatusIndicator.png

File uploaded with MsUpload