UBIK Wiki Test / Augmensys - User contributions [en]

Version 5.1 (Mobile)

2026-03-17T09:39:04Z

REP:

{{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}} ===
* 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.

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

<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-03-17T09:38:43Z

REP: small update to Icon set Addition 8

{{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}} ===
* 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.

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

<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-03-12T16:57:43Z

REP: /* 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.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* 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 adds Show/Hide, AI, Info, and various Procedure icons.

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

<headertabs />

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

Icon Font

2026-03-12T10:40:47Z

REP: /* Viewing Icons */ clarification

'''UBIK-Standard.ttf''' is a custom set of font icons developed primarily for use on the Mobile Client, due to concerns over the legality of using Microsoft's Segoe MDL2 Assets icon font file on non-Windows platforms (ie. Android and iOS). Apart from this legal concern, having a standardized font icon set will contribute to having a more consistent look across the various platforms and clients as UBIK-Standard.ttf becomes more widely adopted.

{{Attention|UBIK-Standard is an <I>Icon Font</I>. For Mobile, the standard Text Font is [https://rsms.me/inter/ Inter], which is included in the resources and thus available to use immediately.}}

{{Attention|UBIK-Standard is currently only supported for the Mobile client.}}

==Viewing Icons==
{{Hint|The latest font set can be downloaded directly from here using the [[File:UBIK-Standard.zip]] file.}}

There are two ways to view which icons are available in the set.
The first requires installing [https://apps.microsoft.com/detail/9WZDNCRDXF41?hl=en-us&gl=AT&ocid=pdpshare Character Map] from the Microsoft store.
Then, download the UBIK-Standard.zip linked above and locate the UBIK-Standard.tff (inside the 'fonts' subfolder). Once the .ttf is also installed on your local PC, you can use the Character Map program you just installed to get a good overview of the full icon set.

[[File:Hexlabelsinmap.PNG]]

For finding the human readable labels that can be used in your xamlx files to display specific icons, you must make sure to unzip UBIK-Standard.zip, then you can open the 'demo.html' file in your web browser. Search for the icon you want either by its Hex code or character value (which you can find in Character Map under the 'Glyph Code' section, or by pressing the Copy button, respectively). These are displayed in the demo.html file on the right and left under each icon, respecitvely. For searching by Hex code, only the last 2-3 characters are required, such as "26" or "123".

[[File:Textlabelsinweb.PNG]]

[[Category:Mobile|Icon Font]]
[[Category:Pages with broken file links|Icon Font]]

==Usage==

===Mobile Client===
Using XAML, Glyphs can be called in two ways. One method is to use the Hex Code, and another is the In-App Name. Of these two methods, the recommended method is to use the In-App Name, as it uses a natural language attribute as opposed to a glyph code, making it more immediately apparent which icon is being requested by the code.

The two below examples show how one might use both methods to create a User symbol.

<br>
====In-App Name Usage====
In the below example, <code>Glyph="{x:Static resources:UBIKIcons.User}"</code> is used to call the <I>User</I> symbol.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel
Glyph="{x:Static resources:UBIKIcons.User}"
HorizontalOptions="Center"
PrimaryColor="{DynamicResource UBIKLightTextColor}"
Style="{DynamicResource HeaderSymbolStyle}"
VerticalOptions="Center" />
</syntaxhighlight>

<br>

====Hex Code Usage====
In the below example, the attribute <code>Glyph=</code> and the following Hex Code is used to call the <I>User</I> icon. These Hex codes can be found using a Character Map program, or by searching through the icon tables below.

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel Glyph=""" HorizontalOptions="Center" />
</syntaxhighlight>

====Directly Accessing Icons====
The icons can also be used like every other font by setting the <code>FontFamily</code> attribute. For example:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:resources="clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL">

<Label HorizontalOptions="Center"
HorizontalTextAlignment="Center"
Text="{x:Static resources:UBIKIcons.User}"
FontFamily="{x:Static UBIKSymbols}"
VerticalOptions="Center"
VerticalTextAlignment="Center" />



</ContentView>
</syntaxhighlight>

== Available Icons==
There are two options available to a customizer wishing to browse available icons.
{{Hint|If a required icon is not found in UBIK, it is instead possible to [[Xamarin_XAML#Custom_Icons|render custom icons using Path data]].}}

'''The best way''' is to download and unzip the [[File:UBIK-Standard.zip]] file. Once unzipped, open the "demo" webpage file to view all icons, as well as the [[Icon_Font#In-App_Name_Usage|human readable labels]] you can use to render them in your UI. Because the demo webpage does not provide a good overview of all the icons, it is possible to combine this approach with the second one described below using that to browse the icons, and then this method to retrieve the human readable labels for the icons you wish to use.
<br>

The second way requires installation of the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse the characters of all the fonts installed on your machine, so to use this method you should certainly download and install the latest version of UBIK-Standard.ttf above. The downside of using this method is that you don't have access to the human readable labels using this app.
{{Attention|Note that icons installed on your machine are not necessarily available to customers, as they only have access to the icons delivered through UBIK, which is version-dependent.}}

<br>

== Known Issues ==
===Mobile Client===
The development of the custom icon font on the Mobile client was hampered significantly by unexpected icon substitutions, which appeared to be vendor/device-specific. To avoid this issue, the individual icons in the text file were mapped to the Hex codes used by the most basic alphabet and symbol characters.

A second issue was encountered where using unstable behavior was observed when using UBIK-Standard.ttf for icons when the user switched tabs, leaving UBIK running in the background. In these cases, circular icon containers became square when switching back to the app, and the icon glyphs were no longer visible. However, using the <i>GlyphButton</i> and <i>GlyphLabel</i> elements (as opposed to simply <i>Button</i> and <i>Label</i>) seems to prevent this issue.

==Creation==
The process for creating icons is documented here.

===Step 01: Asset Creation===
The first step is to find similar, open-source icons to tweak. [https://themes-pixeden.com/font-demos/7-stroke/ Pixeden], [https://lineicons.com/icons/ LineIcons], or [https://linea.io/ LineA], are good starting points, as they have a similar style.

When tweaking (for example, in Adobe Illustrator), use a stroke width of 3 for the base line thickness.

It is good practice to produce three sets of .SVGs; a stroke version, an expanded version, and a final version. The stroke version is more easily edited, but the lines must be 'expanded' in Illustrator to be imported as icons. Finally, duplicate the expanded version, and name it using the following syntax:
<code>001#ubik-U0x26</code>

* The first number is used to keep the icon list orderly.
* Add as many tags as desired using the # as separators. For example, a check mark icon may be listed as #ok#confirm#check. The - ends the tag portion of the syntax.
* The glyph code assigns the icon to a certain space on the character map. As different device vendors block different glyph code sets for different uses, it is good practice to overwrite the basic alphabet, numbers, and symbols, to ensure the icons work on a large range of devices. Starting from 21, glyph codes may use numbers, or letters from 2A (2 here being an example) to 2F.

===Step 02: TTF Generation===
[https://icomoon.io/app/ IcoMoon] is a useful online tool for generating the icon font, that can then be installed on a device or packaged into the client resources.

* Import Icons (top left) - Use this button to import an already existing font file, when creating additions, for example.
* On the Selection tab (bottom center), ensure that the desired set is fully selected, and shown with an orange outline.
* On the Generate Font tab (bottom right), double check the generated tags for the icons. The settings button beside the download button allows you to edit the font file name and version.
* The download button exports the .ttf, among other resources, in a .ZIP, that is then downloaded.

[[Category:Mobile|Icon Font]]
[[Category:Pages with broken file links|Icon Font]]

Icon Font

2026-03-12T10:39:39Z

REP: Added info on how to view icon set

'''UBIK-Standard.ttf''' is a custom set of font icons developed primarily for use on the Mobile Client, due to concerns over the legality of using Microsoft's Segoe MDL2 Assets icon font file on non-Windows platforms (ie. Android and iOS). Apart from this legal concern, having a standardized font icon set will contribute to having a more consistent look across the various platforms and clients as UBIK-Standard.ttf becomes more widely adopted.

{{Attention|UBIK-Standard is an <I>Icon Font</I>. For Mobile, the standard Text Font is [https://rsms.me/inter/ Inter], which is included in the resources and thus available to use immediately.}}

{{Attention|UBIK-Standard is currently only supported for the Mobile client.}}

==Viewing Icons==
{{Hint|The latest font set can be downloaded directly from here using the [[File:UBIK-Standard.zip]] file.}}

There are two ways to view which icons are available in the set.
The first requires installing [https://apps.microsoft.com/detail/9WZDNCRDXF41?hl=en-us&gl=AT&ocid=pdpshare Character Map] from the Microsoft store.
Then, download the UBIK-Standard.zip linked above and locate the UBIK-Standard.tff (inside the 'fonts' subfolder). Once this is installed on your local PC, you can use the Character Map program you just installed to get a good overview of the full icon set.

[[File:Hexlabelsinmap.PNG]]

For finding the human readable labels that can be used in your xamlx files to display specific icons, you must make sure to unzip UBIK-Standard.zip, then you can open the 'demo.html' file in your web browser. Search for the icon you want either by its Hex code or character value (which you can find in Character Map under the 'Glyph Code' section, or by pressing the Copy button, respectively). These are displayed in the demo.html file on the right and left under each icon, respecitvely. For searching by Hex code, only the last 2-3 characters are required, such as "26" or "123".

[[File:Textlabelsinweb.PNG]]

==Usage==

===Mobile Client===
Using XAML, Glyphs can be called in two ways. One method is to use the Hex Code, and another is the In-App Name. Of these two methods, the recommended method is to use the In-App Name, as it uses a natural language attribute as opposed to a glyph code, making it more immediately apparent which icon is being requested by the code.

The two below examples show how one might use both methods to create a User symbol.

<br>
====In-App Name Usage====
In the below example, <code>Glyph="{x:Static resources:UBIKIcons.User}"</code> is used to call the <I>User</I> symbol.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel
Glyph="{x:Static resources:UBIKIcons.User}"
HorizontalOptions="Center"
PrimaryColor="{DynamicResource UBIKLightTextColor}"
Style="{DynamicResource HeaderSymbolStyle}"
VerticalOptions="Center" />
</syntaxhighlight>

<br>

====Hex Code Usage====
In the below example, the attribute <code>Glyph=</code> and the following Hex Code is used to call the <I>User</I> icon. These Hex codes can be found using a Character Map program, or by searching through the icon tables below.

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel Glyph=""" HorizontalOptions="Center" />
</syntaxhighlight>

====Directly Accessing Icons====
The icons can also be used like every other font by setting the <code>FontFamily</code> attribute. For example:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:resources="clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL">

<Label HorizontalOptions="Center"
HorizontalTextAlignment="Center"
Text="{x:Static resources:UBIKIcons.User}"
FontFamily="{x:Static UBIKSymbols}"
VerticalOptions="Center"
VerticalTextAlignment="Center" />



</ContentView>
</syntaxhighlight>

== Available Icons==
There are two options available to a customizer wishing to browse available icons.
{{Hint|If a required icon is not found in UBIK, it is instead possible to [[Xamarin_XAML#Custom_Icons|render custom icons using Path data]].}}

'''The best way''' is to download and unzip the [[File:UBIK-Standard.zip]] file. Once unzipped, open the "demo" webpage file to view all icons, as well as the [[Icon_Font#In-App_Name_Usage|human readable labels]] you can use to render them in your UI. Because the demo webpage does not provide a good overview of all the icons, it is possible to combine this approach with the second one described below using that to browse the icons, and then this method to retrieve the human readable labels for the icons you wish to use.
<br>

The second way requires installation of the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse the characters of all the fonts installed on your machine, so to use this method you should certainly download and install the latest version of UBIK-Standard.ttf above. The downside of using this method is that you don't have access to the human readable labels using this app.
{{Attention|Note that icons installed on your machine are not necessarily available to customers, as they only have access to the icons delivered through UBIK, which is version-dependent.}}

<br>

== Known Issues ==
===Mobile Client===
The development of the custom icon font on the Mobile client was hampered significantly by unexpected icon substitutions, which appeared to be vendor/device-specific. To avoid this issue, the individual icons in the text file were mapped to the Hex codes used by the most basic alphabet and symbol characters.

A second issue was encountered where using unstable behavior was observed when using UBIK-Standard.ttf for icons when the user switched tabs, leaving UBIK running in the background. In these cases, circular icon containers became square when switching back to the app, and the icon glyphs were no longer visible. However, using the <i>GlyphButton</i> and <i>GlyphLabel</i> elements (as opposed to simply <i>Button</i> and <i>Label</i>) seems to prevent this issue.

==Creation==
The process for creating icons is documented here.

===Step 01: Asset Creation===
The first step is to find similar, open-source icons to tweak. [https://themes-pixeden.com/font-demos/7-stroke/ Pixeden], [https://lineicons.com/icons/ LineIcons], or [https://linea.io/ LineA], are good starting points, as they have a similar style.

When tweaking (for example, in Adobe Illustrator), use a stroke width of 3 for the base line thickness.

It is good practice to produce three sets of .SVGs; a stroke version, an expanded version, and a final version. The stroke version is more easily edited, but the lines must be 'expanded' in Illustrator to be imported as icons. Finally, duplicate the expanded version, and name it using the following syntax:
<code>001#ubik-U0x26</code>

* The first number is used to keep the icon list orderly.
* Add as many tags as desired using the # as separators. For example, a check mark icon may be listed as #ok#confirm#check. The - ends the tag portion of the syntax.
* The glyph code assigns the icon to a certain space on the character map. As different device vendors block different glyph code sets for different uses, it is good practice to overwrite the basic alphabet, numbers, and symbols, to ensure the icons work on a large range of devices. Starting from 21, glyph codes may use numbers, or letters from 2A (2 here being an example) to 2F.

===Step 02: TTF Generation===
[https://icomoon.io/app/ IcoMoon] is a useful online tool for generating the icon font, that can then be installed on a device or packaged into the client resources.

* Import Icons (top left) - Use this button to import an already existing font file, when creating additions, for example.
* On the Selection tab (bottom center), ensure that the desired set is fully selected, and shown with an orange outline.
* On the Generate Font tab (bottom right), double check the generated tags for the icons. The settings button beside the download button allows you to edit the font file name and version.
* The download button exports the .ttf, among other resources, in a .ZIP, that is then downloaded.

[[Category:Mobile|Icon Font]]
[[Category:Pages with broken file links|Icon Font]]

File:Hexlabelsinmap.PNG

2026-03-12T10:38:34Z

REP: REP uploaded a new version of File:Hexlabelsinmap.PNG

File:Hexlabelsinmap.PNG

2026-03-12T10:35:39Z

REP: REP uploaded a new version of File:Hexlabelsinmap.PNG

File:Hexlabelsinmap.PNG

2026-03-12T10:35:37Z

REP: REP uploaded a new version of File:Hexlabelsinmap.PNG

File:Textlabelsinweb.PNG

2026-03-12T10:34:36Z

REP: REP uploaded a new version of File:Textlabelsinweb.PNG

File:Textlabelsinweb.PNG

2026-03-12T10:34:16Z

REP: REP uploaded a new version of File:Textlabelsinweb.PNG

File:Hexlabelsinmap.PNG

2026-03-12T10:32:53Z

REP:

File:Textlabelsinweb.PNG

2026-03-12T10:32:25Z

REP:

Icon Font

2026-03-12T09:39:45Z

REP: /* Mobile Client */ removed mention of icon tables as they were eliminated due to maintenance cost

'''UBIK-Standard.ttf''' is a custom set of font icons developed primarily for use on the Mobile Client, due to concerns over the legality of using Microsoft's Segoe MDL2 Assets icon font file on non-Windows platforms (ie. Android and iOS). Apart from this legal concern, having a standardized font icon set will contribute to having a more consistent look across the various platforms and clients as UBIK-Standard.ttf becomes more widely adopted.

{{Hint|The latest font set can be downloaded directly from here using the [[File:UBIK-Standard.zip]] file.}}

{{Attention|UBIK-Standard is an <I>Icon Font</I>. For Mobile, the standard Text Font is [https://rsms.me/inter/ Inter], which is included in the resources and thus available to use immediately.}}

{{Attention|UBIK-Standard is currently only supported for the Mobile client.}}

==Usage==

===Mobile Client===
Using XAML, Glyphs can be called in two ways. One method is to use the Hex Code, and another is the In-App Name. Of these two methods, the recommended method is to use the In-App Name, as it uses a natural language attribute as opposed to a glyph code, making it more immediately apparent which icon is being requested by the code.

The two below examples show how one might use both methods to create a User symbol.

<br>
====In-App Name Usage====
In the below example, <code>Glyph="{x:Static resources:UBIKIcons.User}"</code> is used to call the <I>User</I> symbol.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel
Glyph="{x:Static resources:UBIKIcons.User}"
HorizontalOptions="Center"
PrimaryColor="{DynamicResource UBIKLightTextColor}"
Style="{DynamicResource HeaderSymbolStyle}"
VerticalOptions="Center" />
</syntaxhighlight>

<br>

====Hex Code Usage====
In the below example, the attribute <code>Glyph=</code> and the following Hex Code is used to call the <I>User</I> icon. These Hex codes can be found using a Character Map program, or by searching through the icon tables below.

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL" >

<controls:GlyphLabel Glyph=""" HorizontalOptions="Center" />
</syntaxhighlight>

====Directly Accessing Icons====
The icons can also be used like every other font by setting the <code>FontFamily</code> attribute. For example:

<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:resources="clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL">

<Label HorizontalOptions="Center"
HorizontalTextAlignment="Center"
Text="{x:Static resources:UBIKIcons.User}"
FontFamily="{x:Static UBIKSymbols}"
VerticalOptions="Center"
VerticalTextAlignment="Center" />



</ContentView>
</syntaxhighlight>

[[Category:Mobile|Icon Font]]
[[Category:Pages with broken file links|Icon Font]]

== Available Icons==
There are two options available to a customizer wishing to browse available icons.
{{Hint|If a required icon is not found in UBIK, it is instead possible to [[Xamarin_XAML#Custom_Icons|render custom icons using Path data]].}}

'''The best way''' is to download and unzip the [[File:UBIK-Standard.zip]] file. Once unzipped, open the "demo" webpage file to view all icons, as well as the [[Icon_Font#In-App_Name_Usage|human readable labels]] you can use to render them in your UI. Because the demo webpage does not provide a good overview of all the icons, it is possible to combine this approach with the second one described below using that to browse the icons, and then this method to retrieve the human readable labels for the icons you wish to use.
<br>

The second way requires installation of the [https://apps.microsoft.com/detail/9wzdncrdxf41?hl=en-US&gl=US| Character Map] tool from Microsoft. This can be used to browse the characters of all the fonts installed on your machine, so to use this method you should certainly download and install the latest version of UBIK-Standard.ttf above. The downside of using this method is that you don't have access to the human readable labels using this app.
{{Attention|Note that icons installed on your machine are not necessarily available to customers, as they only have access to the icons delivered through UBIK, which is version-dependent.}}

<br>

== Known Issues ==
===Mobile Client===
The development of the custom icon font on the Mobile client was hampered significantly by unexpected icon substitutions, which appeared to be vendor/device-specific. To avoid this issue, the individual icons in the text file were mapped to the Hex codes used by the most basic alphabet and symbol characters.

A second issue was encountered where using unstable behavior was observed when using UBIK-Standard.ttf for icons when the user switched tabs, leaving UBIK running in the background. In these cases, circular icon containers became square when switching back to the app, and the icon glyphs were no longer visible. However, using the <i>GlyphButton</i> and <i>GlyphLabel</i> elements (as opposed to simply <i>Button</i> and <i>Label</i>) seems to prevent this issue.

==Creation==
The process for creating icons is documented here.

===Step 01: Asset Creation===
The first step is to find similar, open-source icons to tweak. [https://themes-pixeden.com/font-demos/7-stroke/ Pixeden], [https://lineicons.com/icons/ LineIcons], or [https://linea.io/ LineA], are good starting points, as they have a similar style.

When tweaking (for example, in Adobe Illustrator), use a stroke width of 3 for the base line thickness.

It is good practice to produce three sets of .SVGs; a stroke version, an expanded version, and a final version. The stroke version is more easily edited, but the lines must be 'expanded' in Illustrator to be imported as icons. Finally, duplicate the expanded version, and name it using the following syntax:
<code>001#ubik-U0x26</code>

* The first number is used to keep the icon list orderly.
* Add as many tags as desired using the # as separators. For example, a check mark icon may be listed as #ok#confirm#check. The - ends the tag portion of the syntax.
* The glyph code assigns the icon to a certain space on the character map. As different device vendors block different glyph code sets for different uses, it is good practice to overwrite the basic alphabet, numbers, and symbols, to ensure the icons work on a large range of devices. Starting from 21, glyph codes may use numbers, or letters from 2A (2 here being an example) to 2F.

===Step 02: TTF Generation===
[https://icomoon.io/app/ IcoMoon] is a useful online tool for generating the icon font, that can then be installed on a device or packaged into the client resources.

* Import Icons (top left) - Use this button to import an already existing font file, when creating additions, for example.
* On the Selection tab (bottom center), ensure that the desired set is fully selected, and shown with an orange outline.
* On the Generate Font tab (bottom right), double check the generated tags for the icons. The settings button beside the download button allows you to edit the font file name and version.
* The download button exports the .ttf, among other resources, in a .ZIP, that is then downloaded.

[[Category:Mobile|Icon Font]]
[[Category:Pages with broken file links|Icon Font]]

HowTo:Convert Xamarin XAMLs to Maui

2026-03-11T15:33:33Z

REP: /* 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>
|-
|}

[[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-03-11T15:33:05Z

REP: /* Highly Recommended */ Added sections on Delay/LazyLoad and TemplateConverter

HowTo:Convert Xamarin XAMLs to Maui

2026-03-10T15:49:24Z

REP: /* SfPullToRefresh */ Tried to make message not to use PTR clearer as AI didnt get it

== 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 ==
=== 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>
|-
|}

== 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-03-10T15:46:56Z

REP: /* SfTabView */ added warning and link to 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 ===

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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>
|}

== Highly Recommended ==
=== 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>
|-
|}

== 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-03-10T15:41:13Z

REP: Restructured wiki from most to least important, added SfTabView and PTR under Mandatory

== 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 ===

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

=== SfPullToRefresh ===

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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>
|}

== Highly Recommended ==
=== 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>
|-
|}

== 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-03-10T14:57:08Z

REP: Restructured wiki from most to least important

== 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 ==

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

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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>
|}

== Highly Recommended ==
=== 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>
|-
|}

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

File:UBIK-Standard.zip

2026-03-02T15:07:18Z

REP: REP uploaded a new version of File:UBIK-Standard.zip

Latest version of UBIk-Standard.ttf as of 27 September 2019.

HowTo:Convert Xamarin XAMLs to Maui

2026-02-16T09:31:37Z

REP: /* UBIKTabView */ Added link to SF docs

== Information ==
=== 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 ... />
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}
== 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>
|}
== Highly Recommended ==
=== 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>
|-
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== 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>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== SfTabView ==

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

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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]]

Mobile XAML

2026-02-10T15:34:30Z

REP: /* XAML Changes And Improvements */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= 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). It is also combined 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.

=== 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-02-10T15:14:11Z

REP: /* Mandatory */ Restructured an unclear section

== Information ==
=== 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 ... />
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}
== 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>
|}
== Highly Recommended ==
=== 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).

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>
|-
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== 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>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== SfTabView ==

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

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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]]

Version 5.0 (WinX)

2026-02-10T14:59:24Z

REP: Added release note for status colors

{{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.0.42 on 2026-01-27 {{key press|Store}} ===
* Fixed an issue where confirmed work packages are not automatically committed when you switch from offline to online mode.
* Added a visualization of StatusColor to root and document items that don't additionally have [[MRO_Objects_(Client)#Work_Progress|MRO progress]].

=== 5.0.41 on 2026-01-14 {{key press|Store}} ===
* Fixed an issue where [[MRO_Objects_(Client)#Work_Progress|MRO progress]] is rounded up too aggressively and inconsistent with the mobile clients.

=== 5.0.40 on 2025-12-18 {{key press|Store}} ===
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.

=== 5.0.36 on 2025-10-02 {{key press|Store}} ===
* Fixed an issue where task direct editing doesn't work the first time.

=== 5.0.35 on 2025-09-29 {{key press|Store}} ===
* Updated some translations.
* Updated the default Demo profile.
* Updated the notification message about branch download to avoid misunderstanding. When a branch download is in progress, you can work with the offline data which is already available at the time of the download, but any communication with the content server will be scheduled after the branch download is finished.
* Fixed issue that rendered authentication when editing a geo property impossible.
* Fixed an issue that triggered a license warning even on a failed login.
* Fixed an issue where the wizard is shown again when you navigate to a new but saved object offline.
* Fixed an issue where duplicate notifications are shown when you scan an NFC tag for a supervisor task and no fitting supervisor is found.

== Known issues ==
* 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 =

<headertabs />

{{Category/Version2|{{PAGENAME}}}}

[[Category:Client|Version 5.0 (WinX)]]
[[Category:Version 5.0|Version 5.0 (WinX)]]
[[Category:WinX|Version 5.0 (WinX)]]

Mobile XAML

2026-01-14T10:13:23Z

REP: /* Styles and Resources */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= 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;
** '''UBIKGradientColor''' is a brighter version of UBIKAccentColor. This can be achieved easily by adding an alpha prefix to the desired Accent color (eg. "#52ff8800" = 32% opacity of color #ff8800), or defined as a different color.
* 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'.

[[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-01-14T10:12:36Z

REP: /* XAML Changes And Improvements */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= 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>
* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKGradientColor is a brighter version of UBIKAccentColor. This can be achieved easily by adding an alpha prefix to the desired Accent color (eg. "#52ff8800" = 32% opacity of color #ff8800), or defined as a different color.
* 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>

* 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'.

=== 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-01-14T09:42:07Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= 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>

* 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'.

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

== 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-01-14T09:04:29Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== Main Changes ==
=== 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>

* 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'.

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

== 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-01-14T09:04:16Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== Main Changes ==
=== 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>

* 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'.

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

== 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-01-13T16:08:31Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== Main Changes ==
=== 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>

* 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'.

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

== 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-01-13T15:54:39Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== Main Changes ==
=== 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>

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

- ListView and item color

=== Adaptivity ===

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

== 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-01-13T15:08:24Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== 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-01-13T15:07:48Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} */ Adding dark theme cookbook

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

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

== 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-01-13T14:13:43Z

REP: /* UBIK Go (Maui) Customizing Guide {{Version/WinXSince|5.1}} */ Corrected wrong Since flag

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity to visually update the client's default UI.

[[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-01-13T14:12:39Z

REP: Adding a section on the new standard UI

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

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

= UBIK Go (Maui) Customizing Guide {{Version/WinXSince|5.1}} =
The change to Maui was taken as an opportunity to visually update the client's default UI.

[[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

2025-12-15T09:17:39Z

REP: /* Highly Recommended */

== Information ==
=== 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 ... />
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}
== 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>
|}
== Highly Recommended ==
=== 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).

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>
|-
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== 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">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

=== Syncfusion control updates ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| * LeftSwipeTemplate, RightSwipeTemplate
| StartSwipeTemplate, EndSwipeTemplate
|}

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <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].

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== SfTabView ==

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

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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]]

Mobile XAML

2025-12-12T11:19:56Z

REP: /* Delay and LazyLoading */

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

== 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.
* Use async/await to avoid blocking user interface.
* 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.

=== 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://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/text/label#formatted-text FormattedText] instead of multiple labels.
* 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 >

=== 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>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

= 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>

[[Category:Client|Xamarin XAML]]
[[Category:Mobile|Mobile XAML]]
[[Category:Pages with broken file links|Xamarin XAML]]
[[Category:Styling|Xamarin XAML]]
[[Category:XAML|Xamarin XAML]]

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

[[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

2025-11-11T09:15:31Z

REP: /* Frame to Border */

== Information ==
=== 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 ... />
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}
== 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>
|}
== Highly Recommended ==
=== 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.

== 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">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

=== Syncfusion control updates ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| * LeftSwipeTemplate, RightSwipeTemplate
| StartSwipeTemplate, EndSwipeTemplate
|}

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <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].

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:Mobile|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== SfTabView ==

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

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' 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.

{| 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]]

HowTo:Convert Xamarin XAMLs to Maui

2025-09-11T12:28:27Z

REP: /* TapGestureRecognizer and Swipe Conflict */

== Information ==
=== Frame to Border ===
'''Use Border instead of Frame.'''
Frame is deprecated in MAUI. Use Border with `Stroke` instead of `BorderColor`.

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

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:MAUI|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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>
|}
== 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>
|}
== Highly Recommended ==
=== 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}"<br/>Style="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"<br/>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.

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:MAUI|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

== 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
|}

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">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

=== Syncfusion control updates ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| * LeftSwipeTemplate, RightSwipeTemplate
| StartSwipeTemplate, EndSwipeTemplate
|}

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <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 changed. It is recommended to use the inline syntax (see example) 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.
Please rely 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'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>

|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| WinPhone
| WinUI
|-
| <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>
|}

=== 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>
|}

=== 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>
|}

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:MAUI|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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:MAUI|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

=== 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
|}

=== 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>
|}

== SfTabView ==

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

== OnPlatform + OnIdiom backup ==

=== Syntax Changes ===
'''Use inline or multi-tag syntax.'''
Single-tag syntax is outdated and may not build.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><OnPlatform Android="False" iOS="True" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><TheControl TheProperty="{OnPlatform Android=False, iOS=True}" /></syntaxhighlight>
|}

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<OnPlatform x:TypeArguments="TheType">
<On Platform="Android" Value="False" />
<On Platform="iOS" Value="True" />
</OnPlatform>
</syntaxhighlight>
| Required for multi-tag syntax
|}

=== WinPhone to WinUI ===
'''Replace WinPhone with WinUI.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| WinPhone
| WinUI
|}

=== GridLength and TypeArguments ===
'''Avoid x:TypeArguments with GridLength.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ColumnDefinition.Width>
<OnIdiom x:TypeArguments="GridLength" Desktop="Auto" Phone="*" />
</ColumnDefinition.Width>
</syntaxhighlight>
| <syntaxhighlight lang="xml"><ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" /></syntaxhighlight>
|}

⚠️ Inline syntax is more reliable when using bindings or resources.

=== Special Characters ===
'''Wrap values in quotes if they contain commas or strings.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Margin={OnIdiom 10,2, Phone=2,0}
| Margin={OnIdiom '10,2', Phone='2,0'}
|}

=== UWP to WinUI ===
'''Replace UWP with WinUI in all OnPlatform scopes.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| UWP
| WinUI
|}

⚠️ For more details, refer to the [https://wiki.augmensys.com/index.php?title=XAML_Tips#Device_and_Platform_Responsiveness Wiki documentation].

[[Category:How-To|Convert Xamarin XAMLs to Maui]]
[[Category:MAUI|Convert Xamarin XAMLs to Maui]]
[[Category:XAML|Convert Xamarin XAMLs to Maui]]

XAML Tips

2025-09-05T07:48:34Z

REP: /* Set a Binding as PropertyValue */

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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="Xamarin / Maui">
<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>

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

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>

<tab name="Xamarin/Maui">
<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>

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

=== 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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

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

XAML Tips

2025-09-05T07:48:04Z

REP: /* Set a Binding as PropertyValue */ Added mobile syntax example

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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="Xamarin / Maui">
<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.

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

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>

<tab name="Xamarin/Maui">
<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>

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

=== 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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

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

XAML Tips

2025-09-05T07:45:55Z

REP: /* Set Current DateTime */

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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:
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

The above code uses the x:Name of the button to specify the viewmodel from which we wish to begin our binding path.<br>
You do not need to follow this exact syntax, all that is necessary is to provide a connection to the BindingContext of an observable control.

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>

<tab name="Xamarin/Maui">
<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>

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

=== 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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

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

XAML Tips

2025-09-05T07:45:11Z

REP: /* Set Current DateTime */

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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:
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

The above code uses the x:Name of the button to specify the viewmodel from which we wish to begin our binding path.<br>
You do not need to follow this exact syntax, all that is necessary is to provide a connection to the BindingContext of an observable control.

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>
<tab name="Xamarin/Maui">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</tab>
</tabs>

<br>

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

=== 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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

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

XAML Tips

2025-09-05T07:40:31Z

REP: /* Set a Binding as PropertyValue */ Added mobile syntax example

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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:
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

The above code uses the x:Name of the button to specify the viewmodel from which we wish to begin our binding path.<br>
You do not need to follow this exact syntax, all that is necessary is to provide a connection to the BindingContext of an observable control.

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>
<tab name="Xamarin">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

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

XAML Tips

2025-09-05T07:39:53Z

REP: /* Set a Binding as PropertyValue */ Added mobile syntax example

== 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="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).
**Xamarin: 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="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 (Xamarin) 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="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:example="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="Xamarin / Maui">
<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'' with your desired binding, such as ''AppStatus.CurrentLogin.RawDetails[...]'' etc.}}
</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 any named control observable by this button.

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

==== Set Current DateTime ====
The current DateTime stamp can be retrieved from '''AppStatus.LiveDateTime'''.<br>
Since the known issue described in the section above prevents direct binding to this, below are examples for how to implement it.

<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:example="using:UBIK.WinX.Controls"
...
<Button
x:Name="SetCurrentDateTimeButton"
Tag="{Binding}"
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton}" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
{{Hint|The DateTime can be set to the desired format by adding a StringFormatConverter to the LiveDateTime binding:<br><nowiki>"{Binding Tag.AppStatus.LiveDateTime, ElementName=SetCurrentDateTimeButton, </nowiki>'''<nowiki>Converter={StaticResource StringFormatConverter}, ConverterParameter={0:yyyy-MM-dd HH:mm}</nowiki>'''<nowiki>}" </nowiki>.}}
</tab>
<tab name="Xamarin">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</tab>
</tabs>

<br>

=== SaveAndCommitCommand ===
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="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="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="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="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 (Xamarin) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Xamarin, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

== Showing Images and Icons ==
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="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 '''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. 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]. 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>

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

== 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="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="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>

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

=== 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="Xamarin">
<source lang = "xml">
<x:String x:Key="AutoSaveDocumentsOnPageClose">true</x:String>
</source>
</tab>
</tabs>

== Platform and Device-specific UI with OnPlatform and OnIdiom ==
{{UnderConstructionStart}}
<br>
Although '''OnPlatform''' and '''OnIdiom''' are used in Xamarin, the following wiki article is valid from MAUI 5.0 (add version flag), as the syntax changed.

'''OnPlatform''' can be used to define different property values based on the platform. Valid Platform names are:
* iOS
* Android
* WinUI (for MAUI Windows)
* further ones see [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0#customize-ui-appearance-with-a-markup-extension-based-on-the-platform here]
<br>
'''OnIdom''' can be used to define different property values based on the device type (e.g. Phone, Tablet, Desktop).

When it comes to the proper syntax, we should stick with the approaches mentioned in the [https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/customize-ui-appearance?view=net-maui-9.0 official documentation].
Means, we should '''avoid''' using the single-tag syntax like ''<OnPlatform Android="..." iOS="..." />'' or ''<OnIdiom Phone="..." Desktop="..." />'' 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.}}

{{UnderConstructionEnd}}

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

HowTo:Implement Custom Filtering

2025-08-28T12:00:35Z

REP: /* Filtering a DateTime Property */ added section on troubleshooting localization

This page describes how to customize filtered lists that accept one or multiple user inputs as filter criteria (referred to as 'Dynamic'), alone or combined with predefined criteria(referred to as 'Static'). The following examples are based on the Children.Items collection, however, Properties or Documents can be filtered too, by adjusting the ItemsSource in the <cv:ListCollectionView> or <controls:SfDataSourceExt> in UWP or Xamarin respectively.

{{Attention|Are you sure you need this?<br>UBIK has a simpler out-of-the-box Property-based filtering technique for filtering child objects when one or multiple property value inputs are the only type of criteria required. See [[Property_Based_Content_Filters]]}}

Four elements are required for Custom Filtering:
* Input field - for user inputs.
* [[EvalExpression]] - for converting user inputs into a filter expression.
* Collection Filter - for applying the expression to a collection.
* Items control - for displaying the filtered items.
<br>
<br>
This system acts dynamically to output the filtered list, without requiring the use of an Evaluation button, and directly outputs all items that match the filter input.

This page will first describe the basic implementation of a single dynamic input, then describe how to allow for multiple inputs, and finally, how to combine multiple dynamic inputs with static, predefined criteria.
However, keep in mind that for simply dynamically filtering child objects based on single or multiple property values, this complex customizing is not required. Instead, this technique gives the possibility to create multiple collections based on the same child collection, each with individual filters that do not interfere with each other, or else to create filters based on dynamic inputs for Properties or Documents, which are not handled by the Content-Based Filtering functionality.

<br>
== Basic Implementation ==
To build the filter in XAML, you will need to place an EvalExpression and a Collection Filter in the Resources of your container (most likely, a Grid). In the container's content, you will need the Input control, and the items control as an output (most likely a ListView).

The following namespaces are used:
<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
</source>
</tab>
</tabs>

=== Resources ===
For UWP, it is possible to place the EvalExpression and Collection Filter into the <Grid.Resources>, as shown below. However, for Xamarin, it is required to use the <ContentView.Resources>.
For the Collection Filter, use [[XAML_Changes_in_UBIK_WinX_3.5#Filtering_by_expressions|ListCollectionView]] for UWP & [[Xamarin_XAML#FeatureRelated|Content_filtering]] for Xamarin:

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid.Resources>
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<cv:ListCollectionView
x:Key="FilterView"
Expression="{Binding ElementName=FilterExpression, Path=Result}"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
</source>

{{Attention|Note that the EvalExpression in UWP requires an x:Name, which in turn requires the 'ElementName' syntax seen in the <cv:ListCollectionView>.}}
{{Attention|Note that the Converter seen in the 'EXP' EvalExpressionParameter in UWP is 'StringFormatConverter', which is different than in Xamarin.}}
</tab>

<tab name="Xamarin">
<source lang = "xml">
<ContentView.Resources>
<ResourceDictionary>
<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<controls:SfDataSourceExt
x:Key="FilterView"
Expression="{Binding Source={StaticResource FilterExpression}, Path=Result}"
ItemsSource="{Binding Children.Items}"
Unloaded="{Binding SkipFiltering}"/>
</ResourceDictionary>
</ContentView.Resources>
</source>
{{Attention|Note that Unloaded attribute improves performance by preventing refiltering while navigating away from the page. This attribute should be added to all instances of controls:SfDataSourceExt in your customizing.}}
{{Hint|Note that the EvalExpression in Xamarin requires an x:Key, which in turn requires the 'StaticResource ' syntax seen in the <controls:SfDataSourceExt>.}}
{{Hint|Note that the Converter seen in the 'EXP' EvalExpressionParameter in Xamarin is 'StringFormat', which is different than in UWP.}}
</tab>
</tabs>

The EvalExpression Expression first checks whether the TextBox input is empty (as this would otherwise incorrectly be considered a filter input, whereby the property should be empty) and if so returns the unfiltered list (expression outcome hardcoded to 'true'), otherwise, applies the filter (expression outcome is taken from string constructed in ConverterParameter of 'EXP').

There are two important details of the EvalExpressionParameter to note here:
* The "ElementName=NameInput" / "x:Reference NameInput" should match exactly to the name of your Input control.
* The Item.Values["NAME"] should be adapted, by changing NAME to the property that should be filtered by this input.

=== TextBox / Entry ===
The input field is just a basic <Textbox> / <Entry> we will use to input the filter criteria value. The only important detail for this input control is the name, which must be passed back to the EvalExpressionParameter.
<br>
<br>
It will look like this:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput"/>
</source>
</tab>
</tabs>

=== Items control ===
An items control will likely be used for displaying filtered results, such as <controls:SelectionBoundListView> for UWP & [[Xamarin_XAML#Performance|SfListViewExt]] for Xamarin:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:SelectionBoundListView
x:Name="FilterQueryList"
ItemsSource="{StaticResource FilterView}" />
</source>
</tab>

<tab name="Xamarin">
<source lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
ItemsSource="{Binding DisplayItems, Source={StaticResource FilterView}}" />
</source>
</tab>
</tabs>
<br>

== Multiple Dynamic (User Inputs) Criteria ==
It is likely that the customizing is required to process multiple user inputs for the same filter. In this case, the EvalExpression must be adapted to combine the inputs (most likely using an AND relation, for a 'filtering-down' effect), as well as to deliver the full list when nothing is inputted.
A <Textbox> / <Entry>, and an EvalExpression, will be required for every additional property, as well as a final EvalExpression to combine them.

The EvalExpressions should be amended as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DescInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DescInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DescInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference DescInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
<br>

The above example shows how to check for inputs to either property, NAME and DESCR, then use an additional EvalExpression to create the expression string that combines them. For each additional property you need to:
* Create an EvalExpression that checks whether the text input is null or empty, and if not, returns the desired expression EXP.
* Add each EvalExpression (Name_FilterExpression, Desc_FilterExpression) to the 'main' one (FilterExpression) as Parameters, combined using the escaped '&&' concatenation symbols.

{{Attention|Due to the escaped syntax required in the Expression, <source lang = "xml">+"&&"+</source> is the correct syntax required to concatenate filter expressions together.}}

Once the additional input controls have been created, processed in their own EvalExpressions, referenced as EvalExpressionParameters and the "FilterExpression" EvalExpression has been adapted as shown, the filter should already function as required; the Collection Filters and Items Controls do not need to be adapted.
<br>

=== One Input To Filter Multiple Properties ===
Since we have control over how the input is matched against the properties, is possible to use the same input to filter against multiple properties, for example, both Title and SubTitle. This keeps the UI lean with less elements to clutter the layout, and the user is not forced to think about which input relates to which field. The downside, of course, is that the search will be slightly less refined.
This is achieved easily as shown:

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT " Value="{Binding ElementName=Title_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding ElementName=SubTitle_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT" Value="{Binding Source={StaticResource Title_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding Source={StaticResource SubTitle_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

{{Attention|Note the different operator required in this case. Unless your object has the same Title ''and'' SubTitle, there will be no match found unless the FilterExpression is amended to an Or relationship.}}

<br>

== Combining Dynamic (User Inputs) and Static (Predefined) Criteria ==
A common use of the Collection Filter is to filter child lists based on one or multiple properties, such as MetaDefinition.UID or a certain status, to present groups of specific object types. Therefore, it is likely that a customizing may require hardcoded filter criteria, combined with user input, if any is provided.

The following describes how to implement such a scenario in XAML, again using [[:Category:Multiple Dynamic (User Inputs) Criteria]] as a starting point.

<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

Once one or multiple EvalExpressions have been added to process each input (such as Name_FilterExpression, Desc_FilterExpression), the remaining predefined filter criteria, in this example, filtering for a specific MetaClass by UID, can be added as an x:String, or directly in the EvalExpression paramerter, though the first approach is recommended, for better readability.

{{Attention|The above syntax only works for individual static string filters. If you need to chain multiple hardcoded filters, such as filtering in several UIDs, they need one String resource each, and must be added to the FilterExpression expression individually as in the below example.}}

=== Multiple Static Criteria ===
Experimentation has shown that the dynamic filter struggles to combine a single string made of multiple expressions, with additional expressions via the FilterExpression. However, it is still possible to combine user inputs and multiple static criteria, simply by breaking up the static criteria into separate strings.

Of course, when for example filtering various MetaDefinitions.UIDs, the '&' (and) comparison condition is no longer appropriate, as there will never be matches for multiple of these UIDs that returns a true result. In these cases, the comparison condition needs to be set to '||' ([[HowTo:Implement_Custom_Filtering#.27Or.27_Operations|Or]]).
The below example shows the correct syntax.

<tabs>
<tab name="UWP">
<br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String></source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin"><br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>
</source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
{{Hint|Note that the above strings make use of the .Equals() method, which is an alternate option to the more commonly seen <nowiki>'Item.Content.MetaDefinition.UID.ToString().ToLower()==...</nowiki>'}}
<br><br>

== Other Property Types ==

=== Filtering an INT / Double ===
Though the string comparison works mostly the same for a Int / Dbl, you additionally have to include a .ToString() method to the EXP EvalExpressionParameter of that property's individual EvalExpression for it to evaluate:
<source lang = "xml">
ConverterParameter='Item.Values["INSTRUCTIONID"].ToString().ToLower().Contains("{0}".ToLower())==true'
</source>
<br>

=== Filtering a Boolean (CheckBox) ===
To process a Boolean filter, the expression needs to be slightly amended, due to the different type of filter match criteria that is required.

Note that the below implementation returns all items by default (ie. when the CheckBox is unchecked), and returns only True matches when the CheckBox is checked. This functionality is designed to align with string input, where no filtering occurs for each string until something is entered into the corresponding text input box.
<br>
<source lang = "xml">
Note that this example uses UWP xaml syntax:

<controls:EvalExpression x:Name="Bool_FilterExpression" Expression="(INPUT==false) ? "true==true" : EXP" Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=CheckBox, Path=IsChecked, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["MP_BOOL"]=="{0}"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=CheckBox, Path=IsChecked}" />
</controls:EvalExpression>
</source>
<br>

* The individual EvalExpression for a Boolean filter match needs to be amended as follows:
** The INPUT can never be null, as the IsChecked property is either True or False. Therefore we can remove the Null or empty test, and instead, check whether the CheckBox is checked or not. IsChecked=False should 'escape' the expression, and return all items (or, not contribute to the overall filtering).
* The EvalExpressionParameter 'EXP' similarly can be simplified, as it does not need to make a string match with .Contains, but simply check whether the property value matches to True or False.
<br>
Changes only need to be made to the individual EvalExpression. The "FilterExpression" that joins all individual expressions does not need to be amended, other than the regular additional EvalExpressionParameter, and updating the expression accordingly.

<br>

=== Filtering a GUID Property ===
The expression string seen in the "EXP" command parameters shown above compare a user input with the value stored in Values[MP_PROPERTY], of the requested property. However, in certain cases, it may not be adequate to search in Values[MP_PROPERTY], such as when the property is a GUID. This is because Values[LK_GUID_PROPERTY] returns the UID value of the linked object, whereas Properties.VisibleItems[LK_GUID_PROPERTY].DisplayValue returns the human readable label associated with this linked object.

The solution is to rewrite the expression string to target the correct binding:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

A good way to inspect and test the target binding is to output it on the items UI, therefore on the ItemTemplate of your ListView, as well as to output the expressions that are being dynamically generated in your EvalExpressions, by binding the Result to the Text property of a <TextBlock> (UWP) or <Label> (Xamarin).
<br>
<br>

{{UnderConstructionStart}}
=== Filtering a DateTime Property ===
Filtering a DateTime property is more complex than other properties, because one has to consider both the input, and the type of filtering.

Input can be done both as freetext, and using a DatePicker. Freetext input has the downside that users have to take care to enter the correct string format (ie. yyyy/MM/dd), whereas the DatePicker outputs a DateTime string which can then be formatted for use in the EvalExpression. The DatePicker does however have certain downsides, chief of which being that it is not nullable, the current date is shown when no date has been selected, making the non-filtered UI indistinguishable from the filtered one.

Filtering can be done as a simple comparison, such as finding an object whose date matches the inputted date. However, it is also possible to ranges; either 'open', that is, dates before or after the user's selection, or 'closed', which is a date falling inside a range created by two user inputs.

==== Input ====
The input method is the first important consideration for filtering DateTime properties. A DatePicker is the generally accepted method. Textbox input is also possible, though users will need to correctly format their input to 'yyyy/MM/dd' (such as "2032/12/31") in order to achieve a valid comparison.

'''DatePicker'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<DatePicker x:Name="DatePicker" Tag="{Binding SelectedDate, ElementName=DatePicker, Converter={StaticResource StringFormatConverter}, ConverterParameter='{0:yyyy/MM/dd}'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<DatePicker x:Name="DateInput" />
<Label x:Name="DateString" Text="{Binding Path=Date, Source={x:Reference DateInput}, StringFormat='{0:yyyy/MM/dd}'}"/>
</source>
</tab>

{{Attention|In both cases, it is necessary that the format of the input matches the format of the property value, which will be explained more in the Comparison section below. In the above examples, this is applied in the Tag property (UWP) or through use of a secondary control (a Label in the Xamarin example).}}
</tabs>

'''Freetext'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="DateInput" PlaceholderText="Date"/>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="DateInput" Placeholder="Date"/>
</source>
</tab>

{{Attention|Remember that no matches will be found unless the date is inputted following a 'yyyy/MM/dd' format.}}
</tabs>

{{Hint|For greater control over the input format, it is also possible to provide multiple TextBoxes, which could then either be concatenated in an EvalExpression, or used to filter by the DateTime.Day/Week/Month values of the property individually, if such functionality fits the usecase.}}

<br>

==== Comparison ====
Since the EvalExpression approach utilizes string comparisons, not only is it necessary to format the input string, but the property value must also be formatted to match. The 'yyyy/MM/dd' format includes several measures to create the best conditions for comparing the two strings;
* months and days below the value of 10 cannot be a single digit, but must be padded with a preceding 0 in order to keep the string lengths equivalent; 2032/1/1 cannot be property compared with 2032/12/31 for example, as the strings are different lengths.
* putting the year and month first also improves the chance of a correct comparison, as a day 01 can be after a day 31 if the month and year are greater.

{{Attention|For the rest of this section, a DatePicker input is assumed.}}

'''Single'''

Comparison of a single date against a property value works the same way as other dynamic filters. Therefore it is sufficient to make use of the previously used .Contains() or .Equals() methods.
Remember that the Date attribute is not directly usable from the DatePicker, and its formatted version received via the Tag attribute or an additional label is what is actually used by the EvalExpressions.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DatePicker, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DatePicker, Path=Tag}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Path=Text, Source={x:Reference DateString}, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Path=Text, Source={x:Reference DateString}}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

'''Range'''
<br>
It is also possible to filter not for a specific date, but rather for all items whose property falls after or before the user input (depending on whether a 'Starting From' or 'Ending By' comparison is implemented. An 'open' range filter is created when only one value is inputted by the user, whereas a 'closed' range has a start and end date, and must fall on or in between these two.

For range comparison, we use the [https://learn.microsoft.com/en-us/dotnet/api/system.string.compareto?view=net-9.0 Microsoft .CompareTo method]. As documented there, this method outputs a -1/0/1 depending on the compared string's location in the range. Our expression can target one output for an 'exclusive' filter (in which the inputted date is not considered for the range), however, a more likely scenario is that the user wants the inputted date included in the filter. This is why the expression in the StringFormatConverter should be defined for start date as !=-1, and for end date as !=1; the instance should be not less than than the start date (where true would be an output of 0 or 1), and not greater than the end date (true = -1 or 0), respectively.

Similar to the earlier section on [[HowTo:Implement_Custom_Filtering#Multiple_Dynamic_.28User_Inputs.29_Criteria|multiple inputs]], separate EvalExpressions are used for each half of the range, meaning that the filtering also works (as an 'open Range' filter) when only one value is inputted by the user. To implement only an open range filter, simply eliminate the second input and EvalExpression.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Start_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=StartInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=StartInput, Path=Tag}" />
</controls:EvalExpression>
<controls:EvalExpression x:Name="End_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=EndInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=EndInput, Path=Tag}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding ElementName=Start_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding ElementName=End_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Start_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference StartString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference StartString}, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Key="End_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference EndString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference EndString}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding Source={StaticResource Start_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding Source={StaticResource End_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note the .CompareTo method used in each half of the ranged filter expression; the start date comparison is <noWiki>!=-1</noWiki>, whereas the end date comparison <noWiki>!=1</noWiki>.}}
</tabs>

==== Individual DateTime Components ====
The DateTime property has the additional benefit of exposing components that can be used to refine filtering.

[[Developer_Mode]] reveals the members available under the binding path; <source lang = "xml">PropertyItems["DATETIME"].Value</source>
These include; Date, Day, DayOfWeek, DayOfYear, Hour, Millisecond, Minute, Month, Ticks, TimeOfDay, and Year.

These can be used in the EvalExpressionParameter as a binding in the custom expression string, as follows, and can even be used in separate filters to search individual components of the date seperately (for example, to filter by a particular month, year, or even day of the week).
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DateInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().Contains("{0}".ToLower())==true'}" />
</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DayWeekInputString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

<br>
<br>

==== Troubleshooting ====
If no match is found when one is expected, it's possible that localization is affecting the ToString evaluation of the object's DateTime property. The StringFormatConverter used in the Start/End_FilterExpression hardcodes a search string (in this case yyyy/MM/dd with '/' as seperators). To check that that the matched strings coming from the datepickers and property values are exactly the same, output both to the UI and ensure that everything about them is the same, including order of year-month-day elements, dividing symbols, etc.

{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Adjustments ==
=== 'Or' Operations ===
All examples of multiple inputs in this article use an 'and' filter condition, where, if any inputs are entered, only items that match all inputs (NAME <b>and</b> DESC) are kept in the collection, to produce a 'filtering down' effect in the user interface.

If a less strict filter condition is required, the FilterExpression can be altered to have an 'or' condition, where all results that match NAME <b>or</b> DESC, but not necessarily both, are shown. To do so, simply change the concatenation syntax to return 'or' symbols (two pipes or '||'):
<source lang = "xml">
+"||"+
</source>

== Displaying a Count ==
To display the filtered count, use the following syntax:

<source lang = "xml">
"{Binding Path=Count, Source={StaticResource FilterView}}"
</source>

== Persisting Filter Values ==
{{UnderConstructionStart}}
One of the drawbacks of this method of filtering is the inability for the UI to 'remember' user inputs when they navigate away from the page. This is because this implementation of dynamic filters exists solely on the UI thread (that is, is defined in XAML only with no actual connection to the data, opposite to [[Property_Based_Content_Filters]], for example), which is re-rendered according to the xaml definition every time the page is loaded. This section describes how to implement a limited solution to this issue, the limitation being that values can currently only be persisted during the 'session', and are lost when the user closes the client.

This solution involves use of the StoreProfileParameterCommand to create key-value pairs (a simple list of items made up of a name and a value), which can then be read using the 'StoredProfileParameters[key]'. The StoreProfileParameterCommand accepts a CommandParameter with the format 'key=value', where 'key' represents the name of the key-value pair that can be used to reference it later (in the case below, "name"), and 'value' represents what string should be returned by referencing it (in this case, the Text attribute of the text field control).

When a user completes their input, we use the StoreProfileParameterCommand to create or update a key-value pair associated with a particular filter, instead of passively reading the value from the input as was done previously.

Furthermore, the associated StoredProfileParameter is fed back to the input control so that if any value is set for that particular key (ie. if a filter value has been created), it will be displayed on the input control. Otherwise, the input control will be reset when next loading the page, as was previously the case with dynamic filtering, whereas the StoredProfileParameter will be persisted, leading to a mismatch between the UI and filtering state.
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<interactivity:Interaction.Behaviors>
<core:EventTriggerBehavior EventName="LostFocus">
<core:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Text, ElementName=NameInput, Converter={StaticResource StringFormatConverter}, ConverterParameter='name={0}'}" />
</core:EventTriggerBehavior>
</interactivity:Interaction.Behaviors>
</TextBox>
</source>

Pay attention to which [https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.textbox?view=winrt-26100#events Event] is used to trigger the StoreProfileParameterCommand. The above example uses LostFocus, which fires when the user clicks out of the TextBox. Another possible choice is TextChanged, however, this means that the command will fire with every keystroke, which may reduce overall performance.
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<Entry.Behaviors>
<behaviors:EventHandlerBehavior EventName="Completed">
<behaviors:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Path=Text, Source={x:Reference NameInput}, StringFormat='name={0}'}" />
</behaviors:EventHandlerBehavior>
</Entry.Behaviors>
</Entry>
</source>

The Xamarin 'Completed' event fires when the user clicks the return button on their onscreen keyboard.
</tab>
{{Hint|StringFormatConverter/StringFormat is used to format the key-value pair as required by the StoreProfileParameterCommand. The key is hardcoded into the formatted string as, for example <noWiki>'name={0}'</noWiki>. The dynamic value, in this case whatever is inputted in the text field when the edit is completed, replaces the <noWiki>{0}</noWiki> tag when the binding is evaluated (ie. when the command is executed).}}
</tabs>

In this implementation, the EvalExpression also needs to be adapted to check whether a particular filter value exists within the StoredProfileParameters list, instead of simply whether the associated input control has a value or selection:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["NAME"].ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["NAME"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note how the EvalExpressionParameters have been adapted to reference a StoredProfileParameter, rather than the input control.}}
</tabs>

=== Item Selection ===
Filter value persistence works also when the user input method is to select an item from a picker.

<tabs>
<tab name="Xamarin">
<source lang = "xml">
<controls:PickerExt
x:Name="ExamplePicker"
ItemsSource="{Binding Children.Items[0].PropertyItems[PROPERTY].MetaProperty.SelectiveList, Converter={StaticResource SelectiveListToItems}, TargetNullValue='', FallbackValue=''}"
ItemDisplayBinding="{Binding DisplayText}"
SelectedValuePath="Value"
SelectedValue="{Binding StoredProfileParameters[key]}"
SelectionChangedCommand="{Binding StoreProfileParameterCommand}"
SelectionChangedCommandParameter="{Binding SelectedItem.Value, Source={x:Reference ExamplePicker}, StringFormat='key={0}'}"/>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Known Issues ==
=== Text Input in ListView Header Template ===
This implementation will not work when parts of it, such as the Input fields, are hosted in a ListView header or footer template, as this content is not readable by the rest of the page and will return a "Can not find the object referenced" parsing error.

To workaround this, you need to move the Input control out of the header template.

=== Troubleshooting ===
* Everything looks correct but filtering returns no results:
** Ensure that the string you are trying to filter by matches what is returned as the DisplayValue.
** If the property is a INT / DBL (Integer or Double) type: The string comparison doesn't work directly with non-string types. Check the [[HowTo:Implement_Custom_Filtering#Other_Property_Types|Other Property Types]] section.
** If filtering a DateTime property, ensure the formatting of the input matches that of the property value in the EXP string.
** If filtering a GUID property, ensure the same values are compared; DisplayString if the user is inputting readable text, UID if the user has selected an item from a list.

== See also ==
* [[XAML]]
* [[XAML_Tips]]
* [[Xamarin_XAML]]

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

XAML Best practices

2025-08-18T12:14:25Z

REP: /* Context Switching And Templates */ restructured and added UWP example

{{UnderConstructionStart}}
<br><br>
This article recommends approaches to customizing and troubleshooting your UBIK custom UIs.
To learn about the fundamentals of XAML, check out our article [[XAML_Basics]].

The most important specific Best Practices are marked with a 🏆
<br>
== Conventions ==
Conventions are ‘rules’ that make our xamls collectively readable and shareable. By aiming to construct our xaml files in a similar style, we reduce the effort required by others to read and understand our work. This section includes guidelines on how to name controls, and how to internally organize your xaml files.

=== Naming Conventions ===
<Button x:Name="SubmitFormButton" ... />

* The x:Name is used to give a unique name for an object within a xaml file. It’s not valid in a ResourceDirectory (such as a style, template, etc, either defined within a xaml file, or in UBIKThemes), which requires using x:Key instead.
** Likewise there is a difference when referencing x:Name and x:Key elements.
<nowiki>x:Name - UWP: ElementName=SubmitFormButton | Xamarin: Source={x:Reference SubmitFormButton}
x:Key - Both: {StaticResource SubmitFormButtonStyle} or {DynamicResource SubmitFormButtonStyle}</nowiki>
* Use explicit language when giving a name or key, for example: “PropStkpnl” is not easily readable, but “PropertiesStackPanel” is.
* Furthermore, “FailureCodeExpression” does not describe the purpose of the expression, whereas “FailureCode_HasUnfilledFields” does.
** Naming it according to its purpose also makes it easier to use in xaml, such as when combining the result with a converter for an intended outcome (eg. An warning symbol visible when FailureCode_HasUnfilledFields is true).
* You '''do not''' have to name every object in your code, only if it is referred to by another element. However, sometimes adding names to controls helps a reader understand their intended function.
<br>

=== Formatting ===

Formatting xamls properly is critical to others being able to quickly read and understand a customizing.
{{Hint|If you struggle to maintain nice formatting while writing your xaml code, you can find formatters that automatically such as Notepad++’s “Pretty Print” or VS Code’s “XAML Styler” plugins.}}

==== Best Practices ====

* x: Name or x: Key should come first.
* A control with up to 2 Attributes can be added in one line. If it has more than 2, they should be stacked over another for readability.
** Avoid using a formatter where the indentation matches the name of the control
[[File:Formatting_Indentation.jpg]]

* Add controls in a Top-to-Bottom order in the xaml file. Additionally, try to add them in a Left-to-Right order.
** Controls in Grid.Row/Column 0 should be higher up in your xaml file than controls placed in other rows and columns.

* Respect indentation of nested controls.
** Opening and closing tags should always begin in the same column.
** Controls nested inside them should begin exactly one column to the right.
** When pasting code snippets into your work, be sure to correct the differences in indentations.

* Use Linebreaks mindfully.
** It is difficult to describe rules for how linebreaks should be used, but the general idea is to use them to group elements in your xaml file, and to show which controls are nested (no linebreaks) and which controls are 'siblings' (divided by linebreaks).
** ✔️Put linebreaks in between large sections of a UI definition (eg. between Grids or major elements of the page, or between content set on different Rows/Columns).
** ❌ Avoid linebreaks in the middle of smaller elements (eg. a stackpanel with 2 texts inside).

* 🏆 '''Add comments.'''
** This is one of the most critical features of clear code, saving the reader from wasting time struggling to read the code, or even having to search and ask around.
** Use comments to describe the position, purpose, and function of every control.
** When maintain xamls according to a ticket, put the ticket number in a comment so a reader has access to background information on the change.
[[File:Formatting_Comments.jpg]].

* Remove unnecessary code. Ensure everything included in your xaml has a purpose. This includes large sections of commented out code.
** This both makes the xaml clearer, but also improves performance by avoiding unnecessary loading and rendering effort.
** This is especially true when copying from other’s work.
** If you’re not sure if something is necessary, comment it out and see if your xaml still fulfils its function. If it works, remove it.
** [[XAML_Best_practices#Performance | Read more in the next section on Performance]].

* 🏆 '''Empty out your UBIKThemes''' for every new customizing.
** When working in Xamarin, it is recommended to empty out your UBIKThemes file (ie. delete everything between the <ResourceDictionary> tags) and only add what you intend to customize.
** Unfortunately, this approach is currently not 100% possible in UWP xamls, as we noticed that custom styles are not utilized on controls unless the controls are also in UBIKThemes, shown instead using the standard grey/orange. However, diligent customizers can find out how to do so below: <div class="toccolours mw-collapsible mw-collapsed" data-expandtext="Read More" data-collapsetext="Close"> An issue with dynamically refreshing style resources causes emptying of UBIKThemes to be much more complicated on UWP than in Xamarin.<br>This is because StaticResources are only updated once they are overwritten again in Themes. The most common symptom of this issue is that for example, if UBIKAccentColor is changed to blue, this customization will not be reflected by styles for any control defined in UBIKThemes, unless the styles are 'written' again in UBIKThemes. So in this example, the regular button hover state will remain orange, unless UBIKButtonStyle is included in the UBIKThemes of that project.<br>Therefore, the only approach we can recommend is to remove everything from UBIKThemes, and add styles back once they fail to reflect the customized color resources. Since this approach is impractical, we do not encourage emptying UBIKThemes for UPW as strongly as we do for Xamarin.
</div>

* Organize UBIKThemes in sections.
** For example, standard UBIKThemes defines resources grouped into; Color resource / Size resources / Text styles / Button styles / etc
** In Xamarin, keep Item Templates at the end of UBIKThemes.
** Either way, it is recommended to keep your UBIKThemes file as lean as possible (read the next point), as well as maintaining a grouping strategy. Use the tags <nowiki></nowiki> and <nowiki></nowiki> to define groups of content, for example
<nowiki>, , or </nowiki>.
<br><br>

== Performance ==
A basic rule is that '''more code = more to compile''', and this can decrease the performance of your whole application. To counter that, always attempt to reduce the amount of xaml customizing, especially if you find yourself repeating specific controls and attributes.

=== Understanding Templating in UBIK ===
The most critical thing to understand about customizing your UI is that '''templates for the entire default UI are already present in the client’s core'''. Customizing templates allow us to modify of specific areas of the UI by overwriting the parts of the default UI with the same name. Therefore, only the specific xamls that need to be customized should be added. This is recommended for many reasons;

* Custom xamls will ‘undo’ improvements to the UI coming from newer versions of the client, when they are based on xaml files from an older version of UBIK. For custom UIs there is no way around it, but this is why '''uncustomized copies of xamls should never be added to the project folder'''. To remove a customizing, simply delete that file. There is no need to replace it with an uncustomized version from the default folder.
* Less xaml files to parse means better performance.
* More xamls also makes it more difficult for others to read and understand the customizing. This also makes it much more difficult to find and diagnose errors when requesting support. It also generally increases the effort required to maintain the xamls.
<br>

Check out the next section for a more in-depth look into [[XAML_Best_practices#Templating|Content Templating]].

==== Best Practices ====
* 🏆 '''Deploy a new Default folder''' every time you update your client version, to ensure that the latest UI version is the foundation for your customizing.
* 🏆 '''Only include xamls that are needed for your customizing.'''
** Remove files for child Areas and Items that are not included in the project this customizing will be used for. This is especially relevant when copying customizings from other projects.

=== How to select the right Control ===
Controls often have similar functionality, making the question of which control to use highly ambiguous.
For clarity, a 'Control' refers to a single xaml object that can be added to your visual tree. These range in scope and purpose, from layouting (such as a Grid or StackPanel), to interactivity (such as a Button or TextBox), and everything in between (such as a ListView).

So, how to choose the best control to meet your requirements?

==== Best Practices ====
* 🏆 A good rule of thumb is to '''always use the least complex control possible'''.
** For example, there is no need to use a Filter + ListView to show a single UBIK object or property. Instead, you can bind the specific context of that object or property to a xaml control, and everything nested inside will inherit that binding context. This will be explained more in the section on [[XAML_Best_practices#Reusable_Templates|Reusable Templates]].
** Similarly, simple EvalExpressions can in many cases be replaced with [[XAML_Best_practices#Converters|Converters]].
** The Visibility attribute can be added to any control. '''There is no need to wrap any control in a Grid simply to apply a Visibility.''' The same goes for layouting attributes such as Grid.Row/Column.
* 🏆 When you need to show a collection of items such as ListView, '''always use our custom versions'''. These are UBIK-optimized for speed and performance.
** These are [[XAML_Tips#Version_3.7_.26_later|SelectionBoundListView]] on UWP and [[Xamarin_XAML#SfListViewExt|SfListViewExt]] on Xamarin.
** Avoid using other item controls, or BindableLayouts, unless you are sure the performance impact will be negligible.
* Layouts:
** If you want to define a specific layout for a page, use a Grid with rows and columns.
** If things need to be positioned relative to each other, use a StackPanel/StackLayout.
** When defining Rows/Columns for a Grid, assign as few Auto size as possible, and avoid putting controls of unlimited size in an Auto Row.
** 🏆 '''Never nest controls of unrestricted size within controls of unlimited size.'''
*** To clarify: Some controls resize themselves based on their content and can be of unlimited size. One example is a StackPanel/StackLayout, when compared to a Grid, which is limited to the screen's size. On the other hand, some controls have an unrestricted size, such as ListView, ScrollView, etc.
*** Furthermore: ListViews require a fixed size in order to preserve [[XAML_Best_practices#Virtualization|virtualization]].
* Do not nest ScrollViews within other ScrollViews.
** Note that this includes '''any''' control with scrolling behavior, as these include a hidden built-in ScrollView. For example, never place a ListView or TreeView within a ScrollView.
* Nested ListViews involves using a ListView on the item template of an object already presented in a collection. For example, showing the children of a child object.
** This is especially an issue in Xamarin, both for performance, but also because sfListViewExt tends to cause layouting issues by taking up more space than needed, unlike in UWP where a ListViewExt is capable of calculating its size based on the size of its items. Therefore, when using nested ListViews in Xamarin, constrain the size of the inner ListView with a fixed HeightRequest attribute (or WidthRequest in the case of a horizontal list).
** 🏆 '''Alternatives to the optimized ListViews should be used with extreme caution.''' Controls such as CollectionView or BindableLayout are not optimized for good performance in UBIK.

=== Using Styles and Templates ===
Attributes are the properties used to customize the controls in a UI. The number of attributes on each control can also contribute to having 'too much' code. Reducing the number of attributes will improve the overall performance of a customizing, especially on elements that appear multiple times in the UI,s such as items in a list.

[[XAML_Best_practices#Templating|Custom templates]] can be used with the additional benefits of defining a uniform look for all similar elements, and reducing customizing effort by creating a central point where a reusable template can be maintained.

==== Best Practices ====
* Do not re-define default attributes.
** All attributes have a default value. For example, Grid.Row="0" is always true, unless specified. Use the Microsoft documentation to familiarize yourself with the default value for every property, and avoid rewriting them.
** If your control inherits an attribute from its style, do not rewrite the same attribute again.
*** If you find yourself adding the same attributes to a control with a style, consider moving the attribute to the style definition, or creating a substyle.
* Avoid repeatedly applying Margins to individual controls.
** The main layouting should not be done through Margins. Instead, try to use a combination of Grid.Row/Column definitions and Horizontal/Vertical alignments to create your layout, instead of applying many or very large Margins.
** For example, if you want to move every control within your Grid away from the edge, use a Padding on the Grid instead of Margins on each of the elements.
** If you want to move controls away from each other within the same container, use RowSpacing or ColumnSpacing on the Grid, or Spacing on the Stackpanel.
* 🏆 If you repeatedly define the same attributes on a control, '''create a style'''.
** If the repeated customizing is used in only one xaml, create a ResourceDictionary on the parent container and defining your style there.
** Otherwise, place your style in UBIKThemes so it can be accessed across the entire project.
** '''For more information, read the section on [[XAML_Best_practices#Implicit_and_Explicit_Styling|Implicit and Explicit Styling]] below.'''
* 🏆 If you repeatedly define the same combinations of controls, '''use Control/DataTemplates'''.
** DataTemplates and ControlTemplates are reusable XAML elements that can be defined once and applied several times throughout the customizing.
** You may have noticed that a DataTemplate is the basis for an item template in UBIKThemes. However, these can be applied anywhere in the xaml, and do not require a ListView to be rendered.
** '''For more information, read the section on [[XAML_Best_practices#Templating|Content Templating]] below.'''
* 🏆 '''Reduce the number of elements, especially containers''', wherever possible.
** Layouts are often defined in multiple nested containers, usually Grids and StackPanels. This has an impact on performance if it leads to a very deep hierarchy of rendered elements. On mobile devices with less computational power, the difference can be felt.
** Creative use of basic controls can sometimes eliminate the need for additional visual elements.
** Frequent use of Grids or Stackpanels can sometimes be replaced with clever use of Grid.Row/Column definitions.
* Layout Compression:
** Sometimes it’s unavoidable that multiple containers are needed. In Xamarin, applying the [[Xamarin_XAML#Layout_compression_examples|HeadlessLayout]] style can reduce their impact on the visual tree.
** Some ideas for reducing the number of nested controls can be seen [[XAML_Best_practices#Alternatives_to_using_Multiple_Controls|later in this article]].

==== Implicit and Explicit Styling ====
A Style is a collection of preset attributes that can be assigned to a XAML control of the same type.
When this is done directly, by adding the Style attribute to a control, it is called Explicit Styling.
However, styles can also be made Implicit, by not assigning an x:Key, making it a default style. Whether it is the default style for a localized section of a XAML, or the entire project, depends on where the Implicit style is defined.

The following code snippet makes use of several features of XAML Styling:
[[File:Performance_ImplicitStyling.jpg]]

* The above is an example of a localized ResourceDictionary used to avoid repeatedly customizing similar controls.
* By not assigning an x:Key to the style in the Grid.Resources, it will be used as the Implicit style for all Labels within that StackPanel unless a Style is assigned to them.
** All Labels within the StackPanel will inherit the defined style, except for "The result is:", which is given an explicit style, overriding the inherited implicit one.
** If no Explicit style is assigned, the Implicit style will be assigned first, and will be overwritten by any defined attributes, like TextColor in the above example.
* The localized Style definitions in this StackPanel will be passed down to all controls contained within it, no matter how deep the nesting goes.
* The BasedOn attribute can be used to create a sub-style based on another existing style. However, the TargetType must always match.

=== Simplifying Layouts ===
In UWP / on desktop UBIK, the processor is generally powerful enough to handle more complex UIs. However, mobile devices running Xamarin versions of UBIK will noticeably struggle to render sophisticated UIs made of deeply nested levels of containers. There are two ways this situation can be improved; the first is to reduce the number of containers used, and the second is to apply [[Xamarin_XAML#Layout_compression_examples|Layout Compression]] wherever possible. Finally, some ideas will be presented for other ways to reduce the number of controls needed to render the same UI.

==== Reducing Containers ====
Containers refers to controls whose purpose is to display other controls. The most basic examples are the Grid and StackLayout. These containers are frequently nested in order to finetune a UI, however, the downside is that each one adds a new branch in what is called a "visual tree', even if the control itself is not visible. When using many containers, it is useful to ask yourself if each container is really necessary, or if the visual tree can be simplified.

The examples below show three different ways for showing the same content, each utilizing less controls, leading to a simpler visual tree.

<tabs>
<tab name="2 StackLayouts, 3 Labels">
<source lang = "xml">
<StackLayout>
<StackLayout Orientation="Horizontal">
<Label Text="{x:Static resources:UBIKIcons.IconName}" FontFamily="{StaticResource UBIKSymbols}"/>
<Label Text="Name" />
</StackLayout>

<Label Text="Description" />
</StackLayout>
</source>
</tab>

<tab name="1 Grid, 3 Labels">
<source lang = "xml">

<Grid Grid.ColumnDefinitions="24,*" Grid.RowDefinitions="Auto,Auto">
<Label Text="{x:Static resources:UBIKIcons.IconName}" FontFamily="{StaticResource UBIKSymbols}"/>
<Label Grid.Column="1" Text="Name" />
<Label
Grid.Row="1"
Grid.ColumnSpan="2"
Text="Description lorem ipsum..." />
</Grid>
</source>
</tab>

<tab name="1 Label">
<source lang = "xml">
<Label>
<Label.FormattedString>
<FormattedText>
<Span FontFamily="{StaticResource UBIKSymbols}" Text="{x:Static resources:UBIKIcons.IconName}" />
<Span Text="Name & #10;" />
<Span Text="Description lorem ipsum..." />
</FormattedText>
</Label.FormattedString>
</Label>
</source>
</tab>

Note: & #10; (without the blank space) is the Xamarin glyph code for a newline. The equivalent in UWP is & #x0a;.
</tabs>

Now imagine the UI element should have a colored background. You may be tempted to wrap everything in a Frame, however, you can just as easily assign color using the Background attribute on the StackLayout, Grid, or even the Label itself.

Granted, this example is very simple, however, the point illustrated here is that you should fid creative ways to reduce the number of controls nested in your UI.

Another thing to consider is how many times this particular UI definition will be rendered on screen. You have more freedom to be uneconomical in your use of controls when when designing items that will appear once on a page, such as the page header, rather than with item templates or control templates that are rendered several, or even dozens, of times in one view.

==== Layout Compression ====

==== Alternatives to using Multiple Controls ====

=== Performance analysis (MAUI only) ===
In the MAUI app, {{UBIK}} provides customizers a possibility to analyze the performance of specific UI elements by measuring the time it takes to render them. This can help customizers find performance weak spots in the entire UI and also serve as a benchmarking tool to verify the result of any improvement attempts.
The measurement is achieved through the use of the MeasurePerformanceBehavior. The concept of it is very similar to other behaviors, namely you attach it to any UI element in the XAML code (as long as it's a derivate of the [https://learn.microsoft.com/en-us/dotnet/api/microsoft.maui.controls.visualelement?view=net-maui-9.0 VisualElement], which should cover the vast majority of all UI element types).
* The behavior measures the time to render the UI element (which it attaches to) as well as its child elements (recursively if any).
* You can attach multiple behaviors to multiple UI elements at the same time, one to each, in order to get the measurements of the different elements.
* The measurements are logged in the UBIKDebug.log file under the app's Logs folder.
* You can and should assign a unique name to the Label property of the behavior, so that it's easy to identify the render time of the target element.

The following is an example of attaching the behavior to the root Grid inside the UBIKChildItem template. It should effectively measure the time to render the UI for a child item.

<tabs>
<tab name="MAUI">
<br/>
Namespace referenced in the code: <code>xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"</code>
<source lang = "xml">
<Grid>
<Grid.Behaviors>
<behaviors:MeasurePerformanceBehavior Label="UBIKChildItemRootGrid" />
</Grid.Behaviors>
...
</Grid>
</source>
</tab>
</tabs>

With this, you should see log entries such as the following, one for every child item that you see when opening a content page.

<pre>2025.07.15 12:12:18:1030 Debug Sender: MeasurePerformanceBehavior Message:'Rendering Microsoft.Maui.Controls.Grid UBIKChildItemRootGrid took 8.4889 ms'</pre>

[[Category:Pages with broken file links|XAML Best practices]]
[[Category:XAML|XAML Best practices]]

== Templating ==
Similar to styling single controls, presets featuring groups of controls can also be defined in UBIKThemes and used anywhere in the client. The benefit of this

One simple example of this is an ItemTemplate. Project customizers should be familiar with ItemTemplates, which are defined in UBIKThemes and then applied to every item in a List, for example. However, such templates are not inherently connected to listviews, and can be used on any items control, or can even on their own, if the situation calls for it. The important thing to understand is that a content template is a standalone unit, defined in xaml to display particular data bindings, and perhaps react to various states.
<br>
{{Hint|Look at other interesting templates in UBIKThemes, such as "Badge" / "ChildCountBadge" in Xamarin, or "UBIKObjectIndicators" in UWP to see more ideas for how templates can be utilized.}}

=== Template Selectors ===
Various parts of the UBIK UI are dynamically swapped in based on specific conditions. One example is the UBIKPropertyDirectItemContainer.xaml, which serves as the base for an item in the property list, and which renders a different type-appropriate editing UI for each kind of property input (such as TextBox for manual input String, Double, or Integer; selection for link properties, or list-based String, Double, or Integer; clock and calendar pickers for DateTime; Lat., Lon., and Alt. input for geo coordinates, etc).

The logical tree used by these selectors to render different UIs is documented in our article [[UBIK_Templates]].

=== DataTemplate vs. ControlTemplate in Xamarin ===
There are two main types of templates that can be used in UBIK to define reusable clusters of controls. Ignoring the technical differences, the functional differences boil down to;
==== DataTemplate ====
DataTemplate is used for showing / interacting with various aspects of a data binding.
* Example 1: Consider a Child ItemTemplate, which is capable of displaying metadata like Title or SubTitle, MetaProperty collections, Classifications, Children and Documents. In this case, the '''context''' for the item template is one object, and we can bind to any of its data.
* Example 2: Consider a Property ItemTemplate, where we can view or edit a metaproperty. In this case, the '''context''' of the ItemTemplate would be a single property, and the bindings available would reflect that; we can bind to its Description, Value, DisplayString, Unit, or even its SortedValueRecords, if property change history is activated.
* Use a '''ContentControl''' or our custom '''controls:ContentControl''' (with the attribute ContentTemplate="{DynamicResource ...}" and TemplateContext="{Binding ...}") to display it.

==== ControlTemplate ====
ControlTemplate is technically used for showing how a specific control can be used; for example, if you want to customize a new template for how a Button should appear. However, it can be used similar to the DataTemplate, with one added bonus; its ContentPresenter sub-control allows for dynamically adding content at every instance, as opposed to a single universal layout that is shared by all.
* For example: The screenshot below shows three areas navigated to by clicking on root objects. Each has a potentially large collection of their own metaclass of children, meaning that each page benefits from filters, but they do not filter the same properties. However, some details are common, such as the item and filter count texts, and the button to remove all filters.
[[File:Templating_ControlTemplate.jpg]]
* The general layout could be created with two columns, one for the counts and button, with the rest of the space dedicated to the individual filters. The template would then be applied one in each of the child areas, with their specific filters nested inside the ContentView used to display the filter.
* During runtime, the <ContentPresenter /> defined in the ControlTemplate will be replaced with whatever content is nested in the ContentView.
* Note that implicit styles can also be added to the ControlTemplate, and will be inherited by any content nested in the ContentView.
* Use a '''ContentView''' (with the attribute ControlTemplate="{DynamicResource ...}") to display it.

{{Attention|Since the ControlTemplate is not technically designed to work directly with data bindings, it does inherit the context from its ContentView by default. However this can be easily fixed by adding the <nowiki>BindingContext="{TemplateBinding BindingContext}"</nowiki> attribute to the root grid of the template.}}

{{Hint|An understanding of '''Contexts''' is fundamental to using templates, as this informs what data bindings are directly available. Some more information can be found at this article on [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#The_ContentViewModel.28s.29|the ContentViewModel]] }}

=== ControlTemplate in UWP ===
The situation is much simpler in UWP, which only makes use of the ControlTemplate to define custom templates. The ControlTemplate in UWP inherits the context from its content control, so no equivalent to Xamarin's <nowiki>BindingContext="{TemplateBinding BindingContext}"</nowiki> is required.

The ContentControl is used to render an instance of a template.

=== Contexts and Context Switching ===
In xaml, every element in the UI is informed by a '''context'''. This is the data that is delivered by UBIK immediately when binding. Knowing the context that will be used by a content control is vital when using templates, as this directly affects what bindings you can prepare in your template. Furthermore, all content views that use the same template must have similar contexts, to a degree.

For example:
Two of the more frequently customized elements are Objects and their Metaproperties. A template used for a UBIK object will have bindings such as Title, Values[PROPERTY], etc, whereas one designed for a Metaproperty will have DisplayValue, Description, Unit, and so on. Using a template designed for a UBIK object will have no benefit if the context applied to it is that of a property, and vice versa.

==== Where does the context come from? ====
Context is inherited. When you begin customizing a xaml template, it generally has a known use, such as a child area, document viewer, or item in a property list, to name just a few of many. In these cases, the context is quite clear. However, when you begin creating general templates that can be used anywhere in the client, there will likely be the need to specify what context should be applied each time the template is used.

[[Image:XBP_ContentTemplates.png]]

In the above example, we see a variety of property editing fields. To cut down on repetitive XAMLing, a template is created for inputting a single property, consisting in this case of Description, DisplayValue, a placeholder label, and some indicators such as whether the property is required or filled. In each case, the context needs to be set to a specific metaproperty defined on the 'controls:ContentControl' that hosts each instance of the template, through the TemplateContext attribute.

<source lang = "xml">
<controls:ContentControl
ContentTemplate="{DynamicResource PropertyField_Required}"
TemplateContext="{Binding Properties.VisibleItems[MP_DETECTION]}" >
<controls:ContentControl.GestureRecognizers>
<TapGestureRecognizer Command="{Binding Properties.VisibleItems[MP_DETECTION].PropertyClickedCommand}"/>
</controls:ContentControl.GestureRecognizers>
</controls:ContentControl>
</source>

{{Hint|Adding the behavior to the ContentControl, rather than defining it in the template itself, allows flexibility in the customizing as different property-editing commands can be paired with the same UI based on the required functionality.}}

==== Context Switching ====
To repeat, context is almost always inherited. If you forget to assign a specific context to a content control (as in the above example), the context of the XAML element that hosts that content control will be used. When you think about it, any number of nested Grids still inherit the context of the area or item template they are hosted in.

Context-switching is simply the name given to the act of assigning a different context to a particular control, when needed. It is also usually very simple to do:

'''UWP'''
<source lang = "xml">
DataContext="{Binding ...}"
</source>
<br>
'''Xamarin'''
<source lang = "xml">
BindingContext="{Binding ...}"
</source>
<br>
The above attributes can be added to any control to change it's binding context.

Try this experiment:
<source lang = "xml">
<TextBlock
DataContext="{Binding ParentLevel}"
Text="{Binding Title}" />
</source>

By using this code snippet, we expect to see the Title or the current object. However, because we have a context switch applied, we would instead see the Title of the parent object. For Xamarin use '''Label''' instead of TextBlock and '''BindingContext''' instead of DataContext.

{{Attention|Using this technique to switch the context of a control does it for ''all bindings on that control''. Since the entire control is now 'focused' directly on a different context, existing bindings will need to be adapted. An easy example is the Visibility of the TextBlock, which we might still want to bind to certain conditions on the child object, while displaying the data of the parent.

One exception is the controls:ContentControl, which through its TemplateContext attribute accepts the possibility to have a different context for its content, therefore decoupling the context of the template from the actual control, [[XAML_Best_practices#Context_Switching_And_Templates|as described below]].}}

Furthermore, since context continues to be inherited, any controls contained within the context-switched one (imagine it's a Grid containing more elements, rather than a simple TextBlock) will all also have the context of ParentLevel.

==== Context Switching And Templates ====

===== '''DataTemplate''' =====
As described in the previous section, DataTemplates are designed to be used as templates for data contexts, therefore the content control used to render them, controls:ContentControl, has the TemplateContext property which allows you to set the binding context '''for the template'''. The important difference to note is that the controls:ContentControl itself will not use the TemplateContext, but rather the inherited context from its hosting xaml.

Because they are independent of each other, it allows more sophisticated usage of binding contexts, for example, when ''Object A'' has ''Status B'', show ''Property C''.

<tabs>
<tab name="UWP">
<source lang = "xml">
<ContentControl (displayed on child area of Object A)
Visibility="{Binding Values[STATUS], Converter={StaticResource EqualToVisConverter}, ConverterParameter=B}"
Content="{Binding PropertyItems[PROPERTYC]}"
ContentTemplate="{StaticResource MyPropertyTemplate}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:ContentControl (displayed on child area of Object A)
IsVisible="{Binding Values[STATUS], Converter={StaticResource EqualityToBool}, ConverterParameter=B}"
TemplateContext="{Binding PropertyItems[PROPERTYC]}"
ContentTemplate="{StaticResource MyPropertyTemplate}" />
</source>
</tab>
</tabs>

===== '''ControlTemplate''' =====
On the other hand, since the ControlTemplate is not designed to be used this way, it has no inherent binding context attribute that can be assigned to it's content only. The only benefit of using a ControlTemplate over a DataTemplate is the possibility to nest dynamic content (that has not been defined in the original ControlTemplate) within in, by use of the <nowiki><ContentPresenter... /></nowiki> attribute.

To use it this way would therefore require a context switch on the ContentView used to render it, with the related adjustments required to bindings placed on the ContentView itself;

<tabs>
<tab name="UWP">
No example yet.
</tab>

<tab name="Xamarin">
<source lang = "xml">
<ContentView (displayed on child area of Object A)
BindingContext="{Binding PropertyItems[PROPERTYC]}"
IsVisible="{Binding CallingViewModel.Values[STATUS], Converter={StaticResource EqualityToBool}, ConverterParameter=B}"
ControlTemplate="{StaticResource MyOtherPropertyTemplate}" />
</source>
</tab>
</tabs>

{{Hint|CallingViewModel (as used on the IsVisible attribute) can be added to a metaproperty's binding path to bind to its context object.}}

{{Attention|Remember that Styling in Xaml is type-based, so you cannot use the same template with controls:ContentControl (ContentTemplate attribute) and ContentView (ControlTemplate attribute), as DataTemplate and ControlTemplate are technically different types.}}

{{UnderConstructionEnd}}

[[Category:Pages with broken file links|XAML Best practices]]
[[Category:XAML|XAML Best practices]]

== Performance ==
Diminishing the performance should not be the first priority but it also shouldn’t be the last. You should always think about retaining readability and consistency in your code by adding comments and using clear and significant code. But you also have to keep in mind that more code and lines mean more compiling, this can decrease the performance of your whole application. Just try to keep a good balance between these two factors in order to ease the life of customizers. They’ll surely stumble across your code in a few months and will maybe have a hard time to finalize a ten-minute task because they have to find out what every piece of code exactly does. Here are some examples which support the increase of performance.<br>
For example:<br>
* If you use the same resource on more than one XAML file, consider defining it in UBIKThemes (Resources Folder -> LocalState/XAML) rather than on each page. <br>
* Don't define UI elements you don't need for composition and use the default control templates whenever possible (these templates have already been tested and verified for load performance). <br> <br>

Useful links for inefficient XAML code: <br>
* https://www.codemag.com/Article/1509091/XAML-Anti-Patterns-Layout-SNAFUs <br>
* https://docs.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-xaml-loading

=== Using 'NextLevel' bindings ===
Performance can be impacted by attempting to show multiple levels of data (ie. child data, from the parent object) outside what is delivered by UBIK by default.

For an in-depth explanation, and guidance on how to implement such functionality safely, please refer to this page [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel]].

== Testing of UI ==
XAML can be sometimes very weird, there are dependencies or default values that you don’t see immediately. So, a good way to prevent millions of fixes for the customer, because the environment, different device or even a different windows version destroys your UI, is to write a test plan where you test your implementation. It’s important to see exactly your controls in action on their own and acting with each other, so you can prevent doing lots of ‘easy’ fixes.

{{UnderConstructionStart}}

== Improving performance on complex List item templates ==

=== Overview ===
Performance issues in XAML-based UI development often stem from unnecessary UI rendering and binding errors. Hidden elements remain in the UI tree, impacting performance, while premature bindings cause background errors. To optimize complex list item templates, UI content can be loaded only when needed, and binding errors can be reduced by applying view models at the control level. These improvements enhance efficiency, reduce log clutter, and improve maintainability.

=== Technique 1: Loading UI content on demand ===
It was discovered that UI controls hidden with '''IsVisible=False''' remain in the UI tree. To improve performance on highly complex item templates, like UBIKTaskItem, rendered repeatedly such as in ListViews, a workaround can be applied to only load the UI content when the '''visibility''' binding condition is met.

==== Previous Approach ====
Previously, we used '''IsVisible''' directly with a binding condition. The approach looked like this:

<source lang = "xml">
<Label IsVisible="{Binding MROViewModel.PreviousValue, Converter={StaticResource NullToNotBool}}">
<Label.FormattedText>
<FormattedString>
<Span Text="{Binding MROViewModel.PreviousValue}" />
<Span Text=" " />
<Span Text="{Binding MROViewModel.Unit}" />
</FormattedString>
</Label.FormattedText>
</Label>
</source>
<br>

==== Improved Approach ====
To prevent unnecessary loading of UI elements when their '''visibility''' is False, it is possible to replace the UI content with a content hosting control, such as a '''ContentView''' or '''ContentControl'''. The original content should instead be defined as a template in '''UBIKThemes''', as shown below.

<source lang = "xml">
<ContentView>
<ContentView.Triggers>
<DataTrigger Binding="{Binding MROViewModel.PreviousValue, Converter={StaticResource NullToNotBool}, TargetNullValue=false, FallbackValue=false}"
Value="True" TargetType="ContentView">
<Setter Property="ControlTemplate" Value="{StaticResource PreviousValueTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>

The important part of the snippet above is the '''DataTrigger'''. Through this technique, the '''ControlTemplate''' of the content hosting control is only set once the visibility condition is met, preventing the UI content from being loaded until it is explicitly required.
And the associated '''ControlTemplate''', located in UBIKThemes:
<br>
<source lang = "xml">
<ControlTemplate x:Key="PreviousValueTemplate">
<Label>
<Label.FormattedText>
<FormattedString>
<Span Text="{TemplateBinding BindingContext.MROViewModel.PreviousValue}" />
<Span Text=" " />
<Span Text="{TemplateBinding BindingContext.MROViewModel.Unit}" />
</FormattedString>
</Label.FormattedText>
</Label>
</ControlTemplate>
</source>
<br>

'''Why This Change?'''
* '''More Modular''': The separation into discrete templates makes individual UI elements reusable and maintainable.
* '''Better Performance''': Eliminates unnecessary loading of UI elements in the background, that are not visible to the user.

<br>

=== Technique 2: Reducing background Binding errors ===

Complex item templates such as UBIKTaskItem were found to produce large numbers of '''errors''' while rendering, likely as bindings are being resolved before the relevant '''viewmodels''' can be loaded by the client. While these '''errors''' are temporary and not visible to the user, the cumulative effect of numerous binding errors raised while rendering items can be felt when navigating to pages with large numbers of items.
<br>
{{Attention|Unfortunately, these bindings errors are not normally logged in the UBIKDebug.log. Therefore, the recommendation is to use the following technique whenever using a ContentControl or controls:ContentControl.}}

==== Previous Approach ====
Initially, we used a '''ContentControl''' with a direct '''ContentTemplate''' and '''TemplateContext''', as shown below:

<tabs>
<tab name="Xamarin">
<source lang = "xml">
xmlns:ctrls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
</source>
</tab>
<tab name="MAUI">
<source lang = "xml">
xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</source>
</tab>
</tabs>

<source lang = "xml">
<ctrls:ContentControl
ContentTemplate="{StaticResource TaskPropertyTemplateSelector}"
TemplateContext="{Binding MROViewModel}" />
</source>
<br>

[[File:Binding_logs.png]]

==== Improved Approach ====
One workaround that reduced the number of '''binding errors''' encountered was to refer to '''viewmodels''' indirectly in the bindings.

<source lang = "xml">
<ctrls:ContentControl x:Name="TaskPropertyTempSelCtrl"
BindingContext="{Binding MROViewModel}"
TemplateContext="{Binding BindingContext, Source={x:Reference TaskPropertyTempSelCtrl}}">
</ctrls:ContentControl>
</source>
<br>

The previous example used an '''MROViewModel''' binding directly in the '''TemplateContext''' property of the '''<ctrls:ContentControl>.'''
However, a workaround that seems to avoid triggering background binding errors is to apply the '''MROViewModel''' to the '''<ctrls:ContentControl>''' itself via the '''BindingContext''' property, and then request that '''BindingContext''' using the x:Reference syntax seen in the '''TemplateContext''' property.

'''Why This Change?'''
* '''Avoids Additional Binding Errors''': Using this workaround seems to prevent binding errors.

{{UnderConstructionEnd}}

[[Category:Pages with broken file links|XAML Best practices]]
[[Category:XAML|XAML Best practices]]

HowTo:Implement Custom Filtering

2025-08-11T09:58:31Z

REP: /* Comparison */

This page describes how to customize filtered lists that accept one or multiple user inputs as filter criteria (referred to as 'Dynamic'), alone or combined with predefined criteria(referred to as 'Static'). The following examples are based on the Children.Items collection, however, Properties or Documents can be filtered too, by adjusting the ItemsSource in the <cv:ListCollectionView> or <controls:SfDataSourceExt> in UWP or Xamarin respectively.

{{Attention|Are you sure you need this?<br>UBIK has a simpler out-of-the-box Property-based filtering technique for filtering child objects when one or multiple property value inputs are the only type of criteria required. See [[Property_Based_Content_Filters]]}}

Four elements are required for Custom Filtering:
* Input field - for user inputs.
* [[EvalExpression]] - for converting user inputs into a filter expression.
* Collection Filter - for applying the expression to a collection.
* Items control - for displaying the filtered items.
<br>
<br>
This system acts dynamically to output the filtered list, without requiring the use of an Evaluation button, and directly outputs all items that match the filter input.

This page will first describe the basic implementation of a single dynamic input, then describe how to allow for multiple inputs, and finally, how to combine multiple dynamic inputs with static, predefined criteria.
However, keep in mind that for simply dynamically filtering child objects based on single or multiple property values, this complex customizing is not required. Instead, this technique gives the possibility to create multiple collections based on the same child collection, each with individual filters that do not interfere with each other, or else to create filters based on dynamic inputs for Properties or Documents, which are not handled by the Content-Based Filtering functionality.

<br>
== Basic Implementation ==
To build the filter in XAML, you will need to place an EvalExpression and a Collection Filter in the Resources of your container (most likely, a Grid). In the container's content, you will need the Input control, and the items control as an output (most likely a ListView).

The following namespaces are used:
<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
</source>
</tab>
</tabs>

=== Resources ===
For UWP, it is possible to place the EvalExpression and Collection Filter into the <Grid.Resources>, as shown below. However, for Xamarin, it is required to use the <ContentView.Resources>.
For the Collection Filter, use [[XAML_Changes_in_UBIK_WinX_3.5#Filtering_by_expressions|ListCollectionView]] for UWP & [[Xamarin_XAML#FeatureRelated|Content_filtering]] for Xamarin:

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid.Resources>
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<cv:ListCollectionView
x:Key="FilterView"
Expression="{Binding ElementName=FilterExpression, Path=Result}"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
</source>

{{Attention|Note that the EvalExpression in UWP requires an x:Name, which in turn requires the 'ElementName' syntax seen in the <cv:ListCollectionView>.}}
{{Attention|Note that the Converter seen in the 'EXP' EvalExpressionParameter in UWP is 'StringFormatConverter', which is different than in Xamarin.}}
</tab>

<tab name="Xamarin">
<source lang = "xml">
<ContentView.Resources>
<ResourceDictionary>
<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<controls:SfDataSourceExt
x:Key="FilterView"
Expression="{Binding Source={StaticResource FilterExpression}, Path=Result}"
ItemsSource="{Binding Children.Items}"
Unloaded="{Binding SkipFiltering}"/>
</ResourceDictionary>
</ContentView.Resources>
</source>
{{Attention|Note that Unloaded attribute improves performance by preventing refiltering while navigating away from the page. This attribute should be added to all instances of controls:SfDataSourceExt in your customizing.}}
{{Hint|Note that the EvalExpression in Xamarin requires an x:Key, which in turn requires the 'StaticResource ' syntax seen in the <controls:SfDataSourceExt>.}}
{{Hint|Note that the Converter seen in the 'EXP' EvalExpressionParameter in Xamarin is 'StringFormat', which is different than in UWP.}}
</tab>
</tabs>

The EvalExpression Expression first checks whether the TextBox input is empty (as this would otherwise incorrectly be considered a filter input, whereby the property should be empty) and if so returns the unfiltered list (expression outcome hardcoded to 'true'), otherwise, applies the filter (expression outcome is taken from string constructed in ConverterParameter of 'EXP').

There are two important details of the EvalExpressionParameter to note here:
* The "ElementName=NameInput" / "x:Reference NameInput" should match exactly to the name of your Input control.
* The Item.Values["NAME"] should be adapted, by changing NAME to the property that should be filtered by this input.

=== TextBox / Entry ===
The input field is just a basic <Textbox> / <Entry> we will use to input the filter criteria value. The only important detail for this input control is the name, which must be passed back to the EvalExpressionParameter.
<br>
<br>
It will look like this:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput"/>
</source>
</tab>
</tabs>

=== Items control ===
An items control will likely be used for displaying filtered results, such as <controls:SelectionBoundListView> for UWP & [[Xamarin_XAML#Performance|SfListViewExt]] for Xamarin:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:SelectionBoundListView
x:Name="FilterQueryList"
ItemsSource="{StaticResource FilterView}" />
</source>
</tab>

<tab name="Xamarin">
<source lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
ItemsSource="{Binding DisplayItems, Source={StaticResource FilterView}}" />
</source>
</tab>
</tabs>
<br>

== Multiple Dynamic (User Inputs) Criteria ==
It is likely that the customizing is required to process multiple user inputs for the same filter. In this case, the EvalExpression must be adapted to combine the inputs (most likely using an AND relation, for a 'filtering-down' effect), as well as to deliver the full list when nothing is inputted.
A <Textbox> / <Entry>, and an EvalExpression, will be required for every additional property, as well as a final EvalExpression to combine them.

The EvalExpressions should be amended as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DescInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DescInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DescInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference DescInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
<br>

The above example shows how to check for inputs to either property, NAME and DESCR, then use an additional EvalExpression to create the expression string that combines them. For each additional property you need to:
* Create an EvalExpression that checks whether the text input is null or empty, and if not, returns the desired expression EXP.
* Add each EvalExpression (Name_FilterExpression, Desc_FilterExpression) to the 'main' one (FilterExpression) as Parameters, combined using the escaped '&&' concatenation symbols.

{{Attention|Due to the escaped syntax required in the Expression, <source lang = "xml">+"&&"+</source> is the correct syntax required to concatenate filter expressions together.}}

Once the additional input controls have been created, processed in their own EvalExpressions, referenced as EvalExpressionParameters and the "FilterExpression" EvalExpression has been adapted as shown, the filter should already function as required; the Collection Filters and Items Controls do not need to be adapted.
<br>

=== One Input To Filter Multiple Properties ===
Since we have control over how the input is matched against the properties, is possible to use the same input to filter against multiple properties, for example, both Title and SubTitle. This keeps the UI lean with less elements to clutter the layout, and the user is not forced to think about which input relates to which field. The downside, of course, is that the search will be slightly less refined.
This is achieved easily as shown:

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT " Value="{Binding ElementName=Title_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding ElementName=SubTitle_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT" Value="{Binding Source={StaticResource Title_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding Source={StaticResource SubTitle_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

{{Attention|Note the different operator required in this case. Unless your object has the same Title ''and'' SubTitle, there will be no match found unless the FilterExpression is amended to an Or relationship.}}

<br>

== Combining Dynamic (User Inputs) and Static (Predefined) Criteria ==
A common use of the Collection Filter is to filter child lists based on one or multiple properties, such as MetaDefinition.UID or a certain status, to present groups of specific object types. Therefore, it is likely that a customizing may require hardcoded filter criteria, combined with user input, if any is provided.

The following describes how to implement such a scenario in XAML, again using [[:Category:Multiple Dynamic (User Inputs) Criteria]] as a starting point.

<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

Once one or multiple EvalExpressions have been added to process each input (such as Name_FilterExpression, Desc_FilterExpression), the remaining predefined filter criteria, in this example, filtering for a specific MetaClass by UID, can be added as an x:String, or directly in the EvalExpression paramerter, though the first approach is recommended, for better readability.

{{Attention|The above syntax only works for individual static string filters. If you need to chain multiple hardcoded filters, such as filtering in several UIDs, they need one String resource each, and must be added to the FilterExpression expression individually as in the below example.}}

=== Multiple Static Criteria ===
Experimentation has shown that the dynamic filter struggles to combine a single string made of multiple expressions, with additional expressions via the FilterExpression. However, it is still possible to combine user inputs and multiple static criteria, simply by breaking up the static criteria into separate strings.

Of course, when for example filtering various MetaDefinitions.UIDs, the '&' (and) comparison condition is no longer appropriate, as there will never be matches for multiple of these UIDs that returns a true result. In these cases, the comparison condition needs to be set to '||' ([[HowTo:Implement_Custom_Filtering#.27Or.27_Operations|Or]]).
The below example shows the correct syntax.

<tabs>
<tab name="UWP">
<br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String></source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin"><br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>
</source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
{{Hint|Note that the above strings make use of the .Equals() method, which is an alternate option to the more commonly seen <nowiki>'Item.Content.MetaDefinition.UID.ToString().ToLower()==...</nowiki>'}}
<br><br>

== Other Property Types ==

=== Filtering an INT / Double ===
Though the string comparison works mostly the same for a Int / Dbl, you additionally have to include a .ToString() method to the EXP EvalExpressionParameter of that property's individual EvalExpression for it to evaluate:
<source lang = "xml">
ConverterParameter='Item.Values["INSTRUCTIONID"].ToString().ToLower().Contains("{0}".ToLower())==true'
</source>
<br>

=== Filtering a Boolean (CheckBox) ===
To process a Boolean filter, the expression needs to be slightly amended, due to the different type of filter match criteria that is required.

Note that the below implementation returns all items by default (ie. when the CheckBox is unchecked), and returns only True matches when the CheckBox is checked. This functionality is designed to align with string input, where no filtering occurs for each string until something is entered into the corresponding text input box.
<br>
<source lang = "xml">
Note that this example uses UWP xaml syntax:

<controls:EvalExpression x:Name="Bool_FilterExpression" Expression="(INPUT==false) ? "true==true" : EXP" Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=CheckBox, Path=IsChecked, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["MP_BOOL"]=="{0}"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=CheckBox, Path=IsChecked}" />
</controls:EvalExpression>
</source>
<br>

* The individual EvalExpression for a Boolean filter match needs to be amended as follows:
** The INPUT can never be null, as the IsChecked property is either True or False. Therefore we can remove the Null or empty test, and instead, check whether the CheckBox is checked or not. IsChecked=False should 'escape' the expression, and return all items (or, not contribute to the overall filtering).
* The EvalExpressionParameter 'EXP' similarly can be simplified, as it does not need to make a string match with .Contains, but simply check whether the property value matches to True or False.
<br>
Changes only need to be made to the individual EvalExpression. The "FilterExpression" that joins all individual expressions does not need to be amended, other than the regular additional EvalExpressionParameter, and updating the expression accordingly.

<br>

=== Filtering a GUID Property ===
The expression string seen in the "EXP" command parameters shown above compare a user input with the value stored in Values[MP_PROPERTY], of the requested property. However, in certain cases, it may not be adequate to search in Values[MP_PROPERTY], such as when the property is a GUID. This is because Values[LK_GUID_PROPERTY] returns the UID value of the linked object, whereas Properties.VisibleItems[LK_GUID_PROPERTY].DisplayValue returns the human readable label associated with this linked object.

The solution is to rewrite the expression string to target the correct binding:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

A good way to inspect and test the target binding is to output it on the items UI, therefore on the ItemTemplate of your ListView, as well as to output the expressions that are being dynamically generated in your EvalExpressions, by binding the Result to the Text property of a <TextBlock> (UWP) or <Label> (Xamarin).
<br>
<br>

{{UnderConstructionStart}}
=== Filtering a DateTime Property ===
Filtering a DateTime property is more complex than other properties, because one has to consider both the input, and the type of filtering.

Input can be done both as freetext, and using a DatePicker. Freetext input has the downside that users have to take care to enter the correct string format (ie. yyyy/MM/dd), whereas the DatePicker outputs a DateTime string which can then be formatted for use in the EvalExpression. The DatePicker does however have certain downsides, chief of which being that it is not nullable, the current date is shown when no date has been selected, making the non-filtered UI indistinguishable from the filtered one.

Filtering can be done as a simple comparison, such as finding an object whose date matches the inputted date. However, it is also possible to ranges; either 'open', that is, dates before or after the user's selection, or 'closed', which is a date falling inside a range created by two user inputs.

==== Input ====
The input method is the first important consideration for filtering DateTime properties. A DatePicker is the generally accepted method. Textbox input is also possible, though users will need to correctly format their input to 'yyyy/MM/dd' (such as "2032/12/31") in order to achieve a valid comparison.

'''DatePicker'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<DatePicker x:Name="DatePicker" Tag="{Binding SelectedDate, ElementName=DatePicker, Converter={StaticResource StringFormatConverter}, ConverterParameter='{0:yyyy/MM/dd}'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<DatePicker x:Name="DateInput" />
<Label x:Name="DateString" Text="{Binding Path=Date, Source={x:Reference DateInput}, StringFormat='{0:yyyy/MM/dd}'}"/>
</source>
</tab>

{{Attention|In both cases, it is necessary that the format of the input matches the format of the property value, which will be explained more in the Comparison section below. In the above examples, this is applied in the Tag property (UWP) or through use of a secondary control (a Label in the Xamarin example).}}
</tabs>

'''Freetext'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="DateInput" PlaceholderText="Date"/>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="DateInput" Placeholder="Date"/>
</source>
</tab>

{{Attention|Remember that no matches will be found unless the date is inputted following a 'yyyy/MM/dd' format.}}
</tabs>

{{Hint|For greater control over the input format, it is also possible to provide multiple TextBoxes, which could then either be concatenated in an EvalExpression, or used to filter by the DateTime.Day/Week/Month values of the property individually, if such functionality fits the usecase.}}

<br>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Comparison ====
Since the EvalExpression approach utilizes string comparisons, not only is it necessary to format the input string, but the property value must also be formatted to match. The 'yyyy/MM/dd' format includes several measures to create the best conditions for comparing the two strings;
* months and days below the value of 10 cannot be a single digit, but must be padded with a preceding 0 in order to keep the string lengths equivalent; 2032/1/1 cannot be property compared with 2032/12/31 for example, as the strings are different lengths.
* putting the year and month first also improves the chance of a correct comparison, as a day 01 can be after a day 31 if the month and year are greater.

{{Attention|For the rest of this section, a DatePicker input is assumed.}}

'''Single'''

Comparison of a single date against a property value works the same way as other dynamic filters. Therefore it is sufficient to make use of the previously used .Contains() or .Equals() methods.
Remember that the Date attribute is not directly usable from the DatePicker, and its formatted version received via the Tag attribute or an additional label is what is actually used by the EvalExpressions.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DatePicker, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DatePicker, Path=Tag}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Path=Text, Source={x:Reference DateString}, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Path=Text, Source={x:Reference DateString}}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

'''Range'''
<br>
It is also possible to filter not for a specific date, but rather for all items whose property falls after or before the user input (depending on whether a 'Starting From' or 'Ending By' comparison is implemented. An 'open' range filter is created when only one value is inputted by the user, whereas a 'closed' range has a start and end date, and must fall on or in between these two.

For range comparison, we use the [https://learn.microsoft.com/en-us/dotnet/api/system.string.compareto?view=net-9.0 Microsoft .CompareTo method]. As documented there, this method outputs a -1/0/1 depending on the compared string's location in the range. Our expression can target one output for an 'exclusive' filter (in which the inputted date is not considered for the range), however, a more likely scenario is that the user wants the inputted date included in the filter. This is why the expression in the StringFormatConverter should be defined for start date as !=-1, and for end date as !=1; the instance should be not less than than the start date (where true would be an output of 0 or 1), and not greater than the end date (true = -1 or 0), respectively.

Similar to the earlier section on [[HowTo:Implement_Custom_Filtering#Multiple_Dynamic_.28User_Inputs.29_Criteria|multiple inputs]], separate EvalExpressions are used for each half of the range, meaning that the filtering also works (as an 'open Range' filter) when only one value is inputted by the user. To implement only an open range filter, simply eliminate the second input and EvalExpression.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Start_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=StartInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=StartInput, Path=Tag}" />
</controls:EvalExpression>
<controls:EvalExpression x:Name="End_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=EndInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=EndInput, Path=Tag}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding ElementName=Start_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding ElementName=End_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Start_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference StartString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference StartString}, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Key="End_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference EndString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference EndString}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding Source={StaticResource Start_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding Source={StaticResource End_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note the .CompareTo method used in each half of the ranged filter expression; the start date comparison is <noWiki>!=-1</noWiki>, whereas the end date comparison <noWiki>!=1</noWiki>.}}
</tabs>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Individual DateTime Components ====
The DateTime property has the additional benefit of exposing components that can be used to refine filtering.

[[Developer_Mode]] reveals the members available under the binding path; <source lang = "xml">PropertyItems["DATETIME"].Value</source>
These include; Date, Day, DayOfWeek, DayOfYear, Hour, Millisecond, Minute, Month, Ticks, TimeOfDay, and Year.

These can be used in the EvalExpressionParameter as a binding in the custom expression string, as follows, and can even be used in separate filters to search individual components of the date seperately (for example, to filter by a particular month, year, or even day of the week).
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DateInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().Contains("{0}".ToLower())==true'}" />
</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DayWeekInputString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

<br>
<br>
{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Adjustments ==
=== 'Or' Operations ===
All examples of multiple inputs in this article use an 'and' filter condition, where, if any inputs are entered, only items that match all inputs (NAME <b>and</b> DESC) are kept in the collection, to produce a 'filtering down' effect in the user interface.

If a less strict filter condition is required, the FilterExpression can be altered to have an 'or' condition, where all results that match NAME <b>or</b> DESC, but not necessarily both, are shown. To do so, simply change the concatenation syntax to return 'or' symbols (two pipes or '||'):
<source lang = "xml">
+"||"+
</source>

== Displaying a Count ==
To display the filtered count, use the following syntax:

<source lang = "xml">
"{Binding Path=Count, Source={StaticResource FilterView}}"
</source>

== Persisting Filter Values ==
{{UnderConstructionStart}}
One of the drawbacks of this method of filtering is the inability for the UI to 'remember' user inputs when they navigate away from the page. This is because this implementation of dynamic filters exists solely on the UI thread (that is, is defined in XAML only with no actual connection to the data, opposite to [[Property_Based_Content_Filters]], for example), which is re-rendered according to the xaml definition every time the page is loaded. This section describes how to implement a limited solution to this issue, the limitation being that values can currently only be persisted during the 'session', and are lost when the user closes the client.

This solution involves use of the StoreProfileParameterCommand to create key-value pairs (a simple list of items made up of a name and a value), which can then be read using the 'StoredProfileParameters[key]'. The StoreProfileParameterCommand accepts a CommandParameter with the format 'key=value', where 'key' represents the name of the key-value pair that can be used to reference it later (in the case below, "name"), and 'value' represents what string should be returned by referencing it (in this case, the Text attribute of the text field control).

When a user completes their input, we use the StoreProfileParameterCommand to create or update a key-value pair associated with a particular filter, instead of passively reading the value from the input as was done previously.

Furthermore, the associated StoredProfileParameter is fed back to the input control so that if any value is set for that particular key (ie. if a filter value has been created), it will be displayed on the input control. Otherwise, the input control will be reset when next loading the page, as was previously the case with dynamic filtering, whereas the StoredProfileParameter will be persisted, leading to a mismatch between the UI and filtering state.
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<interactivity:Interaction.Behaviors>
<core:EventTriggerBehavior EventName="LostFocus">
<core:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Text, ElementName=NameInput, Converter={StaticResource StringFormatConverter}, ConverterParameter='name={0}'}" />
</core:EventTriggerBehavior>
</interactivity:Interaction.Behaviors>
</TextBox>
</source>

Pay attention to which [https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.textbox?view=winrt-26100#events Event] is used to trigger the StoreProfileParameterCommand. The above example uses LostFocus, which fires when the user clicks out of the TextBox. Another possible choice is TextChanged, however, this means that the command will fire with every keystroke, which may reduce overall performance.
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<Entry.Behaviors>
<behaviors:EventHandlerBehavior EventName="Completed">
<behaviors:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Path=Text, Source={x:Reference NameInput}, StringFormat='name={0}'}" />
</behaviors:EventHandlerBehavior>
</Entry.Behaviors>
</Entry>
</source>

The Xamarin 'Completed' event fires when the user clicks the return button on their onscreen keyboard.
</tab>
{{Hint|StringFormatConverter/StringFormat is used to format the key-value pair as required by the StoreProfileParameterCommand. The key is hardcoded into the formatted string as, for example <noWiki>'name={0}'</noWiki>. The dynamic value, in this case whatever is inputted in the text field when the edit is completed, replaces the <noWiki>{0}</noWiki> tag when the binding is evaluated (ie. when the command is executed).}}
</tabs>

In this implementation, the EvalExpression also needs to be adapted to check whether a particular filter value exists within the StoredProfileParameters list, instead of simply whether the associated input control has a value or selection:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["NAME"].ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["NAME"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note how the EvalExpressionParameters have been adapted to reference a StoredProfileParameter, rather than the input control.}}
</tabs>

=== Item Selection ===
Filter value persistence works also when the user input method is to select an item from a picker.

<tabs>
<tab name="Xamarin">
<source lang = "xml">
<controls:PickerExt
x:Name="ExamplePicker"
ItemsSource="{Binding Children.Items[0].PropertyItems[PROPERTY].MetaProperty.SelectiveList, Converter={StaticResource SelectiveListToItems}, TargetNullValue='', FallbackValue=''}"
ItemDisplayBinding="{Binding DisplayText}"
SelectedValuePath="Value"
SelectedValue="{Binding StoredProfileParameters[key]}"
SelectionChangedCommand="{Binding StoreProfileParameterCommand}"
SelectionChangedCommandParameter="{Binding SelectedItem.Value, Source={x:Reference ExamplePicker}, StringFormat='key={0}'}"/>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Known Issues ==
=== Text Input in ListView Header Template ===
This implementation will not work when parts of it, such as the Input fields, are hosted in a ListView header or footer template, as this content is not readable by the rest of the page and will return a "Can not find the object referenced" parsing error.

To workaround this, you need to move the Input control out of the header template.

=== Troubleshooting ===
* Everything looks correct but filtering returns no results:
** Ensure that the string you are trying to filter by matches what is returned as the DisplayValue.
** If the property is a INT / DBL (Integer or Double) type: The string comparison doesn't work directly with non-string types. Check the [[HowTo:Implement_Custom_Filtering#Other_Property_Types|Other Property Types]] section.
** If filtering a DateTime property, ensure the formatting of the input matches that of the property value in the EXP string.
** If filtering a GUID property, ensure the same values are compared; DisplayString if the user is inputting readable text, UID if the user has selected an item from a list.

== See also ==
* [[XAML]]
* [[XAML_Tips]]
* [[Xamarin_XAML]]

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

HowTo:Implement Custom Filtering

2025-07-30T13:36:11Z

REP: /* Comparison */

This page describes how to customize filtered lists that accept one or multiple user inputs as filter criteria (referred to as 'Dynamic'), alone or combined with predefined criteria(referred to as 'Static'). The following examples are based on the Children.Items collection, however, Properties or Documents can be filtered too, by adjusting the ItemsSource in the <cv:ListCollectionView> or <controls:SfDataSourceExt> in UWP or Xamarin respectively.

{{Attention|Are you sure you need this?<br>UBIK has a simpler out-of-the-box Property-based filtering technique for filtering child objects when one or multiple property value inputs are the only type of criteria required. See [[Property_Based_Content_Filters]]}}

Four elements are required for Custom Filtering:
* Input field - for user inputs.
* [[EvalExpression]] - for converting user inputs into a filter expression.
* Collection Filter - for applying the expression to a collection.
* Items control - for displaying the filtered items.
<br>
<br>
This system acts dynamically to output the filtered list, without requiring the use of an Evaluation button, and directly outputs all items that match the filter input.

This page will first describe the basic implementation of a single dynamic input, then describe how to allow for multiple inputs, and finally, how to combine multiple dynamic inputs with static, predefined criteria.
However, keep in mind that for simply dynamically filtering child objects based on single or multiple property values, this complex customizing is not required. Instead, this technique gives the possibility to create multiple collections based on the same child collection, each with individual filters that do not interfere with each other, or else to create filters based on dynamic inputs for Properties or Documents, which are not handled by the Content-Based Filtering functionality.

<br>
== Basic Implementation ==
To build the filter in XAML, you will need to place an EvalExpression and a Collection Filter in the Resources of your container (most likely, a Grid). In the container's content, you will need the Input control, and the items control as an output (most likely a ListView).

The following namespaces are used:
<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
</source>
</tab>
</tabs>

=== Resources ===
For UWP, it is possible to place the EvalExpression and Collection Filter into the <Grid.Resources>, as shown below. However, for Xamarin, it is required to use the <ContentView.Resources>.
For the Collection Filter, use [[XAML_Changes_in_UBIK_WinX_3.5#Filtering_by_expressions|ListCollectionView]] for UWP & [[Xamarin_XAML#FeatureRelated|Content_filtering]] for Xamarin:

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid.Resources>
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<cv:ListCollectionView
x:Key="FilterView"
Expression="{Binding ElementName=FilterExpression, Path=Result}"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
</source>

{{Attention|Note that the EvalExpression in UWP requires an x:Name, which in turn requires the 'ElementName' syntax seen in the <cv:ListCollectionView>.}}
{{Attention|Note that the Converter seen in the 'EXP' EvalExpressionParameter in UWP is 'StringFormatConverter', which is different than in Xamarin.}}
</tab>

<tab name="Xamarin">
<source lang = "xml">
<ContentView.Resources>
<ResourceDictionary>
<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<controls:SfDataSourceExt
x:Key="FilterView"
Expression="{Binding Source={StaticResource FilterExpression}, Path=Result}"
ItemsSource="{Binding Children.Items}"
Unloaded="{Binding SkipFiltering}"/>
</ResourceDictionary>
</ContentView.Resources>
</source>
{{Attention|Note that Unloaded attribute improves performance by preventing refiltering while navigating away from the page. This attribute should be added to all instances of controls:SfDataSourceExt in your customizing.}}
{{Hint|Note that the EvalExpression in Xamarin requires an x:Key, which in turn requires the 'StaticResource ' syntax seen in the <controls:SfDataSourceExt>.}}
{{Hint|Note that the Converter seen in the 'EXP' EvalExpressionParameter in Xamarin is 'StringFormat', which is different than in UWP.}}
</tab>
</tabs>

The EvalExpression Expression first checks whether the TextBox input is empty (as this would otherwise incorrectly be considered a filter input, whereby the property should be empty) and if so returns the unfiltered list (expression outcome hardcoded to 'true'), otherwise, applies the filter (expression outcome is taken from string constructed in ConverterParameter of 'EXP').

There are two important details of the EvalExpressionParameter to note here:
* The "ElementName=NameInput" / "x:Reference NameInput" should match exactly to the name of your Input control.
* The Item.Values["NAME"] should be adapted, by changing NAME to the property that should be filtered by this input.

=== TextBox / Entry ===
The input field is just a basic <Textbox> / <Entry> we will use to input the filter criteria value. The only important detail for this input control is the name, which must be passed back to the EvalExpressionParameter.
<br>
<br>
It will look like this:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput"/>
</source>
</tab>
</tabs>

=== Items control ===
An items control will likely be used for displaying filtered results, such as <controls:SelectionBoundListView> for UWP & [[Xamarin_XAML#Performance|SfListViewExt]] for Xamarin:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:SelectionBoundListView
x:Name="FilterQueryList"
ItemsSource="{StaticResource FilterView}" />
</source>
</tab>

<tab name="Xamarin">
<source lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
ItemsSource="{Binding DisplayItems, Source={StaticResource FilterView}}" />
</source>
</tab>
</tabs>
<br>

== Multiple Dynamic (User Inputs) Criteria ==
It is likely that the customizing is required to process multiple user inputs for the same filter. In this case, the EvalExpression must be adapted to combine the inputs (most likely using an AND relation, for a 'filtering-down' effect), as well as to deliver the full list when nothing is inputted.
A <Textbox> / <Entry>, and an EvalExpression, will be required for every additional property, as well as a final EvalExpression to combine them.

The EvalExpressions should be amended as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DescInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DescInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DescInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference DescInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
<br>

The above example shows how to check for inputs to either property, NAME and DESCR, then use an additional EvalExpression to create the expression string that combines them. For each additional property you need to:
* Create an EvalExpression that checks whether the text input is null or empty, and if not, returns the desired expression EXP.
* Add each EvalExpression (Name_FilterExpression, Desc_FilterExpression) to the 'main' one (FilterExpression) as Parameters, combined using the escaped '&&' concatenation symbols.

{{Attention|Due to the escaped syntax required in the Expression, <source lang = "xml">+"&&"+</source> is the correct syntax required to concatenate filter expressions together.}}

Once the additional input controls have been created, processed in their own EvalExpressions, referenced as EvalExpressionParameters and the "FilterExpression" EvalExpression has been adapted as shown, the filter should already function as required; the Collection Filters and Items Controls do not need to be adapted.
<br>

=== One Input To Filter Multiple Properties ===
Since we have control over how the input is matched against the properties, is possible to use the same input to filter against multiple properties, for example, both Title and SubTitle. This keeps the UI lean with less elements to clutter the layout, and the user is not forced to think about which input relates to which field. The downside, of course, is that the search will be slightly less refined.
This is achieved easily as shown:

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT " Value="{Binding ElementName=Title_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding ElementName=SubTitle_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT" Value="{Binding Source={StaticResource Title_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding Source={StaticResource SubTitle_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

{{Attention|Note the different operator required in this case. Unless your object has the same Title ''and'' SubTitle, there will be no match found unless the FilterExpression is amended to an Or relationship.}}

<br>

== Combining Dynamic (User Inputs) and Static (Predefined) Criteria ==
A common use of the Collection Filter is to filter child lists based on one or multiple properties, such as MetaDefinition.UID or a certain status, to present groups of specific object types. Therefore, it is likely that a customizing may require hardcoded filter criteria, combined with user input, if any is provided.

The following describes how to implement such a scenario in XAML, again using [[:Category:Multiple Dynamic (User Inputs) Criteria]] as a starting point.

<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

Once one or multiple EvalExpressions have been added to process each input (such as Name_FilterExpression, Desc_FilterExpression), the remaining predefined filter criteria, in this example, filtering for a specific MetaClass by UID, can be added as an x:String, or directly in the EvalExpression paramerter, though the first approach is recommended, for better readability.

{{Attention|The above syntax only works for individual static string filters. If you need to chain multiple hardcoded filters, such as filtering in several UIDs, they need one String resource each, and must be added to the FilterExpression expression individually as in the below example.}}

=== Multiple Static Criteria ===
Experimentation has shown that the dynamic filter struggles to combine a single string made of multiple expressions, with additional expressions via the FilterExpression. However, it is still possible to combine user inputs and multiple static criteria, simply by breaking up the static criteria into separate strings.

Of course, when for example filtering various MetaDefinitions.UIDs, the '&' (and) comparison condition is no longer appropriate, as there will never be matches for multiple of these UIDs that returns a true result. In these cases, the comparison condition needs to be set to '||' ([[HowTo:Implement_Custom_Filtering#.27Or.27_Operations|Or]]).
The below example shows the correct syntax.

<tabs>
<tab name="UWP">
<br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String></source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin"><br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>
</source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
{{Hint|Note that the above strings make use of the .Equals() method, which is an alternate option to the more commonly seen <nowiki>'Item.Content.MetaDefinition.UID.ToString().ToLower()==...</nowiki>'}}
<br><br>

== Other Property Types ==

=== Filtering an INT / Double ===
Though the string comparison works mostly the same for a Int / Dbl, you additionally have to include a .ToString() method to the EXP EvalExpressionParameter of that property's individual EvalExpression for it to evaluate:
<source lang = "xml">
ConverterParameter='Item.Values["INSTRUCTIONID"].ToString().ToLower().Contains("{0}".ToLower())==true'
</source>
<br>

=== Filtering a Boolean (CheckBox) ===
To process a Boolean filter, the expression needs to be slightly amended, due to the different type of filter match criteria that is required.

Note that the below implementation returns all items by default (ie. when the CheckBox is unchecked), and returns only True matches when the CheckBox is checked. This functionality is designed to align with string input, where no filtering occurs for each string until something is entered into the corresponding text input box.
<br>
<source lang = "xml">
Note that this example uses UWP xaml syntax:

<controls:EvalExpression x:Name="Bool_FilterExpression" Expression="(INPUT==false) ? "true==true" : EXP" Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=CheckBox, Path=IsChecked, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["MP_BOOL"]=="{0}"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=CheckBox, Path=IsChecked}" />
</controls:EvalExpression>
</source>
<br>

* The individual EvalExpression for a Boolean filter match needs to be amended as follows:
** The INPUT can never be null, as the IsChecked property is either True or False. Therefore we can remove the Null or empty test, and instead, check whether the CheckBox is checked or not. IsChecked=False should 'escape' the expression, and return all items (or, not contribute to the overall filtering).
* The EvalExpressionParameter 'EXP' similarly can be simplified, as it does not need to make a string match with .Contains, but simply check whether the property value matches to True or False.
<br>
Changes only need to be made to the individual EvalExpression. The "FilterExpression" that joins all individual expressions does not need to be amended, other than the regular additional EvalExpressionParameter, and updating the expression accordingly.

<br>

=== Filtering a GUID Property ===
The expression string seen in the "EXP" command parameters shown above compare a user input with the value stored in Values[MP_PROPERTY], of the requested property. However, in certain cases, it may not be adequate to search in Values[MP_PROPERTY], such as when the property is a GUID. This is because Values[LK_GUID_PROPERTY] returns the UID value of the linked object, whereas Properties.VisibleItems[LK_GUID_PROPERTY].DisplayValue returns the human readable label associated with this linked object.

The solution is to rewrite the expression string to target the correct binding:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

A good way to inspect and test the target binding is to output it on the items UI, therefore on the ItemTemplate of your ListView, as well as to output the expressions that are being dynamically generated in your EvalExpressions, by binding the Result to the Text property of a <TextBlock> (UWP) or <Label> (Xamarin).
<br>
<br>

{{UnderConstructionStart}}
=== Filtering a DateTime Property ===
Filtering a DateTime property is more complex than other properties, because one has to consider both the input, and the type of filtering.

Input can be done both as freetext, and using a DatePicker. Freetext input has the downside that users have to take care to enter the correct string format (ie. yyyy/MM/dd), whereas the DatePicker outputs a DateTime string which can then be formatted for use in the EvalExpression. The DatePicker does however have certain downsides, chief of which being that it is not nullable, the current date is shown when no date has been selected, making the non-filtered UI indistinguishable from the filtered one.

Filtering can be done as a simple comparison, such as finding an object whose date matches the inputted date. However, it is also possible to ranges; either 'open', that is, dates before or after the user's selection, or 'closed', which is a date falling inside a range created by two user inputs.

==== Input ====
The input method is the first important consideration for filtering DateTime properties. A DatePicker is the generally accepted method. Textbox input is also possible, though users will need to correctly format their input to 'yyyy/MM/dd' (such as "2032/12/31") in order to achieve a valid comparison.

'''DatePicker'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<DatePicker x:Name="DatePicker" Tag="{Binding SelectedDate, ElementName=DatePicker, Converter={StaticResource StringFormatConverter}, ConverterParameter='{0:yyyy/MM/dd}'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<DatePicker x:Name="DateInput" />
<Label x:Name="DateString" Text="{Binding Path=Date, Source={x:Reference DateInput}, StringFormat='{0:yyyy/MM/dd}'}"/>
</source>
</tab>

{{Attention|In both cases, it is necessary that the format of the input matches the format of the property value, which will be explained more in the Comparison section below. In the above examples, this is applied in the Tag property (UWP) or through use of a secondary control (a Label in the Xamarin example).}}
</tabs>

'''Freetext'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="DateInput" PlaceholderText="Date"/>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="DateInput" Placeholder="Date"/>
</source>
</tab>

{{Attention|Remember that no matches will be found unless the date is inputted following a 'yyyy/MM/dd' format.}}
</tabs>

{{Hint|For greater control over the input format, it is also possible to provide multiple TextBoxes, which could then either be concatenated in an EvalExpression, or used to filter by the DateTime.Day/Week/Month values of the property individually, if such functionality fits the usecase.}}

<br>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Comparison ====
Since the EvalExpression approach utilizes string comparisons, not only is it necessary to format the input string, but the property value must also be formatted to match. The 'yyyy/MM/dd' format includes several measures to create the best conditions for comparing the two strings;
* months and days below the value of 10 cannot be a single digit, but must be padded with a preceding 0 in order to keep the string lengths equivalent; 2032/1/1 cannot be property compared with 2032/12/31 for example, as the strings are different lengths.
* putting the year and month first also improves the chance of a correct comparison, as a day 01 can be after a day 31 if the month and year are greater.

{{Attention|For the rest of this section, a DatePicker input is assumed.}}

'''Single'''

Comparison of a single date against a property value works the same way as other dynamic filters. Therefore it is sufficient to make use of the previously used .Contains() or .Equals() methods.
Remember that the Date attribute is not directly usable from the DatePicker, and it's formatted version received via the Tag attribute or an additional label is what is actually used by the EvalExpressions.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DatePicker, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DatePicker, Path=Tag}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Path=Text, Source={x:Reference DateString}, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Path=Text, Source={x:Reference DateString}}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

'''Range'''
<br>
It is also possible to filter not for a specific date, but rather for all items whose property falls after or before the user input (depending on whether a 'Starting From' or 'Ending By' comparison is implemented. An 'open' range filter is created when only one value is inputted by the user, whereas a 'closed' range has a start and end date, and must fall on or in between these two.

For range comparison, we use the [https://learn.microsoft.com/en-us/dotnet/api/system.string.compareto?view=net-9.0 Microsoft .CompareTo method]. As documented there, this method outputs a -1/0/1 depending on the compared string's location in the range. Our expression can target one output for an 'exclusive' filter (in which the inputted date is not considered for the range), however, a more likely scenario is that the user wants the inputted date included in the filter. This is why the expression in the StringFormatConverter should be defined for start date as !=-1, and for end date as !=1; the instance should be not less than than the start date (where true would be an output of 0 or 1), and not greater than the end date (true = -1 or 0), respectively.

Similar to the earlier section on [[HowTo:Implement_Custom_Filtering#Multiple_Dynamic_.28User_Inputs.29_Criteria|multiple inputs]], separate EvalExpressions are used for each half of the range, meaning that the filtering also works (as an 'open Range' filter) when only one value is inputted by the user. To implement only an open range filter, simply eliminate the second input and EvalExpression.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Start_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=StartInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=StartInput, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Name="End_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=EndInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=EndInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding ElementName=Start_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding ElementName=End_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Start_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference StartString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference StartString}, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Key="End_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference EndString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference EndString}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding Source={StaticResource Start_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding Source={StaticResource End_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note the .CompareTo method used in each half of the ranged filter expression; the start date comparison is <noWiki>!=-1</noWiki>, whereas the end date comparison <noWiki>!=1</noWiki>.}}
</tabs>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Individual DateTime Components ====
The DateTime property has the additional benefit of exposing components that can be used to refine filtering.

[[Developer_Mode]] reveals the members available under the binding path; <source lang = "xml">PropertyItems["DATETIME"].Value</source>
These include; Date, Day, DayOfWeek, DayOfYear, Hour, Millisecond, Minute, Month, Ticks, TimeOfDay, and Year.

These can be used in the EvalExpressionParameter as a binding in the custom expression string, as follows, and can even be used in separate filters to search individual components of the date seperately (for example, to filter by a particular month, year, or even day of the week).
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DateInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().Contains("{0}".ToLower())==true'}" />
</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DayWeekInputString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

<br>
<br>
{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Adjustments ==
=== 'Or' Operations ===
All examples of multiple inputs in this article use an 'and' filter condition, where, if any inputs are entered, only items that match all inputs (NAME <b>and</b> DESC) are kept in the collection, to produce a 'filtering down' effect in the user interface.

If a less strict filter condition is required, the FilterExpression can be altered to have an 'or' condition, where all results that match NAME <b>or</b> DESC, but not necessarily both, are shown. To do so, simply change the concatenation syntax to return 'or' symbols (two pipes or '||'):
<source lang = "xml">
+"||"+
</source>

== Displaying a Count ==
To display the filtered count, use the following syntax:

<source lang = "xml">
"{Binding Path=Count, Source={StaticResource FilterView}}"
</source>

== Persisting Filter Values ==
{{UnderConstructionStart}}
One of the drawbacks of this method of filtering is the inability for the UI to 'remember' user inputs when they navigate away from the page. This is because this implementation of dynamic filters exists solely on the UI thread (that is, is defined in XAML only with no actual connection to the data, opposite to [[Property_Based_Content_Filters]], for example), which is re-rendered according to the xaml definition every time the page is loaded. This section describes how to implement a limited solution to this issue, the limitation being that values can currently only be persisted during the 'session', and are lost when the user closes the client.

This solution involves use of the StoreProfileParametersCommand to create key-value pairs (a simple list of items made up of a name and a value), which can then be read using the 'StoredProfileParameters[key]'. The StoreProfileParameterCommand accepts a CommandParameter with the format 'key=value', where 'key' represents the name of the key-value pair that can be used to reference it later (in the case below, "name"), and 'value' represents what string should be returned by referencing it (in this case, the Text attribute of the text field control).

When a user completes their input, we use the StoreProfileParametersCommand to create or update a key-value pair associated with a particular filter, instead of passively reading the value from the input as was done previously.

Furthermore, the associated StoredProfileParameter is fed back to the input control so that if any value is set for that particular key (ie. if a filter value has been created), it will be displayed on the input control. Otherwise, the input control will be reset when next loading the page, as was previously the case with dynamic filtering, whereas the StoredProfileParameter will be persisted, leading to a mismatch between the UI and filtering state.
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" Text="{Binding StoredProfileParameter[name]}">
<interactivity:Interaction.Behaviors>
<core:EventTriggerBehavior EventName="LostFocus">
<core:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Text, ElementName=NameInput, Converter={StaticResource StringFormatConverter}, ConverterParameter='name={0}'}" />
</core:EventTriggerBehavior>
</interactivity:Interaction.Behaviors>
</TextBox>
</source>

Pay attention to which [https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.textbox?view=winrt-26100#events Event] is used to trigger the StoreProfileParameterCommand. The above example uses LostFocus, which fires when the user clicks out of the TextBox. Another possible choice is TextChanged, however, this means that the command will fire with every keystroke, which may reduce overall performance.
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<Entry.Behaviors>
<behaviors:EventHandlerBehavior EventName="Completed">
<behaviors:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Path=Text, Source={x:Reference NameInput}, StringFormat='name={0}'}" />
</behaviors:EventHandlerBehavior>
</Entry.Behaviors>
</Entry>
</source>

The Xamarin 'Completed' event fires when the user clicks the return button on their onscreen keyboard.
</tab>
{{Hint|StringFormatConverter/StringFormat is used to format the key-value pair as required by the StoreProfileParameterCommand. The key is hardcoded into the formatted string as, for example <noWiki>'name={0}'</noWiki>. The dynamic value, in this case whatever is inputted in the text field when the edit is completed, replaces the <noWiki>{0}</noWiki> tag when the binding is evaluated (ie. when the command is executed).}}
</tabs>

In this implementation, the EvalExpression also needs to be adapted to check whether a particular filter value exists within the StoredProfileParameters list, instead of simply whether the associated input control has a value or selection:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["NAME"].ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["NAME"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note how the EvalExpressionParameters have been adapted to reference a StoredProfileParameter, rather than the input control.}}
</tabs>

=== Item Selection ===
Filter value persistence works also when the user input method is to select an item from a picker.

<tabs>
<tab name="Xamarin">
<source lang = "xml">
<controls:PickerExt
x:Name="ExamplePicker"
ItemsSource="{Binding Children.Items[0].PropertyItems[PROPERTY].MetaProperty.SelectiveList, Converter={StaticResource SelectiveListToItems}, TargetNullValue='', FallbackValue=''}"
ItemDisplayBinding="{Binding DisplayText}"
SelectedValuePath="Value"
SelectedValue="{Binding StoredProfileParameters[key]}"
SelectionChangedCommand="{Binding StoreProfileParameterCommand}"
SelectionChangedCommandParameter="{Binding SelectedItem.Value, Source={x:Reference ExamplePicker}, StringFormat='key={0}'}"/>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

== Known Issues ==
=== Text Input in ListView Header Template ===
This implementation will not work when parts of it, such as the Input fields, are hosted in a ListView header or footer template, as this content is not readable by the rest of the page and will return a "Can not find the object referenced" parsing error.

To workaround this, you need to move the Input control out of the header template.

=== Troubleshooting ===
* Everything looks correct but filtering returns no results:
** Ensure that the string you are trying to filter by matches what is returned as the DisplayValue.
** If the property is a INT / DBL (Integer or Double) type: The string comparison doesn't work directly with non-string types. Check the [[HowTo:Implement_Custom_Filtering#Other_Property_Types|Other Property Types]] section.
** If filtering a DateTime property, ensure the formatting of the input matches that of the property value in the EXP string.
** If filtering a GUID property, ensure the same values are compared; DisplayString if the user is inputting readable text, UID if the user has selected an item from a list.

== See also ==
* [[XAML]]
* [[XAML_Tips]]
* [[Xamarin_XAML]]

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

HowTo:Implement Custom Filtering

2025-07-30T13:34:20Z

REP: /* Input */

This page describes how to customize filtered lists that accept one or multiple user inputs as filter criteria (referred to as 'Dynamic'), alone or combined with predefined criteria(referred to as 'Static'). The following examples are based on the Children.Items collection, however, Properties or Documents can be filtered too, by adjusting the ItemsSource in the <cv:ListCollectionView> or <controls:SfDataSourceExt> in UWP or Xamarin respectively.

{{Attention|Are you sure you need this?<br>UBIK has a simpler out-of-the-box Property-based filtering technique for filtering child objects when one or multiple property value inputs are the only type of criteria required. See [[Property_Based_Content_Filters]]}}

Four elements are required for Custom Filtering:
* Input field - for user inputs.
* [[EvalExpression]] - for converting user inputs into a filter expression.
* Collection Filter - for applying the expression to a collection.
* Items control - for displaying the filtered items.
<br>
<br>
This system acts dynamically to output the filtered list, without requiring the use of an Evaluation button, and directly outputs all items that match the filter input.

This page will first describe the basic implementation of a single dynamic input, then describe how to allow for multiple inputs, and finally, how to combine multiple dynamic inputs with static, predefined criteria.
However, keep in mind that for simply dynamically filtering child objects based on single or multiple property values, this complex customizing is not required. Instead, this technique gives the possibility to create multiple collections based on the same child collection, each with individual filters that do not interfere with each other, or else to create filters based on dynamic inputs for Properties or Documents, which are not handled by the Content-Based Filtering functionality.

<br>
== Basic Implementation ==
To build the filter in XAML, you will need to place an EvalExpression and a Collection Filter in the Resources of your container (most likely, a Grid). In the container's content, you will need the Input control, and the items control as an output (most likely a ListView).

The following namespaces are used:
<tabs>
<tab name="UWP">
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
</source>
</tab>
</tabs>

=== Resources ===
For UWP, it is possible to place the EvalExpression and Collection Filter into the <Grid.Resources>, as shown below. However, for Xamarin, it is required to use the <ContentView.Resources>.
For the Collection Filter, use [[XAML_Changes_in_UBIK_WinX_3.5#Filtering_by_expressions|ListCollectionView]] for UWP & [[Xamarin_XAML#FeatureRelated|Content_filtering]] for Xamarin:

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid.Resources>
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<cv:ListCollectionView
x:Key="FilterView"
Expression="{Binding ElementName=FilterExpression, Path=Result}"
ItemsSource="{Binding Children.Items}" />
</Grid.Resources>
</source>

{{Attention|Note that the EvalExpression in UWP requires an x:Name, which in turn requires the 'ElementName' syntax seen in the <cv:ListCollectionView>.}}
{{Attention|Note that the Converter seen in the 'EXP' EvalExpressionParameter in UWP is 'StringFormatConverter', which is different than in Xamarin.}}
</tab>

<tab name="Xamarin">
<source lang = "xml">
<ContentView.Resources>
<ResourceDictionary>
<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true" : EXP">
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
</controls:EvalExpression>
<controls:SfDataSourceExt
x:Key="FilterView"
Expression="{Binding Source={StaticResource FilterExpression}, Path=Result}"
ItemsSource="{Binding Children.Items}"
Unloaded="{Binding SkipFiltering}"/>
</ResourceDictionary>
</ContentView.Resources>
</source>
{{Attention|Note that Unloaded attribute improves performance by preventing refiltering while navigating away from the page. This attribute should be added to all instances of controls:SfDataSourceExt in your customizing.}}
{{Hint|Note that the EvalExpression in Xamarin requires an x:Key, which in turn requires the 'StaticResource ' syntax seen in the <controls:SfDataSourceExt>.}}
{{Hint|Note that the Converter seen in the 'EXP' EvalExpressionParameter in Xamarin is 'StringFormat', which is different than in UWP.}}
</tab>
</tabs>

The EvalExpression Expression first checks whether the TextBox input is empty (as this would otherwise incorrectly be considered a filter input, whereby the property should be empty) and if so returns the unfiltered list (expression outcome hardcoded to 'true'), otherwise, applies the filter (expression outcome is taken from string constructed in ConverterParameter of 'EXP').

There are two important details of the EvalExpressionParameter to note here:
* The "ElementName=NameInput" / "x:Reference NameInput" should match exactly to the name of your Input control.
* The Item.Values["NAME"] should be adapted, by changing NAME to the property that should be filtered by this input.

=== TextBox / Entry ===
The input field is just a basic <Textbox> / <Entry> we will use to input the filter criteria value. The only important detail for this input control is the name, which must be passed back to the EvalExpressionParameter.
<br>
<br>
It will look like this:
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput"/>
</source>
</tab>
</tabs>

=== Items control ===
An items control will likely be used for displaying filtered results, such as <controls:SelectionBoundListView> for UWP & [[Xamarin_XAML#Performance|SfListViewExt]] for Xamarin:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:SelectionBoundListView
x:Name="FilterQueryList"
ItemsSource="{StaticResource FilterView}" />
</source>
</tab>

<tab name="Xamarin">
<source lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
ItemsSource="{Binding DisplayItems, Source={StaticResource FilterView}}" />
</source>
</tab>
</tabs>
<br>

== Multiple Dynamic (User Inputs) Criteria ==
It is likely that the customizing is required to process multiple user inputs for the same filter. In this case, the EvalExpression must be adapted to combine the inputs (most likely using an AND relation, for a 'filtering-down' effect), as well as to deliver the full list when nothing is inputted.
A <Textbox> / <Entry>, and an EvalExpression, will be required for every additional property, as well as a final EvalExpression to combine them.

The EvalExpressions should be amended as follows:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=NameInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DescInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DescInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["NAME"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference NameInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="Desc_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DescInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Values["DESCR"].ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference DescInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="NAME +"&&"+ DESC">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
<br>

The above example shows how to check for inputs to either property, NAME and DESCR, then use an additional EvalExpression to create the expression string that combines them. For each additional property you need to:
* Create an EvalExpression that checks whether the text input is null or empty, and if not, returns the desired expression EXP.
* Add each EvalExpression (Name_FilterExpression, Desc_FilterExpression) to the 'main' one (FilterExpression) as Parameters, combined using the escaped '&&' concatenation symbols.

{{Attention|Due to the escaped syntax required in the Expression, <source lang = "xml">+"&&"+</source> is the correct syntax required to concatenate filter expressions together.}}

Once the additional input controls have been created, processed in their own EvalExpressions, referenced as EvalExpressionParameters and the "FilterExpression" EvalExpression has been adapted as shown, the filter should already function as required; the Collection Filters and Items Controls do not need to be adapted.
<br>

=== One Input To Filter Multiple Properties ===
Since we have control over how the input is matched against the properties, is possible to use the same input to filter against multiple properties, for example, both Title and SubTitle. This keeps the UI lean with less elements to clutter the layout, and the user is not forced to think about which input relates to which field. The downside, of course, is that the search will be slightly less refined.
This is achieved easily as shown:

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=FilterInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=FilterInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT " Value="{Binding ElementName=Title_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding ElementName=SubTitle_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Title_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Title.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="SubTitle_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference FilterInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.SubTitle.ToLower().Contains("{0}".ToLower())==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference FilterInput}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="TIT +"||"+ SUB">
<controls:EvalExpressionParameter Name="TIT" Value="{Binding Source={StaticResource Title_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="SUB" Value="{Binding Source={StaticResource SubTitle_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

{{Attention|Note the different operator required in this case. Unless your object has the same Title ''and'' SubTitle, there will be no match found unless the FilterExpression is amended to an Or relationship.}}

<br>

== Combining Dynamic (User Inputs) and Static (Predefined) Criteria ==
A common use of the Collection Filter is to filter child lists based on one or multiple properties, such as MetaDefinition.UID or a certain status, to present groups of specific object types. Therefore, it is likely that a customizing may require hardcoded filter criteria, combined with user input, if any is provided.

The following describes how to implement such a scenario in XAML, again using [[:Category:Multiple Dynamic (User Inputs) Criteria]] as a starting point.

<tabs>
<tab name="UWP">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding ElementName=Desc_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower()=="6f73cde9-ed38-4cbd-8ca1-4597cc2ae621"</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ DESC +"&&"+ STAT" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="DESC" Value="{Binding Source={StaticResource Desc_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT" Value="{StaticResource Static_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

Once one or multiple EvalExpressions have been added to process each input (such as Name_FilterExpression, Desc_FilterExpression), the remaining predefined filter criteria, in this example, filtering for a specific MetaClass by UID, can be added as an x:String, or directly in the EvalExpression paramerter, though the first approach is recommended, for better readability.

{{Attention|The above syntax only works for individual static string filters. If you need to chain multiple hardcoded filters, such as filtering in several UIDs, they need one String resource each, and must be added to the FilterExpression expression individually as in the below example.}}

=== Multiple Static Criteria ===
Experimentation has shown that the dynamic filter struggles to combine a single string made of multiple expressions, with additional expressions via the FilterExpression. However, it is still possible to combine user inputs and multiple static criteria, simply by breaking up the static criteria into separate strings.

Of course, when for example filtering various MetaDefinitions.UIDs, the '&' (and) comparison condition is no longer appropriate, as there will never be matches for multiple of these UIDs that returns a true result. In these cases, the comparison condition needs to be set to '||' ([[HowTo:Implement_Custom_Filtering#.27Or.27_Operations|Or]]).
The below example shows the correct syntax.

<tabs>
<tab name="UWP">
<br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String></source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("8ca1-4597cc2ae621-6f73cde9-ed38-4cbd")==true</x:String>

<controls:EvalExpression x:Name="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding ElementName=Name_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin"><br>
⛔️ '''Don't Do:'''
<source lang = "xml"><x:String x:Key="Static_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true && Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>
</source>
<br>
✅ '''Instead Do:'''
<source lang = "xml">
<x:String x:Key="Static1_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("6f73cde9-ed38-4cbd-8ca1-4597cc2ae621")==true</x:String>
<x:String x:Key="Static2_FilterExpression">Item.Content.MetaDefinition.UID.ToString().ToLower().Equals("4597cc2ae621-6f73cde9-ed38-4cbd-8ca1")==true</x:String>

<controls:EvalExpression x:Key="FilterExpression" Expression="NAME +"&&"+ STAT1 +"||"+ STAT2" Context="{Binding}">
<controls:EvalExpressionParameter Name="NAME" Value="{Binding Source={StaticResource Name_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="STAT1" Value="{StaticResource Static1_FilterExpression}" />
<controls:EvalExpressionParameter Name="STAT2" Value="{StaticResource Static2_FilterExpression}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>
{{Hint|Note that the above strings make use of the .Equals() method, which is an alternate option to the more commonly seen <nowiki>'Item.Content.MetaDefinition.UID.ToString().ToLower()==...</nowiki>'}}
<br><br>

== Other Property Types ==

=== Filtering an INT / Double ===
Though the string comparison works mostly the same for a Int / Dbl, you additionally have to include a .ToString() method to the EXP EvalExpressionParameter of that property's individual EvalExpression for it to evaluate:
<source lang = "xml">
ConverterParameter='Item.Values["INSTRUCTIONID"].ToString().ToLower().Contains("{0}".ToLower())==true'
</source>
<br>

=== Filtering a Boolean (CheckBox) ===
To process a Boolean filter, the expression needs to be slightly amended, due to the different type of filter match criteria that is required.

Note that the below implementation returns all items by default (ie. when the CheckBox is unchecked), and returns only True matches when the CheckBox is checked. This functionality is designed to align with string input, where no filtering occurs for each string until something is entered into the corresponding text input box.
<br>
<source lang = "xml">
Note that this example uses UWP xaml syntax:

<controls:EvalExpression x:Name="Bool_FilterExpression" Expression="(INPUT==false) ? "true==true" : EXP" Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=CheckBox, Path=IsChecked, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Values["MP_BOOL"]=="{0}"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=CheckBox, Path=IsChecked}" />
</controls:EvalExpression>
</source>
<br>

* The individual EvalExpression for a Boolean filter match needs to be amended as follows:
** The INPUT can never be null, as the IsChecked property is either True or False. Therefore we can remove the Null or empty test, and instead, check whether the CheckBox is checked or not. IsChecked=False should 'escape' the expression, and return all items (or, not contribute to the overall filtering).
* The EvalExpressionParameter 'EXP' similarly can be simplified, as it does not need to make a string match with .Contains, but simply check whether the property value matches to True or False.
<br>
Changes only need to be made to the individual EvalExpression. The "FilterExpression" that joins all individual expressions does not need to be amended, other than the regular additional EvalExpressionParameter, and updating the expression accordingly.

<br>

=== Filtering a GUID Property ===
The expression string seen in the "EXP" command parameters shown above compare a user input with the value stored in Values[MP_PROPERTY], of the requested property. However, in certain cases, it may not be adequate to search in Values[MP_PROPERTY], such as when the property is a GUID. This is because Values[LK_GUID_PROPERTY] returns the UID value of the linked object, whereas Properties.VisibleItems[LK_GUID_PROPERTY].DisplayValue returns the human readable label associated with this linked object.

The solution is to rewrite the expression string to target the correct binding:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=NameInput, Path=Text, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference NameInput}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.Properties.VisibleItems["LK_GUID_PROPERTY"].DisplayString.ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

A good way to inspect and test the target binding is to output it on the items UI, therefore on the ItemTemplate of your ListView, as well as to output the expressions that are being dynamically generated in your EvalExpressions, by binding the Result to the Text property of a <TextBlock> (UWP) or <Label> (Xamarin).
<br>
<br>

{{UnderConstructionStart}}
=== Filtering a DateTime Property ===
Filtering a DateTime property is more complex than other properties, because one has to consider both the input, and the type of filtering.

Input can be done both as freetext, and using a DatePicker. Freetext input has the downside that users have to take care to enter the correct string format (ie. yyyy/MM/dd), whereas the DatePicker outputs a DateTime string which can then be formatted for use in the EvalExpression. The DatePicker does however have certain downsides, chief of which being that it is not nullable, the current date is shown when no date has been selected, making the non-filtered UI indistinguishable from the filtered one.

Filtering can be done as a simple comparison, such as finding an object whose date matches the inputted date. However, it is also possible to ranges; either 'open', that is, dates before or after the user's selection, or 'closed', which is a date falling inside a range created by two user inputs.

==== Input ====
The input method is the first important consideration for filtering DateTime properties. A DatePicker is the generally accepted method. Textbox input is also possible, though users will need to correctly format their input to 'yyyy/MM/dd' (such as "2032/12/31") in order to achieve a valid comparison.

'''DatePicker'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<DatePicker x:Name="DatePicker" Tag="{Binding SelectedDate, ElementName=DatePicker, Converter={StaticResource StringFormatConverter}, ConverterParameter='{0:yyyy/MM/dd}'}" />
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<DatePicker x:Name="DateInput" />
<Label x:Name="DateString" Text="{Binding Path=Date, Source={x:Reference DateInput}, StringFormat='{0:yyyy/MM/dd}'}"/>
</source>
</tab>

{{Attention|In both cases, it is necessary that the format of the input matches the format of the property value, which will be explained more in the Comparison section below. In the above examples, this is applied in the Tag property (UWP) or through use of a secondary control (a Label in the Xamarin example).}}
</tabs>

'''Freetext'''
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="DateInput" PlaceholderText="Date"/>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="DateInput" Placeholder="Date"/>
</source>
</tab>

{{Attention|Remember that no matches will be found unless the date is inputted following a 'yyyy/MM/dd' format.}}
</tabs>

{{Hint|For greater control over the input format, it is also possible to provide multiple TextBoxes, which could then either be concatenated in an EvalExpression, or used to filter by the DateTime.Day/Week/Month values of the property individually, if such functionality fits the usecase.}}

<br>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Comparison ====
Since the EvalExpression approach utilizes string comparisons, not only is it necessary to format the input string, but the property value must also be formatted to match. The 'yyyy/MM/dd' format includes several measures to create the best conditions for comparing the two strings;
* months and days below the value of 10 cannot be a single digit, but must be padded with a preceding 0 in order to keep the string lengths equivalent; 2032/1/1 cannot be property compared with 2032/12/31 for example, as the strings are different lengths.
* putting the year and month first also improves the chance of a correct comparison, as a day 01 can be after a day 31 if the month and year are greater.

{{Attention|For the rest of this section, a DatePicker input is assumed.}}

'''Single'''

Comparison of a single date against a property value works the same way as other dynamic filters. Therefore it is sufficient to make use of the previously used .Contains() or .Equals() methods.
Remember that the Date attribute is not directly usable from the DatePicker, and it's formatted version received via the Tag attribute or an additional label is what is actually used by the EvalExpressions.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DatePicker, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=DatePicker, Path=Tag}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Path=Text, Source={x:Reference DateString}, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Path=Text, Source={x:Reference DateString}}" />
</controls:EvalExpression>
</source>
</tab>
</tabs>

'''Range'''
<br>
It is also possible to filter not for a specific date, but rather for all items whose property falls after or before the user input (depending on whether a 'Starting From' or 'Ending By' comparison is implemented. An 'open' range filter is created when only one value is inputted by the user, whereas a 'closed' range has a start and end date, and must fall on or in between these two.

For range comparison, we use the [https://learn.microsoft.com/en-us/dotnet/api/system.string.compareto?view=net-9.0 Microsoft .CompareTo method]. As documented there, this method outputs a -1/0/1 depending on the compared string's location in the range. Our expression can target one output for an 'exclusive' filter (in which the inputted date is not considered for the range), however, a more likely scenario is that the user wants the inputted date included in the filter. This is why the expression in the StringFormatConverter should be defined for start date as !=-1, and for end date as !=1; the instance should be not less than than the start date (where true would be an output of 0 or 1), and not greater than the end date (true = -1 or 0), respectively.

Similar to the earlier section on [[HowTo:Implement_Custom_Filtering#Multiple_Dynamic_.28User_Inputs.29_Criteria|multiple inputs]], separate EvalExpressions are used for each half of the range, meaning that the filtering also works (as an 'open Range' filter) when only one value is inputted by the user. If an open range filter is all that is required by the usecase, the second input and EvalExpression can simply be eliminated.

<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Start_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=StartInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=StartInput, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Name="End_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=EndInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding ElementName=EndInput, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Name="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding ElementName=Start_FilterExpression, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding ElementName=End_FilterExpression, Path=Result}" />
</controls:EvalExpression>
</source>

</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Start_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference StartString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="-1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference StartString}, Path=Text}" />
</controls:EvalExpression>
<controls:EvalExpression x:Key="End_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference EndString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.ToString("yyyy/MM/dd").CompareTo("{0}")!="1"'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding Source={x:Reference EndString}, Path=Text}" />
</controls:EvalExpression>

<controls:EvalExpression x:Key="FilterExpression" Context="{Binding}" Expression="START +"&&"+ END">
<controls:EvalExpressionParameter Name="START" Value="{Binding Source={StaticResource Start_FilterExpression}, Path=Result}" />
<controls:EvalExpressionParameter Name="END" Value="{Binding Source={StaticResource End_FilterExpression}, Path=Result}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note the .CompareTo method used in each half of the ranged filter expression; the start date comparison is <noWiki>!=-1</noWiki>, whereas the end date comparison <noWiki>!=1</noWiki>.}}
</tabs>

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

==== Individual DateTime Components ====
The DateTime property has the additional benefit of exposing components that can be used to refine filtering.

[[Developer_Mode]] reveals the members available under the binding path; <source lang = "xml">PropertyItems["DATETIME"].Value</source>
These include; Date, Day, DayOfWeek, DayOfYear, Hour, Millisecond, Minute, Month, Ticks, TimeOfDay, and Year.

These can be used in the EvalExpressionParameter as a binding in the custom expression string, as follows, and can even be used in separate filters to search individual components of the date seperately (for example, to filter by a particular month, year, or even day of the week).
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding ElementName=DateInput, Path=Tag, Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().Contains("{0}".ToLower())==true'}" />
</tab>
<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding Source={x:Reference DayWeekInputString}, Path=Text, Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["DATE"].Value.DayOfWeek.ToString().ToLower().Contains("{0}".ToLower())==true'}" />
</source>
</tab>
</tabs>

<br>
<br>
{{UnderConstructionEnd}}

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]

== Adjustments ==
=== 'Or' Operations ===
All examples of multiple inputs in this article use an 'and' filter condition, where, if any inputs are entered, only items that match all inputs (NAME <b>and</b> DESC) are kept in the collection, to produce a 'filtering down' effect in the user interface.

If a less strict filter condition is required, the FilterExpression can be altered to have an 'or' condition, where all results that match NAME <b>or</b> DESC, but not necessarily both, are shown. To do so, simply change the concatenation syntax to return 'or' symbols (two pipes or '||'):
<source lang = "xml">
+"||"+
</source>

== Displaying a Count ==
To display the filtered count, use the following syntax:

<source lang = "xml">
"{Binding Path=Count, Source={StaticResource FilterView}}"
</source>

== Persisting Filter Values ==
{{UnderConstructionStart}}
One of the drawbacks of this method of filtering is the inability for the UI to 'remember' user inputs when they navigate away from the page. This is because this implementation of dynamic filters exists solely on the UI thread (that is, is defined in XAML only with no actual connection to the data, opposite to [[Property_Based_Content_Filters]], for example), which is re-rendered according to the xaml definition every time the page is loaded. This section describes how to implement a limited solution to this issue, the limitation being that values can currently only be persisted during the 'session', and are lost when the user closes the client.

This solution involves use of the StoreProfileParametersCommand to create key-value pairs (a simple list of items made up of a name and a value), which can then be read using the 'StoredProfileParameters[key]'. The StoreProfileParameterCommand accepts a CommandParameter with the format 'key=value', where 'key' represents the name of the key-value pair that can be used to reference it later (in the case below, "name"), and 'value' represents what string should be returned by referencing it (in this case, the Text attribute of the text field control).

When a user completes their input, we use the StoreProfileParametersCommand to create or update a key-value pair associated with a particular filter, instead of passively reading the value from the input as was done previously.

Furthermore, the associated StoredProfileParameter is fed back to the input control so that if any value is set for that particular key (ie. if a filter value has been created), it will be displayed on the input control. Otherwise, the input control will be reset when next loading the page, as was previously the case with dynamic filtering, whereas the StoredProfileParameter will be persisted, leading to a mismatch between the UI and filtering state.
<tabs>
<tab name="UWP">
<source lang = "xml">
<TextBox x:Name="NameInput" Text="{Binding StoredProfileParameter[name]}">
<interactivity:Interaction.Behaviors>
<core:EventTriggerBehavior EventName="LostFocus">
<core:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Text, ElementName=NameInput, Converter={StaticResource StringFormatConverter}, ConverterParameter='name={0}'}" />
</core:EventTriggerBehavior>
</interactivity:Interaction.Behaviors>
</TextBox>
</source>

Pay attention to which [https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.textbox?view=winrt-26100#events Event] is used to trigger the StoreProfileParameterCommand. The above example uses LostFocus, which fires when the user clicks out of the TextBox. Another possible choice is TextChanged, however, this means that the command will fire with every keystroke, which may reduce overall performance.
</tab>

<tab name="Xamarin">
<source lang = "xml">
<Entry x:Name="NameInput" Text="{Binding StoredProfileParameters[name]}">
<Entry.Behaviors>
<behaviors:EventHandlerBehavior EventName="Completed">
<behaviors:InvokeCommandAction Command="{Binding StoreProfileParameterCommand}" CommandParameter="{Binding Path=Text, Source={x:Reference NameInput}, StringFormat='name={0}'}" />
</behaviors:EventHandlerBehavior>
</Entry.Behaviors>
</Entry>
</source>

The Xamarin 'Completed' event fires when the user clicks the return button on their onscreen keyboard.
</tab>
{{Hint|StringFormatConverter/StringFormat is used to format the key-value pair as required by the StoreProfileParameterCommand. The key is hardcoded into the formatted string as, for example <noWiki>'name={0}'</noWiki>. The dynamic value, in this case whatever is inputted in the text field when the edit is completed, replaces the <noWiki>{0}</noWiki> tag when the binding is evaluated (ie. when the command is executed).}}
</tabs>

In this implementation, the EvalExpression also needs to be adapted to check whether a particular filter value exists within the StoredProfileParameters list, instead of simply whether the associated input control has a value or selection:
<tabs>
<tab name="UWP">
<source lang = "xml">
<controls:EvalExpression x:Name="Name_FilterExpression" Context="{Binding}" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormatConverter}, ConverterParameter='Item.PropertyItems["NAME"].ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

<tab name="Xamarin">
<source lang = "xml">
<controls:EvalExpression x:Key="Name_FilterExpression" Expression="(INPUT==null||INPUT=="") ? "true==true" : EXP " Context="{Binding}">
<controls:EvalExpressionParameter Name="EXP" Value="{Binding StoredProfileParameters[name], Converter={StaticResource StringFormat}, ConverterParameter='Item.PropertyItems["NAME"].Value.ToString("yyyy/MM/dd").Contains("{0}")==true'}" />
<controls:EvalExpressionParameter Name="INPUT" Value="{Binding StoredProfileParameters[name]}" />
</controls:EvalExpression>
</source>
</tab>

{{Hint|Note how the EvalExpressionParameters have been adapted to reference a StoredProfileParameter, rather than the input control.}}
</tabs>

=== Item Selection ===
Filter value persistence works also when the user input method is to select an item from a picker.

<tabs>
<tab name="Xamarin">
<source lang = "xml">
<controls:PickerExt
x:Name="ExamplePicker"
ItemsSource="{Binding Children.Items[0].PropertyItems[PROPERTY].MetaProperty.SelectiveList, Converter={StaticResource SelectiveListToItems}, TargetNullValue='', FallbackValue=''}"
ItemDisplayBinding="{Binding DisplayText}"
SelectedValuePath="Value"
SelectedValue="{Binding StoredProfileParameters[key]}"
SelectionChangedCommand="{Binding StoreProfileParameterCommand}"
SelectionChangedCommandParameter="{Binding SelectedItem.Value, Source={x:Reference ExamplePicker}, StringFormat='key={0}'}"/>
</source>
</tab>
</tabs>

{{UnderConstructionEnd}}

== Known Issues ==
=== Text Input in ListView Header Template ===
This implementation will not work when parts of it, such as the Input fields, are hosted in a ListView header or footer template, as this content is not readable by the rest of the page and will return a "Can not find the object referenced" parsing error.

To workaround this, you need to move the Input control out of the header template.

=== Troubleshooting ===
* Everything looks correct but filtering returns no results:
** Ensure that the string you are trying to filter by matches what is returned as the DisplayValue.
** If the property is a INT / DBL (Integer or Double) type: The string comparison doesn't work directly with non-string types. Check the [[HowTo:Implement_Custom_Filtering#Other_Property_Types|Other Property Types]] section.
** If filtering a DateTime property, ensure the formatting of the input matches that of the property value in the EXP string.
** If filtering a GUID property, ensure the same values are compared; DisplayString if the user is inputting readable text, UID if the user has selected an item from a list.

== See also ==
* [[XAML]]
* [[XAML_Tips]]
* [[Xamarin_XAML]]

[[Category:Client|Custom Filtering]]
[[Category:Filtering|Custom Filtering]]
[[Category:Styling|Custom Filtering]]
[[Category:WinX|Custom Filtering]]
[[Category:XAML|Implement Custom Filtering]]
[[Category:Xamarin|Custom Filtering]]