UBIK Wiki / Augmensys - User contributions [en]

Multi Select (UBIK Client)

2026-08-13T13:54:56Z

REP: /* Editing common properties of selected items (UWP only) */

The Multi Select mode aims to improve the efficiency of performing actions on a large number of selected objects (Mobile & UWP), as well as changing property values for a large number of selected objects (UWP only). Editing property values for a large number of objects was known in some previous UWP versions as Mass Editing. Currently, the Multi Select mode is available for lists of children (including task and query objects) and documents.

== Activating the multi select mode ==

<tabs>
<tab name="UWP">
Clicking on a Multi Select button, which will appear when hovering over a list, activates the Multi Select mode. A panel at the left side gets displayed.
</tab>

<tab name="Mobile">
The Multi Select mode gets enabled by holding (long tapping) an item. As soon as it is active, a panel on the bottom gets displayed.
</tab>
</tabs>

In XAML code, you can use <code>ListViewModel.BulkOperation.ToggleMultiSelectCommand</code> to (de)activate the multi select mode.

== Multi select panel ==

<tabs>
<tab name="UWP">
The header displays the count of the currently selected items and three buttons.
The first one is for selecting all items, the second for deselecting all items at one click. The {{key press|x}} button closes the panel and deactivates the Multi Select mode.
Further, the panel contains two tabs.
The "properties" tab displays all common editable properties of the selected items. If none are selected, or if the selected items don't share any common properties, it will remain empty.
The "other options" tab contains buttons to perform actions on all selected items.
</tab>

<tab name="Mobile">
The Multi Select panel in the Mobile client is located at the bottom.
It displays the count of selected items, command buttons for Copy, Discard, Delete and Download actions and a close button to deactivate the Multi Select mode.
</tab>
</tabs>

[[File:UBIKWinXUI_MultiSelect1.JPG|thumb|Multi Select mode (UWP)]]

{{Hint|Note: Please only use the buttons in the Multi Select Panel to perform actions on the selected objects. Others, like content area / context menu button actions are still related to the content page and do not work for the selected objects.}}

For the current usecase and the standard client, the Multi Select mode can be activated for Document and Children objects in parallel, hence when activating the Multi Select mode in the Children tab and then switching to Documents tab, it is possible to enable a separate Multi Select panel there.

By navigating away from the related content page, all active Multi Select modes get deactivated automatically.

== Selection ==

[[File:UBIKCPLXUI_MultiSelect1.JPG|thumb|Multi Select mode (Mobile)]]

By default, all objects are deselected when the Multi Select Mode gets invoked. Items can be selected by tapping on them. Therefore, navigating into an object in the list by tapping on it is no longer available. To be able to navigate again, the Multi Select mode needs to be turned off.

To select or deselect all items, <code>ListViewModel.BulkOperation.SelectAllCommand</code> or <code>ListViewModel.BulkOperation.DeselectAllCommand</code> can be used as command binding. These options are currently not presented in the standard Mobile UI.

In UWP, there are some additional selection related options besides "Select All" and "Deselect All". Selecting or deselecting a bunch of items in a row can be achieved by holding shift and first clicking on the first required item and then clicking on the last required item.

== Performing actions on selected items ==

The following actions are currently available in Multi Select mode:
* Copy / Paste
* Download Branches
* Discard Content
* Delete Content
* Download and Checkout (*)
* Checkout (*)
* Release (*)
* Revert local changes (*)

Actions marked with (*) are currently not presented in the standard Mobile UI. But they can be easily customized in XAML code with the following commands.

=== Copy and paste ===
To copy multiple branches, the <code>ListViewModel.BulkOperation.CopyBranchesCommand</code> can be used without any additional CommandParameters.
The <code>ContentViewModel.PasteBranchCommand</code> already supports pasting multiple branches, therefore, it can be used to paste the previously copied objects. To clarify, the UI (Mobile & UWP) does not include pasting content into the selected objects, rather pasting multiple, previously copied branches into one object. This can be done eg. via the Paste option in the Context Menu.

=== Download branches ===
To download multiple branches, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="BranchDownloadCommand"</code> as CommandParameter can be used.

=== Discard content ===
To discard selected objects, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="DiscardContentCommand"</code> as CommandParameter can be used.

=== Delete content ===
To delete selected objects, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="DeleteContentCommand"</code> as CommandParameter can be used.

=== Download and checkout ===
This can be achieved by using the command for downloading, just with an additional KeyValueParameter to set the <code>Key="CheckOut"</code> to "True" as CommandParameter:
<source lang = "xml">
<Button ... Command="{Binding ListViewModel.BulkOperation.InvokeOnItemsCommand}">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="Command" Value="BranchDownloadCommand" />
<controls:KeyValueParameter Key="CheckOut" Value="True" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

=== Checkout ===
To checkout selected objects, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="CheckOutContentCommand"</code> as CommandParameter can be used.

=== Release ===
To release selected objects, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="ReleaseContentCommand"</code> as CommandParameter can be used.

=== Revert local changes ===
To revert local changes on objects, <code>ListViewModel.BulkOperation.InvokeOnItemsCommand</code> with a KeyValueList containing <code>Key="Command"</code> and <code>Value="RevertLocalChangesCommand"</code> as CommandParameter can be used.

== Editing common properties of selected items ==

{{Attention|Currently not presented in the standard Mobile UI. But they can be easily customized in XAML code by binding to the BulkOperation.Properties.Items collection. You can use the UWP standard template UBIKMultiSelectPanel.xaml as a guide.}}

When selecting or deselecting objects, the commonly shared properties on the left side are constantly updated during that process.

{{Hint|For such a property, if all selected objects share the same property value, that value is displayed as it is; Otherwise, "..." is displayed to indicate the presence of various values.}}

Once a user clicks/taps on such a property, an editor dialog is shown and the user can enter values just like when editing properties of single objects. However, when the user finishes editing and confirms the dialog, the value is saved to that property of all selected objects immediately.

{{Hint|If the property being edited has various values, a default value (instead of the actual ones) is shown in the editor. E.g. empty for string type, false for boolean type, etc.}}

Further editing of Link properties is currently not supported for multiple objects. Although the related button in the Guid editor dialog is clickable, it is currently inoperable. Also the ''Skipping the dialog'' feature (see [https://wiki.augmensys.com/index.php?title=Editors#Guid_editor| Guid Editor Wiki]) is currently not supported in Multi Select mode.

{{Attention|Mass editing is currently not supported for Properties containing [[Active_List_Client|Active Lists]].}}

[[Category:Client|Multi Select (UBIK Client)]]
[[Category:Mobile|Multi Select (UBIK Client)]]
[[Category:Version 4.3|Multi Select (UBIK Client)]]
[[Category:WinX|Mass Edit (UBIK WinX)]]
[[Category:XAML|Multi Select (UBIK Client)]]

== Multi select for filtered lists ==

In the standard UI, multi selection targets the original unfiltered lists. However, those lists are often presented in several filtered lists in many cases. See content filtering in [[XAML_Changes_in_UBIK_WinX_3.5#Filtering_by_expressions|UWP]] and in [[Xamarin_XAML#Content_filtering|Mobile]].

The multi select related XAML code (essentially <code>ListViewModel.BulkOperation</code>) in the standard UI can not be used directly in such scenarios. Because all filtered lists share the same original source list (<code>ListViewModel</code>). If the multi select feature is turned on from the original source list, all filtered lists will be affected.

For example, a source list can be divided into two filtered lists, one for finished tasks and the other for the unfinished ones. If you use the <code>ListViewModel.BulkOperation.SelectAllCommand</code>, it will select all tasks even though in the UI it will appear as if only those finished/unfinished are selected.

To avoid such a situation, the multi select feature should be turned on from the filtered lists instead. This means the following types:
* UWP: ListCollectionView;
* Mobile: SfDataSourceExt.

Here's also an example of multi select related XAML code adapted for a filtered list.

<tabs>
<tab name="UWP">
<source lang = "xml">
<Grid
xmlns:cv="using:UBIK.WinX.UI.CollectionView"
xmlns:controls="using:UBIK.WinX.Controls"
xmlns:interactivity="using:Microsoft.Xaml.Interactivity"
xmlns:core="using:Microsoft.Xaml.Interactions.Core">
<Grid.Resources>
<x:String x:Key="FilterExpression">Item.Header.ToLower().Contains("1")==true</x:String>
<cv:ListCollectionView x:Key="FilteredList" Expression="{StaticResource FilterExpression}" ItemsSource="{Binding Children.Items}" />
</Grid.Resources>

...

<ContentControl
...
ContentTemplate="{Binding TemplateService[UBIKMultiSelectPanel]}"
DataContext="{StaticResource FilteredList}"
Visibility="{Binding BulkOperation.ItemSelectionMode, Source={StaticResource FilteredList}, Converter={StaticResource EqualToVisConverter}, ConverterParameter=Multiple, FallbackValue=Collapsed, TargetNullValue=Collapsed}">
</ContentControl>

...

<controls:SelectionBoundListView
IsItemClickEnabled="False"
ItemsSource="{StaticResource FilteredList}"
SelectionMode="{Binding BulkOperation.ItemSelectionMode, Source={StaticResource FilteredList}, Converter={StaticResource ChildItemSelectionModeToListViewSelectionModeConverter}}">
<interactivity:Interaction.Behaviors>
<core:EventTriggerBehavior EventName="SelectionChanged">
<core:InvokeCommandAction Command="{Binding BulkOperation.ItemSelectionChangedCommand, Source={StaticResource FilteredList}}" InputConverter="{StaticResource SelectionChangedEventArgsConverter}" />
</core:EventTriggerBehavior>
</interactivity:Interaction.Behaviors>
</controls:SelectionBoundListView>

...

<Button
...
Command="{Binding BulkOperation.ToggleMultiSelectCommand, Source={StaticResource FilteredList}}"
Visibility="{Binding BulkOperation.ItemSelectionMode, Source={StaticResource FilteredList}, Converter={StaticResource EqualToVisConverter}, ConverterParameter=None}" />

</Grid>
</source>
</tab>

<tab name="Mobile(Xamarin)">
<source lang = "xml">
<Grid
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Header.ToLower().Contains("1")==false</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>

...

<controls:SfListViewExt
...
ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}"
SelectionGesture="Tap"
SelectionMode="{Binding BulkOperation.ItemSelectionMode, Source={StaticResource FilteredList}, Converter={StaticResource SelectionModeConverter}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="SelectionChanged">
<behaviors:InvokeCommandAction Command="{Binding BulkOperation.ItemSelectionChangedCommand, Source={StaticResource FilteredList}}" Converter="{StaticResource SelectionChangedEventArgsConverter}" />
</behaviors:EventHandlerBehavior>
...
<behaviors:EventHandlerBehavior EventName="ItemHolding">
<behaviors:InvokeCommandAction Command="{Binding BulkOperation.ToggleMultiSelectCommand, Source={StaticResource FilteredList}}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>

...

<ContentView
...
BindingContext="{StaticResource FilteredList}"
ControlTemplate="{StaticResource UBIKMultiSelectTemplate}"
IsVisible="{Binding BulkOperation.ItemSelectionMode, Converter={StaticResource EqualityToBool}, ConverterParameter=Multiple, FallbackValue=false, TargetNullValue=false}" />

</Grid>
</source>
</tab>
</tabs>

{{Hint|The critical part is that wherever the <code>BulkOperation</code> property is accessed, it must be accessed from the <code>FilteredList</code>, not the original unfiltered <code>Children.Items</code> collection. When all references have been updated, the only remaining reference to 'Children' should be in FilteredList, as the ItemsSource attribute.}}

[[Category:Client|Multi Select (UBIK Client)]]
[[Category:Mobile|Multi Select (UBIK Client)]]
[[Category:Version 4.3|Multi Select (UBIK Client)]]
[[Category:WinX|Mass Edit (UBIK WinX)]]
[[Category:XAML|Multi Select (UBIK Client)]]

Mobile XAML

2026-08-06T13:57:14Z

REP: /* Labels */

The User Interface of the Mobile Clients (Android, iOS, Windows) can be fundamentally customized using custom XAML definitions. This customization process is heavily influenced by the [[XAML|XAML Customization Process on the WinX Client]].

= Basics =
There are predefined XAML templates available that can be customized. If no customizing is found, the default templates will be used.

== Default XAMLs ==
All default XAML templates that can be customized are available through the Mobile Windows client. You need to go to the app settings and click the "Unpack default XAMLs" button.

== Differences to WinX/UWP ==
* Since it's based on the Mobile XAML dialect, you CANNOT use any existing XAML customizings for the WinX/UWP app;
* Namespace definitions must include the corresponding assembly names;
* XAML template files have the extension name of '''xamlx''' instead of '''xaml''';
* You can deploy only those resources that you want to customize. (This is also the case for newer versions of WinX/UWP. {{Version/WinXSince|3.6}})

= Overriding default XAMLs=
On Windows (WinX/UWP), the <code>[App Package Folder]/LocalState/xaml/</code> folder can be accessed by the user and the customized XAML files directly added. An alternative to this on all platforms (including Android, iOS, etc.) is to use the ''Import Customizing'' button in the app settings to import the templates, styles, images, etc. (file by file, or all files within a zip package). The changes should be reflected in the UI (except the current page) without restarting the app. After directly editing the customizings (Mobile Windows), you can also use the "Reload customizing" button without restarting the app.

In the following, we're going to override the default light theme color of the app:
* Unpack the default XAMLs;
* Pick and deploy the default UBIKThemes.xamlx to the '''xaml''' folder inside the ''LocalState'' folder;
* Open it with the text editor of your choice and remove everything within the '''ResouceDictionary''' except <code><Color x:Key="UBIKLightThemeColor">blue</Color></code>;
* Save the changes and reload. You should see changes successfully implemented.

{{Attention| For maintainability reasons, it's HIGHLY recommended to deploy only those XAML resources you want to override. For example, if you only want to customize the UBIKChildArea, don't deploy others like the UBIKMenuArea. If you only want to customize the UBIKChildItem, that's the only content you should include in the UBIKThemes.}}
<br>

== Custom Templates ==
Custom templates can be added, just like on the WinX/UWP client. Make sure to include all '''namespace definitions''' (as attributes of the '''ContentView''' tag), otherwise the custom template will not load.

Similar to the ''UBIKThemes.xamlx'' file, custom or overridden templates start with a <code><ContentView></code> tag containing all '''namespaces'''. <code><ContentView.Resources></code> takes a '''ResourceDictionary''' and contains resources like references to converters. Finally, <code><ContentView.Content></code> contains the actual layout content (it's best to start with a '''Grid'''). Again, don't forget to add namespaces that you need!

Templates can also be defined in ''UBIKThemes.xamlx''. In this case, they need to be added into the <code><ResourceDictionary></code> inside the <code><ContentView.Resources></code> template as a <code><DataTemplate></code>. Similarly, if you want to split up the templates into seperate files, you need to make sure to follow the steps mentioned above and get the content of the <code><DataTemplate></code> into the <code><ContentView.Content></code> tag.

{{Attention|Templates defined in separate files will override templates defined in the ''UBIKThemes.xamlx''!}}

=== Bindings in resources ===
When using bindings such as [[Xamarin_XAML#Content_filtering|this]] in a resource located in a custom template, it is necessary to place the template in a UBIKContentView.

{{Hint|Technically speaking, this is because bindable objects in the ResourceDictionary of a ContentView (the custom template) don't automatically inherit the BindingContext from the container/parent view. UBIKContentView is created to additionally do that.}}

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


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
<ContentView.Resources>
<ResourceDictionary>
<controls:SfDataSourceExt... ItemsSource="{Binding Children.Items}" />
</ResourceDictionary>
</ContentView.Resources>
...
</ContentView>


<ContentView...
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
...
<controls:UBIKContentView Content="{Binding [UBIKCustomView], Source={x:Static services:TemplateService.Instance}}" />
</ContentView>
</source>

== Adding Images ==
Images can't be loaded with the default '''Image''' tag, as the image is on different paths on each operating system.

Therefore, there's a custom '''FileImage''' that internally overrides the default ''Image'' with two custom parameters:
* '''FolderName''' ...The name of the '''folder''' in the '''local folder'''. Only the first level inside the ''LocalState'' folder seems to work.
* '''FileName''' ...The name of the '''file''' in the said folder.

Make sure to implement the proper namespace as well by adding
<code>xmlns:fimage="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> into the root item's attributes.

Then, the image can be loaded using:<br/>
<code><fimage:FileImage FileName="image.png" FolderName="xaml"/></code>

This snipped loads the image called '''image.png''' located in the '''xaml''' folder inside the ''LocalState''.

Furthermore, the ''FileImage'' tag doesn't seem to support most attributes. Therefore place it inside a '''Grid''' to achieve a perfect layout.
<br>

== Custom Icons ==
Moved to article [[XAML_Tips#Custom_Icons]].
<br>

== Converters==
:''Main Page: [[Converters_In_Mobile]]''

They are used to convert specific data into some desired output, using custom logic.

Consider the following example:<br/>
A label saying ''There are no children items available!'' should only be visible if the number of children-items is 0.

= Advanced =

== Feature related ==

=== Customizing Menu Button {{Version/XamarinSince|4.6.0}} ===

For the Mobile Client, it is possible to show/hide the '''Menu button''' of the client.<br>
To customize the visibility of the '''Menu button''' you have to edit the default XAML '''Themes''' file.

* Search for "'''ShowMenuToolBar'''" in the Themes file.
<br>
If there isn't any "'''ShowMenuToolBar'''" in your XAML Themes file, you just have to create one, like this:

<source lang = "xml">
<x:Boolean x:Key="ShowMenuToolBar">true</x:Boolean>
</source>

* Set the value to "true" to show the '''Menu button''' (default value).
* Set the value to "false" to hide the '''Menu button'''.

<gallery widths="300" heights="500">
File:menu_button_show.png|Menu Button shown
File:menu_button_hiddenV3.png|Menu Button hidden
</gallery>

=== Content filtering ===
For the Mobile clients, an "SfDataSourceExt" type is available for filtering list of items using defined expressions.<br />
The following example demonstrates how to filter for child items having certain property values. The filtered list and its count can be displayed in the UI.<br />
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<ContentView
xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"
...>
<ContentView.Resources>
<ResourceDictionary>
<x:String x:Key="Expresssion">Item.Values["MP_YEAR"].Contains("2019")</x:String>
<controls:SfDataSourceExt x:Key="FilteredList" Expression="{StaticResource Expresssion}" ItemsSource="{Binding Children.Items}" Unloaded="{Binding SkipFiltering}" />
</ResourceDictionary>
</ContentView.Resources>
<StackLayout Orientation="Vertical">
<Label Text="{Binding DisplayItemsCount, Source={StaticResource FilteredList}}" />
<controls:SfListViewExt ItemsSource="{Binding DisplayItems, Source={StaticResource FilteredList}}" />
</StackLayout>
</ContentView>
</syntaxhighlight>

==== Notes on using bindings in ResourceDictionary ====
In the example shown above, you can see <code>{Binding Children.Items}</code> is used. For this to work, the SfDataSourceExt control inside the ResourceDictionary must inherit the binding data context properly.
* In this case, that data context comes from where this template (UBIKChildArea.xamlx) is used, namely the UBIKContentArea.xamlx;
* When referencing this template in a ContentView control, the binding data context is '''NOT''' automatically inherited by the controls inside the ResourceDictioinary;
* That's why we use a UBIKContentView control instead. You can find its example usage in the default UBIKContentArea.xamlx template.

=== Search ===
In the default UBIKMenuArea.xamlx (where the search UI is hosted), there are two commands associated with two events. See below.
<syntaxhighlight lang="xml">
Mobile(Xamarin):

<SearchBar ...>
<SearchBar.Behaviors>
<behaviors:EventToCommandBehavior
Command="{Binding FreeTextSearchCommand}"
CommandParameter="{Binding Path=Text, Source={x:Reference SearchField}}"
EventName="SearchButtonPressed" />
<behaviors:EventToCommandBehavior Command="{Binding DelayedFreeTextSearchCommand}" EventName="TextChanged" />
</SearchBar.Behaviors>
</SearchBar>
</syntaxhighlight>
<br />
The one for <code>SearchButtonPressed</code> is responsible for executing searches after the user confirms the input (e.g. pressing {{{keypress|Enter}}} or the search button).
<br />
The one for <code>TextChanged</code> is responsible for the "search as you type" behavior. Namely it triggers an automatic search shortly (half second) after the user stops changing the text in the search bar. It can be turned off by simply removing that particular behavior.

=== DisplayViewCommand ===
This command can be used to [[Custom_View_(Client)|display custom views]].

=== Flashlight {{Version/MobileSince|5.1.0}} ===
For the Mobile clients, it is possible to control the system flashlight via customizing and switch it on or off.

The available properties can, for example, be bound to a Switch or CheckBox, as demonstrated below. These properties allow you to:
* Determine whether the device supports flashlight functionality (IsFlashSupported)
* Check whether the flashlight is currently turned on or off (IsFlashEnabled)
* Toggle the flashlight on or off via user interaction (SwitchFlashLight)
<br/>
If an attempt is made to enable the flashlight on a device that does not provide flashlight support, no action is performed.

{| class="wikitable"
! Switch
! controls:CheckBox
|-
|
<syntaxhighlight lang="xml">
<Switch IsVisible="{Binding AppStatus.IsFlashSupported}"
IsToggled="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"/>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:CheckBox
x:Name="PropertyToggle"
CheckSymbol="🔦"
IsVisible="{Binding AppStatus.IsFlashSupported}"
IsChecked="{Binding AppStatus.SwitchFlashLight, Mode=TwoWay}"
Style="{DynamicResource UBIKIconToggleButton}"
SymbolSize="20">
<controls:CheckBox.Triggers>
<DataTrigger
Binding="{Binding AppStatus.IsFlashEnabled}"
TargetType="controls:CheckBox"
Value="True">
<Setter Property="Background" Value="{StaticResource UBIKAccentColor}" />
</DataTrigger>
</controls:CheckBox.Triggers>
</controls:CheckBox>
</syntaxhighlight>
|-
|}

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

== Performance ==
To get a good performance in the app UI when using your Xaml customizings, it is recommended to try the following.
* Always keep your UI structure simple. Choose the most efficient layouts for the scenarios and avoid unnecessary UI elements. Please refer to [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#choose-the-correct-layout "choose the correct layout"] and [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/deploy-test/performance#reduce-the-visual-tree-size "reduce the visual tree size"];
* Turn on [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-compression layout compression] on wrapping elements that don't have any visual parameters set (reasons stated in the linked documentation).
{{Hint|There is a default "HeadlessLayout" style available in the app you can use on elements such as Grids, StackLayouts, ContentViews, etc. It turns on [[Xamarin_XAML#Layout_compression_examples|layout compression]] on the applied elements in Xamarin.Android (since we find it not worth the effort in Xamarin.iOS).}}
{{Attention|If possible, one should always favor designing the UI with less wrapping elements over turning on layout compression on unnecessary ones.}}

=== General performance tips ===
* Reduce number of views per page
* Don’t bind things if they could be set static easily
* If you do not change the default, don’t set it explicit. For example, [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.StackLayout.Orientation?view=xamarin-forms Orientation of StackLayout] is “Vertical” by default. No need to set it manually if you don’t want to change it.
* Transparency is expensive.
* Do not put ListViews into ScrollViews.
* To stack elements, create a grid and add them to the same cell one after another. It’s cheaper than RelativeLayout.
* Use Margins instead of Paddings.

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

=== Layouts ===
* Choose correct Layout, e.g. no need to add a StackLayout if it only has 1 child.
* [https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/layout-options LayoutOptions].Fill or .FillAndExpand are best choice in most cases. And they are already default, so no need to set.
* Autosize of rows and columns in grids should used as few as possible.
* RelativeLayout is very expensive. Try to avoid.
* In StackLayout, make sure there is only 1 LayoutOptions Expand.

=== Labels ===
* Use [https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/multibinding?view=net-maui-10.0 MultiBinding] instead of multiple labels.
** Avoid Label.FormattedText on ItemTemplates as this can cause issues in lists with many items.
* Use [https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.linebreakmode?view=xamarin-forms Linebreakmode] NoWrap (which is already the default).
* Avoid [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Label.VerticalTextAlignment?view=xamarin-forms VerticalTextAlignment]. Anyway, if needed, use VerticalTextAligment instead of
VerticalOptions.
* Use the "TextTransform" attribute to convert the value of the "Text" attribute to either uppercase or lowercase.
<syntaxhighlight lang="xml">
<Label
TextTransform="Uppercase"
Text="{Binding Properties.AllItems[DESCR].DisplayValue}" />
</syntaxhighlight >

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

=== Images ===
* Provide images in optimized width and size. Provide multiple resolutions for different usage.
* Set [https://docs.microsoft.com/en-us/dotnet/api/Xamarin.Forms.Image.IsOpaque?view=xamarin-forms IsOpaque] to true if image is opaque.

=== Layout compression examples ===
<syntaxhighlight lang="xml">
<ContentView ControlTemplate="{DynamicResource ChangedSymbol}" Style="{DynamicResource HeadlessLayout}" />
</syntaxhighlight>
The code above removes one wrapping element added automatically by the ContentView and demonstrates a good reason to use layout compression because it can not be avoided otherwise.
<syntaxhighlight lang="xml">
<Grid Margin="2" Style="{DynamicResource HeadlessLayout}">
<Label Margin="5" Text="{Binding Title}" />
</Grid>
</syntaxhighlight>
This example, on the other hand, demonstrates a bad usage of layout compression because it can be easily achieved by better designs such as using only the Label with a merged margin.

Sometimes the content inside a compressed layout appears on a wrong z-index level. For eample:
<syntaxhighlight lang="xml">
<BoxView CornerRadius="14" HeightRequest="28" WidthRequest="28" Color="Red" />
<ContentView ControlTemplate="{DynamicResource Badge}" Style="{DynamicResource HeadlessLayout}">
<Label Text="{Binding Title}" />
</ContentView >
</syntaxhighlight>
According to the order of the BoxView and the Label, the latter should appear on top of the former (later ones have higher z-index levels). However, this can be disturbed by layout compression, causing the exact opposite.
In this case, you can add a <code>xmlns:android="clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core"</code> namespace to your Xaml file and manually elevate the Label by specifying <code>android:VisualElement.Elevation="X"</code> on it accordingly (X is the delta of the z-index level you want).

=== SfListViewExt ===
For performance reasons, we created an extended version of the Syncfusion SfListView control and it should be used for all lists in customizings. You need to add a namespace like <code>xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL"</code> to your Xaml file and use it like <code><controls:SfListViewExt ... /></code>.
{{Hint|Technically speaking, SfListViewExt informs item view models when their corresponding item views appear on / disappear from the screen. This way, view models can skip a lot of unnecessary work (on the UI) when their views are not visible. '''If SfListView is used instead, the item views will not reflect content changes until the page is reloaded/refreshed.'''}}

It is possible to configure the ListView, that the ScrollPosition is remembered when navigating away from the page, to do so, the property RembemberScrollPosition needs to be set to true. If unset, the value defaults to false and the scroll positions are not remembered.

<syntaxhighlight lang="xml">
<controls:SfListViewExt RememberScrollPosition="True"/>
</syntaxhighlight>

When using multiple Lists on one page (e.g. in a TabbedView), it is necessary to set the AutomationId property uniquely for each list on the page, to support the remembering of the ScrollPosition.

=== Delay and LazyLoading ===
{{Attention|Although both properties can be set in XAML on the two controls, this should not be done. When both the LazyLoading and Delay properties are set, the Delay property is ignored in the code-behind, as otherwise it could lead to unexpected behavior and, in the worst case, result in performance degradation.}}

==== Delay in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====
More complex UIs create a delay in rendering which leads to a feeling of "unresponsiveness" when navigating through the client. This is because the app loads and displays everything at once, leading to a larger delay between triggering navigation and completion of page loading.

While the complexity of the UI directly affects the time taken to render it, the experience of responsiveness can be somewhat improved by actually adding a delay between the loading of the content page, and actual data content (properties, children, etc). By not loading both at once, resources are freed up in the app, leading to a quicker loading of the basic page. The content then loads in at its normal speed.

Starting from version 5.1, a small delay was introduced in the content heavy pages (child page, document page and query page). However, additional delays can also be applied to the custom UI at will, using a new property added to two existing controls used to insert UI templates: UBIKContentView and ContentControl. You can specify a delay (in milliseconds) on both controls so that the content of them is loaded after that amount of time. Examples are shown below.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<controls:UBIKContentView
Delay="50"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:ContentControl
Delay="50"
ContentTemplate="{Binding [UBIKNavigationBar], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
|-
|}

{{Hint|The delay won't have any effect if you specify the Content of the UBIKContentView control instead of its Converter, because the Content is immediately laid out by the XAML framework that way. If you don't need a converter to determine the actual template name dynamically, you can still use the TemplateConverter and specify the template name like the following so that the delay applies.}}

<tabs>
<tab name="Delay applies ✅">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Converter="{StaticResource TemplateConverter}" ConverterParameter="UBIKChildArea" />
</syntaxhighlight>
</tab>
<tab name="Delay doesn't apply ❌">
<syntaxhighlight lang="xml">
<controls:UBIKContentView Delay="50" Content="{Binding [UBIKChildArea], Source={x:Static services:TemplateService.Instance}}" />
</syntaxhighlight>
</tab>
</tabs>

==== Lazy Loading in UBIKContentView and ContentControl {{Version/MobileSince|5.1}} ====

To further improve performance, it is now possible to apply LazyLoading to UBIKContentView and ContentControl.

When a ContentTemplate is assigned to either of these controls and the LazyLoading property is set to true, the content is only loaded when it is explicitly requested. The difference between this and simply controlling the IsVisible condition is that in the latter, resources are still consumed in constructing the UI element, even though it is not shown. Note that Lazy loading requires a trigger to determine when the content should be loaded, and the biggest benefit is experienced when complex elements, especially those hosting a ListView or some kind of object/property collection, are lazy-loaded.

UBIKTabView is optimized to make use of the LazyLoading attribute when it is applied to tab content. Additionally, usage outside of UBIKTabView is possible, as the loading can be triggered as a behavior attached to any other control, such as a button with an IsClicked behavior handler.

'''UBIKTabView with LazyLoading'''

When used in combination with UBIKTabView (by including the LazyLoading=True attribute on any UBIKContentView or ContentControl content of a tab item, as is now standard {{Version/MobileSince|5.1}}), only the content of the selected tab is rendered (by default, the first tab). The content of non-selected tabs is not. When switching tabs, UBIKTabView takes care of triggering the rendering of the content for the newly selected tab.

{| class="wikitable"
! UBIKContentView
! ContentControl
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:ContentControl
ContentTemplate="{DynamicResource MyTemplate}"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</syntaxhighlight>
|-
|}

''' Using another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. The benefit of this is that LazyLoading can still be applied to a complex UBIKContentView or ContentControl that is not hosted within a UBIKTabView.

And example of a usecase is a togglebutton that reveals a section of content:

<syntaxhighlight lang="xml">
<tabView:SfTabItem.Content>
<Grid RowDefinitions="*,50,*">
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />

<Button
x:Name="LoadDocuments"
Grid.Row="1"
HeightRequest="50"
HorizontalOptions="Center"
Text="LazyLoadDocuments"
WidthRequest="200">
<Button.Behaviors>
<behaviors:EventHandlerBehavior EventName="Clicked">
<behaviors:InvokeMethodAction MethodName="TriggerLazyLoad" TargetObject="{Binding Source={x:Reference DocumentsAreaLoader}}" />
</behaviors:EventHandlerBehavior>
</Button.Behaviors>
</Button>

<controls:UBIKContentView
x:Name="DocumentsAreaLoader"
Grid.Row="2"
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</Grid>
</tabView:SfTabItem.Content>
</syntaxhighlight>

= Known issues =

=== Headlesslayout style in custom UBIKThemes causing problems ===

In our default '''UBIKThemes''', we are currently using this style for a headless layout:

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

<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless">
<Setter.Value>
<OnPlatform
x:TypeArguments="x:Boolean"
Android="True"
WinPhone="False"
iOS="False" />
</Setter.Value>
</Setter>
</Style>
</syntaxhighlight>

<br/>
This style is used for better UI performance on Android.
Using this style in a '''custom UBIKThemes''' could cause an exception & an app crash, or some objects to disappear.
The best case would be to '''not''' include it in the custom themes file, as it's unnecessary if you don't want to make any changes here.

'''This issue is only known on Android tablet devices.'''
<br>
<br>

=== DataTrigger Issues ===
==== Conflicting Triggers ====
DataTriggers in Mobile function better than the equivalent DataTriggerBehavior in UWP as they automatically handle the opposite case when a Boolean attribute value is set. This means that if a boolean DataTrigger is set, such as IsVisible=True, the False visibility will automatically be set if the Binding/Value condition is not met.

However, this means that stacking multiple DataTriggers on the same attribute can lead to unexpected results. For this reason, it is recommended to use as few DataTriggers as possible.
* Avoid setting the same attribute more than once; do not set the same value as a default attribute and in the DataTrigger (ControlTemplate in the below example).
* Ideally, use only DataTriggers without a default ControlTemplate. This ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
* It is acceptable, but not recommended, to combine a single DataTrigger with an opposite default value, but only if the default value is different from all values set in triggers.

<tabs>
<tab name="Don't Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
<br>
</tab>

<tab name="Instead Do">
<source lang = "xml">
<ContentView x:Name="editorValueContainer">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="true">
<Setter Property="ControlTemplate" Value="{StaticResource SelListTemplate}" />
</DataTrigger>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>

<tab name="Acceptable, but not recommended">
<source lang = "xml">
<ContentView x:Name="editorValueContainer" ControlTemplate="{StaticResource SelListTemplate}">
<ContentView.Triggers>
<DataTrigger Binding="{Binding Source={x:Reference editorValueContainer}, Path=BindingContext.PropertyViewModel.ShowComboBox}" TargetType="ContentView" Value="false">
<Setter Property="ControlTemplate" Value="{StaticResource TextTemplate}" />
</DataTrigger>
</ContentView.Triggers>
</ContentView>
</source>
</tab>
</tabs>

==== DataTrigger to set Footer Properties in a ListView ====

When using a DataTrigger to set the properties of a footer for a ListView, the sequence of the properties inside the DataTrigger might matter in some cases.
It seems to occur since Version 4.4 due to a Syncfusion update and could lead to the page not being rendered properly and appearing empty.

If you encounter such an issue, please workaround by adding the IsStickyFooter Property Setter on top inside the DataTrigger.
Also, new customizings should consider this workaround as a preventive action.

<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
<Setter Property="IsStickyFooter" Value="True" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>

<br/>
<syntaxhighlight lang="xml">

<controls:SfListViewExt ...>
<controls:SfListViewExt.Triggers>
<DataTrigger TargetType="controls:SfListViewExt" Binding="{Binding Title}" Value="Administration">
<Setter Property="IsStickyFooter" Value="True" />
<Setter Property="FooterTemplate" Value="{DynamicResource AddLoginFooter}" />
<Setter Property="FooterSize" Value="64" />
</DataTrigger>
</controls:SfListViewExt.Triggers>
</controls:SfListViewExt>
</syntaxhighlight>
<br>
<br>
=== Incorrect glyphs may be shown on buttons ===

When using glyphs on buttons in Mobile, sometimes a different glyph than the expected one will show up when viewing the app on Android.
They only seem to appear incorrectly when used as the Text property of the button (with FontFamily set to UBIKSymbols, such as the UBIKIconButton style.)

If you encounter this issue please workaround by supplying the icon through the FontImageSource property of the button.

<syntaxhighlight lang="xml">
<Button Command="{Binding BulkOperation.InvokeOnItemsCommand}">
<Button.ImageSource>
<FontImageSource
FontFamily="{DynamicResource UBIKSymbols}"
Glyph="{x:Static resources:UBIKIcons.MobileDelete}"
Color="{DynamicResource UBIKDarkThemeColor}"
Size="22"/>
</Button.ImageSource>
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="Command" Value="DiscardContentCommand" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</syntaxhighlight>
<br>
<br>
=== Buttons and gesture recognizers ===
In Mobile XAML, you can use gesture recognizers on many UI elements such as a Grid to enable the latter to interact with user inputs.

However, we've already made quite a lot of experience that gesture recognizers do not always work on Android and iOS when used on a Button control.
For example, the following Button won't properly invoke the command on said platforms.

<syntaxhighlight lang="xml">

<Button ...>
<Button.GestureRecognizers>
<TapGestureRecognizer Command="{Binding ReplicateAsDataCommand}" />
</Button.GestureRecognizers>
</Button>
</syntaxhighlight>

<br/>
Therefore, you should always seek alternatives for Buttons.
'''If only one command is needed''', use the standard Command property on the Button, e.g.

<syntaxhighlight lang="xml">

<Button Command="{Binding ReplicateAsDataCommand}" .../>
</syntaxhighlight>

<br/>
Or if multiple commands are needed, use Behaviors '''instead''', e.g.

<syntaxhighlight lang="xml">

<Button xmlns:behaviors="clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL" ...>
<Button.Behaviors>
<behaviors:EventToCommandBehavior Command="{Binding ReplicateAsDataCommand}" EventName="Clicked" />
<behaviors:EventToCommandBehavior Command="{Binding NavigateBackCommand}" EventName="Clicked" />
</Button.Behaviors>
</Button>
</syntaxhighlight>
<br>
<br>
=== No dynamic reloading of Document Viewer ===
[[File:PDFViewerFixWiki.JPG]]

In a customizing that combines a single-selection list of documents with some kind of viewer (especially UBIKDocumentContentArea), it is generally the case that switching the document causes the document viewer to then appear blank. The technical reason is that the PDFViewer used in the UBIKDocumentContentArea is not reloaded once the document content is reloaded.

An easy fix is to apply a DataTrigger that unloads the ContentView when the document content is null, as the ContentView is forced to rerender itself when the trigger condition is no longer met.

<syntaxhighlight lang="xml">

<controls:UBIKContentView
x:Name="DoucmentViewer"
BindingContext="{Binding SelectedItem, Source={x:Reference DocumentList}}"
Content="{Binding [UBIKDocumentContentArea], Source={x:Static services:TemplateService.Instance}}">

<controls:UBIKContentView.Triggers>
<DataTrigger TargetType="controls:UBIKContentView" Binding="{Binding SelectedItem.DocumentViewModel.DocumentContent, Source={x:Reference DocumentList}, Converter={StaticResource NullToBool}}" Value="True">
<Setter Property="Content" Value="{x:Null}" />
</DataTrigger>
</controls:UBIKContentView.Triggers>
</controls:UBIKContentView>
</syntaxhighlight>

=== Issues with SfPullToRefresh in Mobile client {{Version/MobileSince|5.0}} ===
Due to a third-party issue, problems may occur on Mobile Android when using the SfPullToRefresh control in combination with the SfListViewExt. This can result in e.g. navigation or task interaction sometimes requiring multiple clicks.
In general, and due to more issues, it's not recommended to use the SfPullToRefresh control.
In our Mobile standard client, the PullToRefresh control has been replaced by a Refresh button in the Context Menu.
If you still decide to use SfPullToRefresh, there are a few points to consider:

==== Avoid multiple SfPullToRefresh controls ====
To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_multiple_SfPullToRefresh_controls|this link]].

==== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ====
To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control. Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control. For an example, refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui#Avoid_using_SyncFusion_ListViews_directly_in_SfPullToRefresh_controls|this link]].

=== Tooltips not supported on mobile iOS devices {{Version/MobileSince|5.0}} ===
On iOS, native tooltips are only supported under very specific conditions. According to the official [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/tooltips?view=net-maui-10.0| Microsoft documentation], tooltips are only shown when running the app on macOS with a pointer device. On physical iPhones and iPads, tooltips are generally not displayed. This means that using ToolTipProperties in XAML will not work reliably on iOS mobile devices.

A possible workaround is to simulate tooltip behavior using a [https://help.syncfusion.com/maui/popup/overview| SfPopup control]. The idea is to use a tap interaction on the UI element (e.g., via a ''TappedBehavior'' with a ''SetPropertyAction'') that opens a Popup positioned relative to that element, and to automatically close the Popup after a short duration.

<syntaxhighlight lang="xml">

xmlns:sfPopup="clr-namespace:Syncfusion.Maui.Popup;assembly=Syncfusion.Maui.Popup"
xmlns:behaviors="clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI"

<sfPopup:SfPopup
x:Name="TooltipTextPopup"
AutoCloseDuration="3000"
RelativePosition="AlignTop"
RelativeView="{x:Reference YourUIElement}"
ShowHeader="False">
<sfPopup:SfPopup.ContentTemplate>
<DataTemplate>
<Label Text="This will be displayed as Tooltip text" />
</DataTemplate>
</sfPopup:SfPopup.ContentTemplate>
</sfPopup:SfPopup>

<Border x:Name="YourUIElement">
<Border.Behaviors>
<behaviors:TappedBehavior>
<behaviors:SetPropertyAction
PropertyName="IsOpen"
TargetObject="{Binding Source={x:Reference TooltipTextPopup}}"
Value="True" />
</behaviors:TappedBehavior>
</Border.Behaviors>
</Border>


<Border x:Name="YourUIElement">
<ToolTipProperties.Text>
This will NOT be shown on iOS
</ToolTipProperties.Text>
</Border>
</syntaxhighlight>

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

= UBIK Go (Maui) Customizing Guide {{Version/MobileSince|5.1}} =
The change to Maui was taken as an opportunity both to visually update the client's default UI, and to add some quality of life changes aiming to reduce the amount of customizing needed.

This section describes the standard UI and how to more easily customize it.

For differences between Xamarin and Maui, please refer to the [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] article.

== XAML Changes And Improvements ==
=== Styles and Resources ===
* Various color elements were renamed for neutrality. This will help clarify the purpose of color themes, and make it easier to keep track of in customizings. The old versions are still available but moved to the Obsolete section of UBIKThemes. <syntaxhighlight lang="xml">
UBIKDarkTextColor --> UBIKRegularTextColor
UBIKDarkThemeColor --> UBIKMainThemeColor
UBIKLightTextColor --> UBIKMainThemeContrastColor
UBIKLightThemeColor --> UBIKBasePageColor
UBIKSubtleTextColor --> UBIKMediumTextColor
</syntaxhighlight>
* Furthermore, effort was made to create 'contrast pairs' throughout the client; for example, UBIKMainThemeContrastColor is defined primarily for texts layered on elements of UBIKMainThemeColor (such as the title bar and text).
** The intention here is that this pair can be safely customized with no surprises, that cannot be guaranteed when using non-paired resource. For example, UBIKMainThemeContrastColor and UBIKBasePageColor are both white in the default customizing, but if UBIKBasePageColor that were to be layered over UBIKMainThemeColor, it would result in a black-on-black issue in a dark theme customizing.
** The 'pairs' are; <syntaxhighlight lang="xml">
UBIKMainThemeColor x UBIKMainThemeContrastColor
UBIKBasePageColor x UBIKRegularTextColor
UBIKButtonColor x UBIKButtonTextColor
UBIKButtonToggledColor x UBIKButtonToggledTextColor
UBIKPDFBaseColor x UBIKPDFTextColor
UBIKPDFSelectedToolColor x UBIKPDFSelectedToolTextColor
</syntaxhighlight>
* An effort was also made to avoid hardcoding numeric values on the client. Reusable resources were introduced instead; <syntaxhighlight lang="xml">
<x:Double x:Key="UBIKButtonIconSize">20</x:Double>
<x:Double x:Key="UBIKButtonPanelSize">56</x:Double>
<x:Double x:Key="UBIKButtonSize">44</x:Double>
<x:Double x:Key="UBIKListItemSize">80</x:Double>
<OnIdiom x:Key="UBIKTileItemSize" x:TypeArguments="Thickness" Default="120" Phone="100" />
<x:Double x:Key="UBIKCaptionTextSize">14</x:Double>
<x:Double x:Key="UBIKButtonTextSize">16</x:Double>
<x:Double x:Key="UBIKBodyTextSize">16</x:Double>
<x:Double x:Key="UBIKTitleTextSize">18</x:Double>
<x:Double x:Key="UBIKProgressBarHeight">4</x:Double>
<OnIdiom x:Key="UBIKAdaptivePadding" x:TypeArguments="Thickness" Default="8,0" Phone="4,0" />
<OnIdiom x:Key="UBIKAdaptiveSpacing" x:TypeArguments="x:Double" Default="16" Phone="8" /></syntaxhighlight>

* Regarding corporate colors, there are now additional resources to customize, aside from UBIKAccentColor;
** UBIKHighlightColor is a secondary accent color used for highlighting (eg. Multiselect mode or edited Property). {{Version/MobileSince|5.1.0.0}} Transparency has been added to the UBIKHighlightColor.
** UBIKGradientColor {{Version/MobileSince|5.1.0.0}} is used in combination with UBIKAccentColor to form a gradient on the Authentication area.
* As in WinX {{Version/WinXSince|4.0}}, the various possible object status indicators were exported to a template called '''StatusIndicators''' located in UBIKThemes. These are now displayed at the top right of the item template, with a semi-opaque underlay in case the indicators appear over Title/SubTitle text.
* '''SfTextInputLayout''' was introduced and is used in various locations (Authentication, and properties).
* Default values for size, font, color, etc, were applied to various controls (Picker, Entry etc) for consistency.
* New '''SfListView''' styles were introduced and the originals moved to the Obsolete section.
** The listview now has a background color (UBIKMediumElementColor) and child item templates are now responsible for providing their own background color (UBIKBasePageColor that is applied to the Grid style UBIKItemBase).
*** The intention is to provide visual distinction from actual list items and empty list 'space'.
*** However, this will interfere with lists that rely on the SelectionBackground to highlight selection. This is solved in various ways throughout the UI, such as the SelectedIndicator used in UBIKChildItem, or the seperate SelectedItem and SelectedItemTemplate templates used in UBIKEditGuid.

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

=== Adaptivity ===
- tbd.

=== Layout and Functionality ===
* '''UBIKNavigationBar''' was introduced as a templatable alternative to the hardcoded context menu (accessed by the '...' button in the top right of the content area) and is fully customizable.
* Shadowed panels were introduced in place of floating buttons in the content tabs (Children, Properties). For consistency, both are located at the top of their respective tab content.
* '''UBIKChildItem''' was visually simplified. It now displays a simple icon, the Title (and MRO progress, if any) and Subtitle, and StatusIndicators in the top right. The progressbar is now displayed across the bottom of the item.
* '''UBIKTaskItem''' was completely redesigned.
** Aside from the StatusIndicators that appear in the top right uniformly on any context object, MRO-related ones (Task status (Finished, NA, or Not Necessary, Group Limit and Size, Previous Value, and Tech Indicator) appear on the top left contained in an SfChipGroup.
** The main area of the task item is previously split between Title and task-related input. On smaller devices or in editing regardless of screen size, the input area sizes becomes larger.
** The task related input now looks visually distinct with and without a value. UBIKButton(Text)Color is used for 'new' tasks, while UBIKButtonToggled(Text)Color is used for the 'value filled' state.

=== File Structure ===
* '''UBIKRootItem''' (formerly UBIKMainItem) was introduced simply so that the Title, Area, and Item are organized together within the default and customizing folders. For compatibility, UBIKMainItem still exists in the default folder, however, be aware that the listview in UBIKRootArea now requests UBIKRootItem as the ItemTemplate by default.

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

== Customizing Guides ==
=== Dark Theme ===
While UBIK Go does not include a Dark Theme by default, a lot of effort was invested in optimizing the color resources used throughout the app, so that a dark theme can be quickly customized. Furthermore, below is a list of recommended changes that result in a functional dark theme.

'''In UBIKThemes:'''
<syntaxhighlight lang="xml"><x:String x:Key="TextFontFamily">InterL</x:String></syntaxhighlight>
Replace the value for TextFontFamily with "InterL"; It is recommended to use a thinner font as white on black looks bolder than the inverse.
A 'Light' version of the default font font was added and can be accessed using the tag InterL.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKRegularTextColor">White</Color>
<Color x:Key="UBIKMediumTextColor">#A3ffffff</Color>
<Color x:Key="UBIKBasePageColor">#3a3a3c</Color>
<Color x:Key="UBIKMainThemeColor">#2c2c2e</Color>

<Color x:Key="UBIKBorderColor">#181719</Color>
<Color x:Key="UBIKElementColor">#2c2c2e</Color>
<Color x:Key="UBIKLightElementColor">#222124</Color>
<Color x:Key="UBIKFinishedElementColor">#2a2a2b</Color>
<Color x:Key="UBIKOverlayElementColor">#3D000000</Color>
<Color x:Key="UBIKImageOverlayColor">#A3000000</Color>

<Color x:Key="UBIKButtonColor">#181719</Color>
<Color x:Key="UBIKButtonTextColor">White</Color>
<Color x:Key="UBIKButtonToggledColor">White</Color>
<Color x:Key="UBIKButtonToggledTextColor">Black</Color>

<Color x:Key="UBIKPDFSelectedToolColor">White</Color>
<Color x:Key="UBIKPDFSelectedToolTextColor">#292929</Color>
<Color x:Key="UBIKPDFTextColor">White</Color>
<Color x:Key="UBIKPDFBaseColor">#181719</Color>
</syntaxhighlight>
Replace the above color resources (or similar).

<syntaxhighlight lang="xml">
<Shadow
x:Key="UBIKPanelShadow"
Brush="Black" ... />
</syntaxhighlight>
Change the value for the attribute Brush to "Black" to darken the panel shadows.

<syntaxhighlight lang="xml">
<Color x:Key="UBIKProgressBarUndefinedStatuscolor">#636365</Color>
...
<Style x:Key="UBIKProgressBar" TargetType="controls:ProgressBar">
<Setter Property="StatusColor" Value="{Binding ClassificationHandler.StatusColor, Converter={StaticResource IntToColor}, ConverterParameter={StaticResource UBIKProgressBarUndefinedStatuscolor}}" />
</Style>
</syntaxhighlight>
The light theme uses UBIKElementColor for the progress bar color when none is defined on the server. However, this does not invert well in a dark theme. Therefore a new color resource should be introduced ("UBIKProgressBarUndefinedStatuscolor") and used in the ConverterParameter of the IntToColor converter, which does not accept a color hex code directly.

'''In UBIKSplashArea:'''

Follow the instructions embedded within the file to replace the splash image with a custom logo. Alternatively, simply adapt the Source attribute of the Image control to "splashlogoinverse.png" to apply an inversion of the UBIK Go logo.

=== Increased FontSize ===
tbd.

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

Version 5.2 (Mobile)

2026-08-04T12:17:52Z

REP:

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

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

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

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

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

<headertabs />

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

Version 5.2 (Mobile)

2026-08-04T12:16:34Z

REP: added note on new ScanningIsActive binding

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

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

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

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

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

<headertabs />

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

EditPropertyValueCommand

2026-08-03T08:46:38Z

REP: /* Scan to Input */

This command is used to open a dialog for editing a property.

It is located on the ContentViewModel, and as such can be used from the UI of an object to edit its MetaProperties.

{{Attention|Note that a Save and Commit on the ContentViewModel is automatically triggered once the edit is confirmed.}}
{{Hint|If your usecase requires that the property change '''is not automatically saved''', instead use the (PropertyViewModel).ShowEditorCommand / .PropertyClickedCommand to trigger the edit dialogue of a specific MetaProperty.}}

== Command Properties ==
* ID: String. The ID of the property to be edited.

Example:
<source lang = "xml">
<Button Command="{Binding EditPropertyValueCommand}" Text="Edit">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="ID" Value="TEXT_READWRITE" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

=== Scan to Input ===
* ScanToInput: bool. Default value is false.

A custom button can be added to the UI to trigger the scanning control by default when the string edit window is opened, simply by adding the following KeyValueParameter:
<source lang = "xml">
<Button Command="{Binding EditPropertyValueCommand}" Text="ScanToEdit">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="ID" Value="TEXT_READWRITE" />
<uc:KeyValueParameter Key="ScanToInput" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

{{Version/MobileSince|5.2}} A toggle button to do from within the [[Editors#String_value_editor|string edit dialogue]] was added to the standard UI.

[[Category:XAML|EditPropertyValueCommand]]

EditPropertyValueCommand

2026-08-03T08:36:55Z

REP: Made scan to input section more prominent

This command is used to open a dialog for editing a property.

It is located on the ContentViewModel, and as such can be used from the UI of an object to edit its MetaProperties.

{{Attention|Note that a Save and Commit on the ContentViewModel is automatically triggered once the edit is confirmed.}}
{{Hint|If your usecase requires that the property change '''is not automatically saved''', instead use the (PropertyViewModel).ShowEditorCommand / .PropertyClickedCommand to trigger the edit dialogue of a specific MetaProperty.}}

== Command Properties ==
* ID: String. The ID of the property to be edited.

Example:
<source lang = "xml">
<Button Command="{Binding EditPropertyValueCommand}" Text="Edit">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="ID" Value="TEXT_READWRITE" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

=== Scan to Input ===
* ScanToInput: bool. Default value is false.

A custom button can be added to the UI to trigger the scanning control by default when the string edit window is opened, simply by adding the following KeyValueParameter:
<source lang = "xml">
<Button Command="{Binding EditPropertyValueCommand}" Text="ScanToEdit">
<Button.CommandParameter>
<uc:KeyValueList>
<uc:KeyValueParameter Key="ID" Value="TEXT_READWRITE" />
<uc:KeyValueParameter Key="ScanToInput" Value="true" />
</uc:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

{{Version/MobileSince|5.2}} A togglebutton to do from within the string edit dialogue was added to the standard UI.

[[Category:XAML|EditPropertyValueCommand]]

Version 5.2 (Mobile)

2026-08-03T08:22:13Z

REP: /* 5.2.? on 2026-07-?? */

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

=== 5.2.? on 2026-07-?? ===
* Fixed an issue where documents did not reload properly.
* Fixed an issue where it was not possible to toggle the text input scanner from within the string edit dialog, and added a button to do so to the default UI.

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

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

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

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

= ⚠️ XAML Notes =

<headertabs />

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

Version 5.2 (Mobile)

2026-07-29T13:11:16Z

REP: /* Release */

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

=== 5.2.? on 2026-07-?? ===
* Fixed an issue where documents did not reload properly.
* Fixed an issue where it was not possible to toggle the text input scanner from within the string edit dialog.

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

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

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

= ⚠️ XAML Notes =

<headertabs />

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

Version 5.2 (WinX)

2026-07-15T09:24:37Z

REP: /* Release */ removed wrong note

Version 5.2 (Mobile)

2026-07-15T09:24:25Z

REP: /* Release */ removed wrong note

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

=== 5.2.?? on 2026-??-?? ===
* UBIK LABs (Experimental) The update interval for live value updates (LiveValueUpdateIntervalMs) can be configured in profiles.
* Updated all client localization translations.

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

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

= ⚠️ XAML Notes =

<headertabs />

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

Version 5.1 (Mobile)

2026-07-15T09:24:04Z

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.?? on 2026-07-?? ===
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.
* Fixed an issue where DocumentViewModel.ShowDocumentCommand did not work when combined with InvokeCommandAction.

=== 5.1.54 on 2026-07-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* You can now specify a boolean command parameter for ContentViewModel.DiscardContentCommand in order to skip the confirmation dialog.

=== 5.1.52 2026-06-23 {{key press|Android: Store Beta}} / 5.1.53 2026-06-24 {{key press|iOS: Store Beta}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where [[XAML_Tips#InvokeOnItemsCommand|BulkOperation.InvokeOnItemsCommand]] was not always applied to all items in the collection.
* Fixed an issue where the app sometimes redirects to the login page on certain Android devices. For example, when the device rotates or a physical keyboard is attached.
* Fixed an issue where the task value editing field is unlimited in space and covers everything else.
* Fixed an issue where filtering was not possible in query popups.
* Fixed an issue where it was not possible to set N/A via editors.
* Fixed an issue where the Properties UI was not refreshed properly after reverting changes.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.
* Fixed an issue where it's impossible to show document files externally from list items.
* (iOS) Fixed an issue where the NFC button in the side menu looked like a toggle button while it's not.
* Fixed an issue where the Unit of a Task value has been clipped.

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

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

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

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].
* The possibility to trigger external opening of documents from listview level was added, but to access document-specific commands from the context of a non-document parent view you need to apply the following workaround in xaml; (namely, the "Documents.Items[0]" prefix). <syntaxhighlight lang="xml">
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction
Command="{Binding Documents.Items[0].DocumentViewModel.ShowDocumentCommand}"
Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}"/>
</behaviors:EventHandlerBehavior>
</syntaxhighlight>
** Also note that this same workaround is used in UBIKRootArea. The technical reason is that root items have no parent context from which commands are initialized, so the navigation command needs to be 'borrowed' from the first root item.

<headertabs />

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

Version 5.1 (WinX)

2026-07-15T09:23:34Z

REP: /* Release */

{{Attention|This version requires [https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1809_(October_2018_Update) Windows 10 build 17763] or higher}}

== Availability ==
{{key press|Store}}: Publicly available in Microsoft Store.

{{key press|Store Beta}} / {{key press|Store Preview}}: Publicly available in Microsoft Store as beta or preview versions to those whose account email is participating in our beta or preview test. To join, please send an email to testing@augmensys.com and provide an email address to add to the list as well as the information which test you want to join. Alternatively you can contact the Augmensys staff and submit your chosen email address.

Example: Please add my email account example@example.com to the '''Beta''' test group for the '''WinX''' client.

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

= Release Notes =

== Release ==

=== 5.1.?? on 2026-07-?? ===
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.
* Fixed an issue where DocumentViewModel.ShowDocumentCommand did not work when combined with InvokeCommandAction.

=== 5.1.17 on 2026-07-02 {{key press|Store}} ===
* Fixed an issue where ContentViewModel.Values did not display the values in the [[Developer Mode|developer mode]].
* You can now specify a boolean command parameter for ContentViewModel.DiscardContentCommand in order to skip the confirmation dialog.

=== 5.1.16 on 2026-06-23 {{key press|Store Beta}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Provided a visual difference between suggested and actual values in DateTime and Geo property direct edit fields via a [[XAML#Custom_VisualState_Trigger|Custom VisualState Trigger]].
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems.
* Fixed an issue that caused dialogs to remain open when refreshing, causing problems.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.

=== 5.1.9 on 2026-04-22 {{key press|Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.6 on 2026-02-10 {{key press|Store}} ===
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where certain documents couldn't be loaded anymore.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed an issue where the UI did not update properly when committing a direct edit input task.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the Chart Thresholds didn't update.
* Added a [[XAML#UBIKWebView|UBIKWebView]] control that includes a fix in the WebView2 where some links could not be opened.
* Fixed issue that caused input fields to be focused but not editable.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

[[Category:Version 5.1|Version 5.1 (WinX)]]

== Known issues ==
* Due to third-party limitations, the feature that shows the ImageEditor Save button only when edits have been made is only active when MergeAnnotationsOnSave is set to true.
* When editing Guid Link properties, you can no longer further edit the filtering if there are predefined filter parameters (such as the [[Dynamic_Selective_List_(Client)#Dependency_property_values|dependency property values in dynamic selective lists]]). This is because those parameters are to be enforced by design and should not be changed by users. In the future, we might consider a finer level of control over which parameters can be edited in such cases.
* Free Text Annotations that where created in former sessions cannot be selected and therefore cannot be edited any more.
* There are still some [[Annotation_and_HotSpot#Known_issues|known issues with free text and text markup annotations]].
* Known issues regarding the [[Documents_(Client)#Remember_Document_Settings|Remember Document Settings]] feature:
** Saving the Zoom value via touch gestures is not supported.
** Due to a third-party framework issue it can't be guaranteed that saving the Zoom level is always working properly. We reported this issue and will update our solution as soon as it is resolved on their side.
<br/>

= ⚠️ XAML Notes =
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

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

[[Category:Version 5.1|Version 5.1 (WinX)]]

Version 5.2 (Mobile)

2026-07-15T09:19:29Z

REP: /* Release */

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

=== 5.2.?? on 2026-??-?? ===
* UBIK LABs (Experimental) The update interval for live value updates (LiveValueUpdateIntervalMs) can be configured in profiles.
* Updated all client localization translations.
* Fixed an issue where DocumentViewModel.ShowDocumentCommand did not work when combined with InvokeCommandAction.

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

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

= ⚠️ XAML Notes =

<headertabs />

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

Version 5.2 (WinX)

2026-07-15T09:19:04Z

REP: /* Release */

Version 5.1 (Mobile)

2026-07-15T09:15:48Z

REP: added note on showdocument command

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==

=== 5.1.?? on 2026-07-?? ===
* Updated misleading text resources on dialogues to delete an object on the server and to locally discard an object.

=== 5.1.54 on 2026-07-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* You can now specify a boolean command parameter for ContentViewModel.DiscardContentCommand in order to skip the confirmation dialog.

=== 5.1.52 2026-06-23 {{key press|Android: Store Beta}} / 5.1.53 2026-06-24 {{key press|iOS: Store Beta}} ===
* New features and enhancements in MRO.
** {{UBIK}} now supports defining [[MRO_Objects_(Client)#Procedure_Tasks|branching logic in procedure work packages]].
** {{UBIK}} now supports [[MRO_Objects_(Client)#Procedure_Tasks|calculation tasks which evaluate predefined expressions]].
** {{UBIK}} now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
** Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
** Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
** [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where [[XAML_Tips#InvokeOnItemsCommand|BulkOperation.InvokeOnItemsCommand]] was not always applied to all items in the collection.
* Fixed an issue where the app sometimes redirects to the login page on certain Android devices. For example, when the device rotates or a physical keyboard is attached.
* Fixed an issue where the task value editing field is unlimited in space and covers everything else.
* Fixed an issue where filtering was not possible in query popups.
* Fixed an issue where it was not possible to set N/A via editors.
* Fixed an issue where the Properties UI was not refreshed properly after reverting changes.
* Fixed an issue where the app gets stuck during login when there are geography properties without values.
* Fixed an issue where the root object list doesn't get fully refreshed upon meta definition updates.
* Fixed a potential UI performance issue during file upload.
* Fixed an issue where it's impossible to show document files externally from list items.
* (iOS) Fixed an issue where the NFC button in the side menu looked like a toggle button while it's not.
* Fixed an issue where the Unit of a Task value has been clipped.

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

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

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].
* The possibility to trigger external opening of documents from listview level was added, but to access document-specific commands from the context of a non-document parent view you need to apply the following workaround in xaml; (namely, the "Documents.Items[0]" prefix). <syntaxhighlight lang="xml">
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction
Command="{Binding Documents.Items[0].DocumentViewModel.ShowDocumentCommand}"
Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}"/>
</behaviors:EventHandlerBehavior>
</syntaxhighlight>
** Also note that this same workaround is used in UBIKRootArea. The technical reason is that root items have no parent context from which commands are initialized, so the navigation command needs to be 'borrowed' from the first root item.

<headertabs />

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

XAML Tips

2026-06-16T12:46:40Z

REP: /* FontIcon does not update when set dynamically using Behaviors */ Added example code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

<br>
<br>

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

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

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

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

== Remember scroll positions of list views ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{Hint|There's no way to commit changes without saving them locally first. Therefore, the "AutoSave" parameter will be ignored when "AutoCommit" is set to true.}}

Here's an example of the command usage. It tries to set the property called "VALUE" to a double value 50 regardless of its current state and then automatically save and commit the change.
<br />
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="My Value" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

{{Hint|For simple types, you can try writing them in the text format like <nowiki><controls:KeyValueParameter Key="PropertyValue" Value="50"/></nowiki> and {{UBIK}} will try to find the right type. For advanced property types, it is advised to provide typed values like <nowiki><x:Boolean>true</x:Boolean></nowiki>.}}
<br>

==== Set a Binding as PropertyValue ====
There is a known issue in XAML where Behaviors and KeyValueLists do not inherit the binding context of the control they are attached to. Simply put, trying to use a binding directly in the PropertyValue part of the command; '''<nowiki><controls:KeyValueParameter Key="PropertyValue" Value="{Binding BindingPath}" /></nowiki>''', would lead to the client setting the value of MP_PROPERTY to null.

Luckily, there is a simple way to link this Binding to a context. Using the above example as a foundation, adapt the button as shown below:
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

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

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

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

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

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

<tab name="Mobile">
<source lang="xml">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

<br>

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Localizing UI Texts ====
The most efficient practice is to use pre-localized texts from the standard client, however, this is not always possible, especially in custom UIs. The ObjectByUID indexer was therefore initially developed as a technique to allow localization of custom UI label texts.

The concept is to create an infrastructure object that carries metaproperties for localized texts, then bind to this infrastructure object using ObjectByUID, and bind to a specific metaproperty to receive it's localized Description text as follows:
<source lang = "xml">
"{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].Description}"
</source>

From here there are two approaches; the database-leaning one is to add one metaproperty per UI label, and simply bind to the Description of it. However, this shifts maintenance effort to the UBIK Studio after the initial adding of the label in XAML. Another approach would be to use the metaproperty to provide a "tag" that the xaml customizer can then use to differentiate between hardcoded labels.

A third approach would be to create one infrastructure object per label, however, this can lead to many objects being loaded upon startup.

{| class="wikitable"
|-
! Approach !! Implementation !! Maintenance Effort !! Recommendation
|-
| One metaproperty per UI Label || Bind the label text to the metaproperty Description || Database / UBIK Studio || Recommended for UWP, customizings with fewer UI texts, finalized customizings.
|-
| One metaproperty delivering a localization "tag" (such as: "EN" / "DE") || Use something like DataTrigger (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

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

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

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

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

=== Icons ===
UBIK comes equipped with a collection of icons that can be easily used in your customizing. [[Icon_Font|Here is an indepth explanation on usage]].

In the case that you require an icon that is not included in our icon font file, there is the possibility to use SVG path data to render your required icon in the UI.
<br>

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

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

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

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

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

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

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

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

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

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

<br>
<br>

== TabView ==

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

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

=== Default Tab Selection ===
The tab selection in UBIKContentView defaults to the first tab, which is Children objects. However, for cases where it makes more sense to display Properties or Documents by default, it is possible to change the tab selection using the following classifications:
* [[SYSCLS_SHOWDOCUMENTS]]
* [[SYSCLS_SHOWPROPERTIES]]

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(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].

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

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

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

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

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

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

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

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

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

Instead, we should either use the '''multi-tag syntax''' or the '''inline syntax''' for OnPlatform / OnIdiom.

==== Multi-tag syntax ====
Here it is mandatory to add '''x:TypeArguments="TheType"''' with the proper type to OnPlatfrom/OnIdiom. ''Default="..."'' is optional and can be added like in the following example if a default value needs to be defined.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<OnPlatform x:TypeArguments="Thickness" Default="20">
<On Platform="iOS, WinUI" Value="0,20,0,0" />
<On Platform="Android" Value="10,20,20,10" />
</OnPlatform>
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<OnIdiom x:TypeArguments="Thickness" Default="20">
<OnIdiom.Desktop>0,60,0,0</OnIdiom.Desktop>
</OnIdiom>
</source>
</tab>
</tabs>

If OnPlatform Values contain multiple subtags, the following syntax can be used:
<source lang = "XML">
<ControlTemplate x:Key="ExampleControlTemplate">
<Grid>
<OnPlatform x:TypeArguments="View">
<On Platform="Android">
<Button
...
Text="Button A" />
...
</On>
<On Platform="iOS">
<Button
...
Text="Button B" />
...
</On>
<On Platform="WinUI">
<Grid>
<Button
...
Text="Button C" />
<Label Text="Example" />
...
</Grid>
</On>
</OnPlatform>
</Grid>
</ControlTemplate>
</source>

{{Attention|When using ''GridLength'' as a type in OnPlatform/OnIdiom, it should only be used in combination with the inline syntax.}}

==== Inline syntax ====
When using the inline syntax, the type should not be specified. ''Default='' is optional.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<BoxView Color="{OnPlatform Default=Yellow, iOS=Red, Android=Green}" />
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<BoxView Color="{OnIdiom Default=Yellow, Phone=Red, Tablet=Green}" />
</source>
</tab>
</tabs>

If the value contains any special characters like <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. But be careful with using apostrophes - when using them around curly brackets {} it can lead to an error.
<tabs>
<tab name="Don't">
<source lang = "XML">
Margin="{OnIdiom 10,2, Phone=2,0}"
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Margin="{OnIdiom '10,2', Phone='2,0'}"
</source>
</tab>
</tabs>

=== Complex values ===
If the OnPlatform/OnIdiom value contains a '''Binding''', '''StaticResource''' or any other complex value in curly brackets, it is recommended to use the '''inline syntax'''. Although it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all in OnIdiom / OnPlatform.

<tabs>
<tab name="Don't">
<source lang = "XML">
<OnIdiom x:TypeArguments="..." Default="{Binding ...}">
<OnIdiom.Phone>{Binding ...}</OnIdiom.Phone>
</OnIdiom>
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Header="{OnIdiom Default={Binding ...}, Phone={Binding ...}}"
</source>
</tab>
</tabs>

{{Attention|Unreliable Support: Behavior may vary when using bindings or complex resources. Although it seems to work with the inline syntax according to our experiences, it is recommended to test these edge cases thoroughly.}}

= Known issues =

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

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

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

XAML Tips

2026-06-15T14:27:59Z

REP: Added info on DataTriggerBehavior and FontIcon, added a new Known issues section to do so.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

<br>
<br>

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

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

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

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

== Remember scroll positions of list views ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{Hint|There's no way to commit changes without saving them locally first. Therefore, the "AutoSave" parameter will be ignored when "AutoCommit" is set to true.}}

Here's an example of the command usage. It tries to set the property called "VALUE" to a double value 50 regardless of its current state and then automatically save and commit the change.
<br />
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="My Value" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

{{Hint|For simple types, you can try writing them in the text format like <nowiki><controls:KeyValueParameter Key="PropertyValue" Value="50"/></nowiki> and {{UBIK}} will try to find the right type. For advanced property types, it is advised to provide typed values like <nowiki><x:Boolean>true</x:Boolean></nowiki>.}}
<br>

==== Set a Binding as PropertyValue ====
There is a known issue in XAML where Behaviors and KeyValueLists do not inherit the binding context of the control they are attached to. Simply put, trying to use a binding directly in the PropertyValue part of the command; '''<nowiki><controls:KeyValueParameter Key="PropertyValue" Value="{Binding BindingPath}" /></nowiki>''', would lead to the client setting the value of MP_PROPERTY to null.

Luckily, there is a simple way to link this Binding to a context. Using the above example as a foundation, adapt the button as shown below:
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

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

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

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

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

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

<tab name="Mobile">
<source lang="xml">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

<br>

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Localizing UI Texts ====
The most efficient practice is to use pre-localized texts from the standard client, however, this is not always possible, especially in custom UIs. The ObjectByUID indexer was therefore initially developed as a technique to allow localization of custom UI label texts.

The concept is to create an infrastructure object that carries metaproperties for localized texts, then bind to this infrastructure object using ObjectByUID, and bind to a specific metaproperty to receive it's localized Description text as follows:
<source lang = "xml">
"{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].Description}"
</source>

From here there are two approaches; the database-leaning one is to add one metaproperty per UI label, and simply bind to the Description of it. However, this shifts maintenance effort to the UBIK Studio after the initial adding of the label in XAML. Another approach would be to use the metaproperty to provide a "tag" that the xaml customizer can then use to differentiate between hardcoded labels.

A third approach would be to create one infrastructure object per label, however, this can lead to many objects being loaded upon startup.

{| class="wikitable"
|-
! Approach !! Implementation !! Maintenance Effort !! Recommendation
|-
| One metaproperty per UI Label || Bind the label text to the metaproperty Description || Database / UBIK Studio || Recommended for UWP, customizings with fewer UI texts, finalized customizings.
|-
| One metaproperty delivering a localization "tag" (such as: "EN" / "DE") || Use something like DataTrigger (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

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

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

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

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

=== Icons ===
UBIK comes equipped with a collection of icons that can be easily used in your customizing. [[Icon_Font|Here is an indepth explanation on usage]].

In the case that you require an icon that is not included in our icon font file, there is the possibility to use SVG path data to render your required icon in the UI.
<br>

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

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

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

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

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

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

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

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

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

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

<br>
<br>

== TabView ==

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

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

=== Default Tab Selection ===
The tab selection in UBIKContentView defaults to the first tab, which is Children objects. However, for cases where it makes more sense to display Properties or Documents by default, it is possible to change the tab selection using the following classifications:
* [[SYSCLS_SHOWDOCUMENTS]]
* [[SYSCLS_SHOWPROPERTIES]]

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(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].

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

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

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

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

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

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

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

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

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

Instead, we should either use the '''multi-tag syntax''' or the '''inline syntax''' for OnPlatform / OnIdiom.

==== Multi-tag syntax ====
Here it is mandatory to add '''x:TypeArguments="TheType"''' with the proper type to OnPlatfrom/OnIdiom. ''Default="..."'' is optional and can be added like in the following example if a default value needs to be defined.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<OnPlatform x:TypeArguments="Thickness" Default="20">
<On Platform="iOS, WinUI" Value="0,20,0,0" />
<On Platform="Android" Value="10,20,20,10" />
</OnPlatform>
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<OnIdiom x:TypeArguments="Thickness" Default="20">
<OnIdiom.Desktop>0,60,0,0</OnIdiom.Desktop>
</OnIdiom>
</source>
</tab>
</tabs>

If OnPlatform Values contain multiple subtags, the following syntax can be used:
<source lang = "XML">
<ControlTemplate x:Key="ExampleControlTemplate">
<Grid>
<OnPlatform x:TypeArguments="View">
<On Platform="Android">
<Button
...
Text="Button A" />
...
</On>
<On Platform="iOS">
<Button
...
Text="Button B" />
...
</On>
<On Platform="WinUI">
<Grid>
<Button
...
Text="Button C" />
<Label Text="Example" />
...
</Grid>
</On>
</OnPlatform>
</Grid>
</ControlTemplate>
</source>

{{Attention|When using ''GridLength'' as a type in OnPlatform/OnIdiom, it should only be used in combination with the inline syntax.}}

==== Inline syntax ====
When using the inline syntax, the type should not be specified. ''Default='' is optional.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<BoxView Color="{OnPlatform Default=Yellow, iOS=Red, Android=Green}" />
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<BoxView Color="{OnIdiom Default=Yellow, Phone=Red, Tablet=Green}" />
</source>
</tab>
</tabs>

If the value contains any special characters like <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. But be careful with using apostrophes - when using them around curly brackets {} it can lead to an error.
<tabs>
<tab name="Don't">
<source lang = "XML">
Margin="{OnIdiom 10,2, Phone=2,0}"
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Margin="{OnIdiom '10,2', Phone='2,0'}"
</source>
</tab>
</tabs>

=== Complex values ===
If the OnPlatform/OnIdiom value contains a '''Binding''', '''StaticResource''' or any other complex value in curly brackets, it is recommended to use the '''inline syntax'''. Although it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all in OnIdiom / OnPlatform.

<tabs>
<tab name="Don't">
<source lang = "XML">
<OnIdiom x:TypeArguments="..." Default="{Binding ...}">
<OnIdiom.Phone>{Binding ...}</OnIdiom.Phone>
</OnIdiom>
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Header="{OnIdiom Default={Binding ...}, Phone={Binding ...}}"
</source>
</tab>
</tabs>

{{Attention|Unreliable Support: Behavior may vary when using bindings or complex resources. Although it seems to work with the inline syntax according to our experiences, it is recommended to test these edge cases thoroughly.}}

= Known issues =

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

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

Version 5.1 (Mobile)

2026-05-26T14:33:36Z

REP: /* 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} */

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==
=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* UBIK Client now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
* Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where [[XAML_Tips#InvokeOnItemsCommand|BulkOperation.InvokeOnItemsCommand]] was not always applied to all items in the collection.

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

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

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

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

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

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

Version 5.1 (Mobile)

2026-05-26T14:19:53Z

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}} ===
* UBIK Client now supports [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Tasks]] configured with an [[Active_List_Client|Active List]].
* Added [[MRO_Objects_(Client)#Numeric_Task|Numeric Tasks]] to record numeric values that are checked against an acceptable value range.
* UBIK now supports [[Traits]] which are more flexible when it comes to server side configuration and maintenance.
* Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: Added Show/Hide, AI, Info, and various Procedure icons.
* Fixed an issue where the [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#LoadNextLevelCommand|LoadNextLevelCommand]] did not work under specific conditions (invoked in offline and then in online mode).
* Fixed an issue where [[SYSCLS_CHILDINFOOWNER|child count]] indicators did not update when you delete its child objects which only exist locally.
* Fixed an issue where MRO task items displayed an incorrect DataTemplate after scrolling within a list.
* Fixed an issue where the client could fail at large file uploads (or even crash) due to device running out of memory.
* Fixed an issue where line breaks (in strings property values) from Windows are not recognized as such on other systems. The standard UI is not yet redesigned to show multi-line texts, though. But you can do so in customizing if necessary.
* Fixed the UI of some templates that weren't displayed correctly in Multi Select Mode.
* Fixed an issue where the status color was reflected as background color of an POI item.
* Fixed an issue where it was not possible to do a alternative import of a .profile file on iOS & Android.
* Fixed an issue where it was possible some list items were not updated correctly when e.g. you scroll through the list
* Fixed an issue where setting the SelectedIndex of a UBIKTabView leads to a crash.
* Fixed an issue where BulkOperation.InvokeOnItemsCommand was not always applied to all items in the collection.

=== 5.1.30 2026-03-02 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded when connecting to 5.1 webservices.

=== 5.1.29 on 2026-02-26 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue where the POI button was only visible under certain condition (ShowUnreleasedFeatures in the profile is set to true).

=== 5.1.28 on 2026-02-10 {{key press|Android: Store}}{{key press|iOS: Store}} ===
* The following features which existed in pre 5.0 versions are now available again in 5.1.
** [[Map_View|Map view]].
** [[POI_View_(Mobile)|POI view]]. (Aruco and OCR are not yet supported)
** Location service.
** [[Native_Push_(Client)|Native push]].
** [[Charts]].
* UBIK now uses industry-standard JSON Web Token (JWT) technology for authorization, enhancing security and reliability. Session tokens are transmitted via HTTP headers instead of URLs for improved protection.
* Added support for conditionally showing the ImageEditor Save button only when edits have been made, enabled when MergeAnnotationsOnSave is set to true.
* Complete UI overhaul introduces a cleaner, more modern and adaptive user interface with various quality of life improvements.
* UBIKTabView supports both dynamic and static items in combination with lazy loading.
* Files in the app's data folder can now be opened or deleted directly in the developer settings.
* Introduced a fully resource-driven UI theming system enabling fast, safe customization (dark mode, resizing, and consistent styling) by adapting a small set of centralized resources.
* Added support for [[File_Upload_Size_Restriction|configurable file-upload size restrictions]], preventing oversized files from being uploaded and providing users with feedback when limits are exceeded.
* Fixed an issue where annotated image documents do not appear as changed until the UI refreshes.
* Fixed an issue where displayed file content does not update after you revert its changes.
* Fixed an issue where remembered scroll positions were lost when the ItemsSource property of an SfListViewExt changed (e.g., Properties.ShowAllProperties).
* The UI now updates correctly after mass deletion in multi-selection mode.
* Fixed issue that caused app to be stuck on splash screen after resuming from background.
* Fixed an issue where StatusColor was not shown in the UI for objects that didn't additionally have a Progress.
* Fixed an issue where the Chart Thresholds didn't update.
* Fixed an issue that caused content of the custom ContentControl to not be rendered sometimes.
* (Android) Fixed an issue in the WebView where some links could not be opened.
* Fixed an issue where toggling NA in the String Editor did not behave correctly.
* Fixed an issue where the deletion of some objects was not reflected in the UI until refresh.
* Fixed an issue where document creation might not be properly enabled in certain customizing scenarios. For example, a media creation button might be disabled until a page refresh.
* Fixed an issue where batch creating documents (by multi selecting files to attach) can be interrupted if you leave the page.

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

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

= ⚠️ XAML Notes =
* Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.
* There are some XAML changes necessary when using the new [[Active_List_Client|Active List]] feature, or when using the new [[MRO_Objects_%28Client%29#Pick_List_Task|MRO Pick List Task]]. These XAML changes are explained [[Active_List_Client#XAML|here]].

<headertabs />

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

XAML Tips

2026-05-19T12:09:59Z

REP: /* Using Path Data */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

<br>
<br>

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

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

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

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

== Remember scroll positions of list views ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{Hint|There's no way to commit changes without saving them locally first. Therefore, the "AutoSave" parameter will be ignored when "AutoCommit" is set to true.}}

Here's an example of the command usage. It tries to set the property called "VALUE" to a double value 50 regardless of its current state and then automatically save and commit the change.
<br />
<source lang = "xml">
xmlns:controls="using:UBIK.WinX.Controls"
...
<Button
Command="{Binding SetPropertyValueCommand}"
Style="{StaticResource UBIKButtonStyle}"
Content="Set Property">
<Button.CommandParameter>
<controls:KeyValueList>
<controls:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<controls:KeyValueParameter Key="PropertyValue" Value="My Value" />
<controls:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<controls:KeyValueParameter Key="AutoSave" Value="true" />
<controls:KeyValueParameter Key="AutoCommit" Value="true" />
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>

{{Hint|For simple types, you can try writing them in the text format like <nowiki><controls:KeyValueParameter Key="PropertyValue" Value="50"/></nowiki> and {{UBIK}} will try to find the right type. For advanced property types, it is advised to provide typed values like <nowiki><x:Boolean>true</x:Boolean></nowiki>.}}
<br>

==== Set a Binding as PropertyValue ====
There is a known issue in XAML where Behaviors and KeyValueLists do not inherit the binding context of the control they are attached to. Simply put, trying to use a binding directly in the PropertyValue part of the command; '''<nowiki><controls:KeyValueParameter Key="PropertyValue" Value="{Binding BindingPath}" /></nowiki>''', would lead to the client setting the value of MP_PROPERTY to null.

Luckily, there is a simple way to link this Binding to a context. Using the above example as a foundation, adapt the button as shown below:
<tabs>
<tab name="UWP">
<source lang = "xml">
<Button
x:Name="SetDynamicPropertyButton"
Tag="{Binding}"
... >
<Button.CommandParameter>
<controls:KeyValueList>
...
<controls:KeyValueParameter Key="PropertyValue" Value="{Binding Tag.BindingPath, ElementName=SetDynamicPropertyButton}" />
...
</controls:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>

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

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

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

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

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

<tab name="Mobile">
<source lang="xml">
<Button
x:Name="SetCurrentDateTimeButton"
Command="{Binding SetPropertyValueCommand}"
Text="Set Property">
<Button.CommandParameter>
<classes:KeyValueList>
<classes:KeyValueParameter Key="PropertyName" Value="MP_PROPERTY" />
<classes:KeyValueParameter Key="PropertyValue" Value="{Binding BindingContext.AppStatus.LiveDateTime, Source={x:Reference SetCurrentDateTimeButton}}" />
<classes:KeyValueParameter Key="OnlyForUnvalidated" Value="false" />
<classes:KeyValueParameter Key="AutoSave" Value="true" />
<classes:KeyValueParameter Key="AutoCommit" Value="true" />
</classes:KeyValueList>
</Button.CommandParameter>
</Button>
</source>
</tab>
</tabs>

<br>

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Localizing UI Texts ====
The most efficient practice is to use pre-localized texts from the standard client, however, this is not always possible, especially in custom UIs. The ObjectByUID indexer was therefore initially developed as a technique to allow localization of custom UI label texts.

The concept is to create an infrastructure object that carries metaproperties for localized texts, then bind to this infrastructure object using ObjectByUID, and bind to a specific metaproperty to receive it's localized Description text as follows:
<source lang = "xml">
"{Binding ObjectByUID[paste-your-uid].Properties.VisibleItems[add-your-property-name].Description}"
</source>

From here there are two approaches; the database-leaning one is to add one metaproperty per UI label, and simply bind to the Description of it. However, this shifts maintenance effort to the UBIK Studio after the initial adding of the label in XAML. Another approach would be to use the metaproperty to provide a "tag" that the xaml customizer can then use to differentiate between hardcoded labels.

A third approach would be to create one infrastructure object per label, however, this can lead to many objects being loaded upon startup.

{| class="wikitable"
|-
! Approach !! Implementation !! Maintenance Effort !! Recommendation
|-
| One metaproperty per UI Label || Bind the label text to the metaproperty Description || Database / UBIK Studio || Recommended for UWP, customizings with fewer UI texts, finalized customizings.
|-
| One metaproperty delivering a localization "tag" (such as: "EN" / "DE") || Use something like DataTrigger (Mobile) to hardcode a different localized text per tag (such as: "eg." / "zb.") || XAML || Recommended for Mobile, highly customized UIs with many texts, customizings that tend to change often.
|}
<br>
<br>

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

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

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

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

=== Icons ===
UBIK comes equipped with a collection of icons that can be easily used in your customizing. [[Icon_Font|Here is an indepth explanation on usage]].

In the case that you require an icon that is not included in our icon font file, there is the possibility to use SVG path data to render your required icon in the UI.
<br>

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

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

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

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

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

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

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

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

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

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

<br>
<br>

[[Category:Client|XAML Tips]]
[[Category:Mobile|XAML Tips]]
[[Category:WinX|XAML Tips]]
[[Category:XAML|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="Mobile(Xamarin)">
<source lang = "xml">
<tabView:SfTabView EnableVirtualization="true">
...
</tabView:SfTabView>
</source>
</tab>
</tabs>

=== Default Tab Selection ===
The tab selection in UBIKContentView defaults to the first tab, which is Children objects. However, for cases where it makes more sense to display Properties or Documents by default, it is possible to change the tab selection using the following classifications:
* [[SYSCLS_SHOWDOCUMENTS]]
* [[SYSCLS_SHOWPROPERTIES]]

<tabs>
<tab name="UWP">
Adding the classification to a metaclass is enough for UWP.
</tab>
<tab name="Mobile(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].

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

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

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

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

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

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

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

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

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

Instead, we should either use the '''multi-tag syntax''' or the '''inline syntax''' for OnPlatform / OnIdiom.

==== Multi-tag syntax ====
Here it is mandatory to add '''x:TypeArguments="TheType"''' with the proper type to OnPlatfrom/OnIdiom. ''Default="..."'' is optional and can be added like in the following example if a default value needs to be defined.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<OnPlatform x:TypeArguments="Thickness" Default="20">
<On Platform="iOS, WinUI" Value="0,20,0,0" />
<On Platform="Android" Value="10,20,20,10" />
</OnPlatform>
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<OnIdiom x:TypeArguments="Thickness" Default="20">
<OnIdiom.Desktop>0,60,0,0</OnIdiom.Desktop>
</OnIdiom>
</source>
</tab>
</tabs>

If OnPlatform Values contain multiple subtags, the following syntax can be used:
<source lang = "XML">
<ControlTemplate x:Key="ExampleControlTemplate">
<Grid>
<OnPlatform x:TypeArguments="View">
<On Platform="Android">
<Button
...
Text="Button A" />
...
</On>
<On Platform="iOS">
<Button
...
Text="Button B" />
...
</On>
<On Platform="WinUI">
<Grid>
<Button
...
Text="Button C" />
<Label Text="Example" />
...
</Grid>
</On>
</OnPlatform>
</Grid>
</ControlTemplate>
</source>

{{Attention|When using ''GridLength'' as a type in OnPlatform/OnIdiom, it should only be used in combination with the inline syntax.}}

==== Inline syntax ====
When using the inline syntax, the type should not be specified. ''Default='' is optional.
<tabs>
<tab name="OnPlatform">
<source lang = "XML">
<BoxView Color="{OnPlatform Default=Yellow, iOS=Red, Android=Green}" />
</source>
</tab>
<tab name="OnIdiom">
<source lang = "XML">
<BoxView Color="{OnIdiom Default=Yellow, Phone=Red, Tablet=Green}" />
</source>
</tab>
</tabs>

If the value contains any special characters like <code>"</code> or <code>,</code> or a '''string''' when using the OnIdiom or OnPlatform inline variant, it needs to be wrapped between <code>' '</code>. But be careful with using apostrophes - when using them around curly brackets {} it can lead to an error.
<tabs>
<tab name="Don't">
<source lang = "XML">
Margin="{OnIdiom 10,2, Phone=2,0}"
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Margin="{OnIdiom '10,2', Phone='2,0'}"
</source>
</tab>
</tabs>

=== Complex values ===
If the OnPlatform/OnIdiom value contains a '''Binding''', '''StaticResource''' or any other complex value in curly brackets, it is recommended to use the '''inline syntax'''. Although it's not confirmed in any official documentation, it seems to work according to our experience. However, the multi-tag syntax doesn't always seem to work for such cases. DynamicResource values seem to be not supported at all in OnIdiom / OnPlatform.

<tabs>
<tab name="Don't">
<source lang = "XML">
<OnIdiom x:TypeArguments="..." Default="{Binding ...}">
<OnIdiom.Phone>{Binding ...}</OnIdiom.Phone>
</OnIdiom>
</source>
</tab>
<tab name="Instead do">
<source lang = "XML">
Header="{OnIdiom Default={Binding ...}, Phone={Binding ...}}"
</source>
</tab>
</tabs>

{{Attention|Unreliable Support: Behavior may vary when using bindings or complex resources. Although it seems to work with the inline syntax according to our experiences, it is recommended to test these edge cases thoroughly.}}

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

Version 5.1 (Mobile)

2026-03-17T09:39:04Z

REP:

Version 5.1 (Mobile)

2026-03-17T09:38:43Z

REP: small update to Icon set Addition 8

Version 5.1 (Mobile)

2026-03-12T16:57:43Z

REP: /* Release */

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

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