{{UBIK}} ActiveLists provide the possibility to configure instance-specific lists for integer MetaProperties.

= Purpose =
In some cases it is required to define a list of selectable values for an integer MetaProperty that is specific to a single instance rather than globally defined at the MetaClass level. For example, two instances of the same MetaClass can offer different selectable values for the same MetaProperty.

{{UBIK}} ActiveLists are the representation of such lists. They update dynamically on the client side without requiring an ACM rebuild and can be maintained per instance through server methods.

If a MetaProperty has both a SelectiveList and an ActiveList, the SelectiveList takes precedence when data is displayed on the client, and the ActiveList is ignored.

= Client Behavior =
When the user opens an ActiveList:
* The label for each option is shown in the language configured on the web service. If a translation for the configured language is unavailable, the label is displayed in the default language.
* Each option in the ActiveList has an associated unique integer value that is set to the MetaProperty when selected.
* Only one option can be selected at a time. Selecting an option updates the MetaProperty value immediately.

Sorting of items in the dropdown:

* If all options in the ActiveList have unique sort order values, they are displayed in ascending order of these sort order values.
* If sort orders are not unique, options with the same sort order are sorted in ascending order by their label.

For more details see: [[Active List Client]]

= Server-Side Concept =
ActiveLists are stored in serialized JSON form in the '''ACTIVE_LISTS''' property of the instance.

* Each list is associated with exactly one integer MetaProperty of the instance.
* An instance can have multiple ActiveLists, one for each integer MetaProperty.
* ActiveLists can be viewed in UBIK.Studio in the Object Explorer under “ActiveLists” for the instance, but they cannot be edited there.

= Managing {{UBIK}} ActiveLists =
ActiveLists are managed entirely through server methods. The most relevant methods are:

=== AddOrUpdateActiveList(metaProperty, value, labels, sortOrder) ===
Adds a new list item or updates the labels of an existing one. Optionally repositions the item according to sortOrder.

=== SortActiveList(metaProperty, orderedValues) ===
Reorders the items of a list according to the specified sequence. Items not included in '''orderedValues''' are appended in their current order.

=== RemoveActiveListItem(metaProperty, value) ===
Removes a single list item by its integer value.

=== RemoveActiveList(metaProperty) ===
Removes the entire list for the given MetaProperty.

=== GetActiveLists() ===
Returns all ActiveLists defined on the instance as '''UbikActiveList''' objects, each containing the MetaProperty name and its list items.

= Who-Bert Example =
The following Who-Bert snippet demonstrates how to work with an ActiveList for a MetaProperty named "'''MP_INT_A'''":

<syntaxhighlight lang="csharp">
using System;
using System.Windows.Forms;
using System.Linq;
using System.Collections.Generic;
using UBIK.Kernel;
using UBIK.Runtime;
using UBIK.Runtime.Sys;
using UBIK.Compiler;
using UBIK.Content;

namespace Studio
{
public class ObjectTest
{
public void TestObject(params BaseClass[] InVariables)
{
Debugger.Output(this, "*** Started ActiveList Example");
foreach (BaseClass obj in InVariables)
{
ContentClass c = obj as ContentClass;

var labels1 = new Dictionary<string, string> { { "en", "One" }, { "de", "Eins" } };
var labels2 = new Dictionary<string, string> { { "en", "Two" }, { "de", "Zwei" } };
var labels3 = new Dictionary<string, string> { { "en", "Three" }, { "de", "Drei" } };

// Add items
c.AddOrUpdateActiveList("MP_INT_A", 1, labels1);
c.AddOrUpdateActiveList("MP_INT_A", 2, labels2);
c.AddOrUpdateActiveList("MP_INT_A", 3, labels3);

// Update labels and move item 3 to index 0
var labels3Updated = new Dictionary<string, string> { { "en", "Three Updated" }, { "de", "Drei Aktualisiert" } };
c.AddOrUpdateActiveList("MP_INT_A", 3, labels3Updated, 0);

// Sort items: 2, 1, 3
c.SortActiveList("MP_INT_A", new int[] { 2, 1, 3 });

// Remove item 1
c.RemoveActiveListItem("MP_INT_A", 1);

c.Save();
}
Debugger.Output(this, "*** Finished ActiveList Example");
}
}
} </syntaxhighlight>

= Further Notes =

* ActiveLists are designed for lightweight, instance-specific value lists that can be updated without ACM rebuilds.
* They are ideal for use cases where list content varies between instances of the same MetaClass.
* When both an ActiveList and a SelectiveList are defined for the same MetaProperty, the SelectiveList overrides the ActiveList on the client.

[[Category:ActiveList|UBIK Active Lists]]
[[Category:Server|UBIK Active Lists]]

2026-04-17T08:32:40Z

ARU:

{{UnderConstructionStart}}

When an integer MetaProperty has an ActiveList defined, the property is displayed using the existing icon (the same icon applied to properties with a SelectiveList), followed by the property's display string and the label of the currently selected list item in a closed drop-down component{{Version/ServerSince|5.0.0.0}}.

For editing, the client uses a dropdown menu UI component. The dropdown menu enables users to select exactly one value for the MetaProperty from the ActiveList.
When the user opens the dropdown:

* All available options from the ActiveList are displayed as text labels.
* The label for each option is shown in the language configured on the web service. If a translation for the configured language is unavailable, the label is displayed in the default language.
* Each option in the ActiveList has an associated unique integer value that is set to the MetaProperty when selected.
* Only one option can be selected at a time. Selecting an option updates the MetaProperty value immediately.

Sorting of items in the dropdown:

* If all options in the ActiveList have unique sort order values, they are displayed in ascending order of these sort order values.
* If sort orders are not unique, options with the same sort order are sorted in ascending order by their label.

{{UnderConstructionEnd}}

[[Category:Client|Active List Client]]
[[Category:Active List|Active List Client]]

Active List Client

2026-04-17T08:30:58Z

ARU: Created page with "{{UnderConstructionStart}} When an integer MetaProperty has an ActiveList defined, the property is displayed using the existing icon (the same icon applied to properties with..."

Category:Active List

2026-04-17T08:26:58Z

ARU: Created page with "Category:Client"

[[Category:Client]]

UBIK Active Lists

2026-04-17T08:25:26Z

ARU: /* Client Behavior */

{{UBIK}} ActiveLists provide the possibility to configure instance-specific lists for integer MetaProperties.

= Purpose =
In some cases it is required to define a list of selectable values for an integer MetaProperty that is specific to a single instance rather than globally defined at the MetaClass level. For example, two instances of the same MetaClass can offer different selectable values for the same MetaProperty.

{{UBIK}} ActiveLists are the representation of such lists. They update dynamically on the client side without requiring an ACM rebuild and can be maintained per instance through server methods.

If a MetaProperty has both a SelectiveList and an ActiveList, the SelectiveList takes precedence when data is displayed on the client, and the ActiveList is ignored.

= Client Behavior =
See also [[Active List Client]]

[[Category:ActiveList|UBIK Active Lists]]
[[Category:Server|UBIK Active Lists]]

= Server-Side Concept =
ActiveLists are stored in serialized JSON form in the '''ACTIVE_LISTS''' property of the instance.

* Each list is associated with exactly one integer MetaProperty of the instance.
* An instance can have multiple ActiveLists, one for each integer MetaProperty.
* ActiveLists can be viewed in UBIK.Studio in the Object Explorer under “ActiveLists” for the instance, but they cannot be edited there.

= Managing {{UBIK}} ActiveLists =
ActiveLists are managed entirely through server methods. The most relevant methods are:

=== AddOrUpdateActiveList(metaProperty, value, labels, sortOrder) ===
Adds a new list item or updates the labels of an existing one. Optionally repositions the item according to sortOrder.

=== SortActiveList(metaProperty, orderedValues) ===
Reorders the items of a list according to the specified sequence. Items not included in '''orderedValues''' are appended in their current order.

=== RemoveActiveListItem(metaProperty, value) ===
Removes a single list item by its integer value.

=== RemoveActiveList(metaProperty) ===
Removes the entire list for the given MetaProperty.

=== GetActiveLists() ===
Returns all ActiveLists defined on the instance as '''UbikActiveList''' objects, each containing the MetaProperty name and its list items.

= Who-Bert Example =
The following Who-Bert snippet demonstrates how to work with an ActiveList for a MetaProperty named "'''MP_INT_A'''":

<syntaxhighlight lang="csharp">
using System;
using System.Windows.Forms;
using System.Linq;
using System.Collections.Generic;
using UBIK.Kernel;
using UBIK.Runtime;
using UBIK.Runtime.Sys;
using UBIK.Compiler;
using UBIK.Content;

namespace Studio
{
public class ObjectTest
{
public void TestObject(params BaseClass[] InVariables)
{
Debugger.Output(this, "*** Started ActiveList Example");
foreach (BaseClass obj in InVariables)
{
ContentClass c = obj as ContentClass;

var labels1 = new Dictionary<string, string> { { "en", "One" }, { "de", "Eins" } };
var labels2 = new Dictionary<string, string> { { "en", "Two" }, { "de", "Zwei" } };
var labels3 = new Dictionary<string, string> { { "en", "Three" }, { "de", "Drei" } };

// Add items
c.AddOrUpdateActiveList("MP_INT_A", 1, labels1);
c.AddOrUpdateActiveList("MP_INT_A", 2, labels2);
c.AddOrUpdateActiveList("MP_INT_A", 3, labels3);

// Update labels and move item 3 to index 0
var labels3Updated = new Dictionary<string, string> { { "en", "Three Updated" }, { "de", "Drei Aktualisiert" } };
c.AddOrUpdateActiveList("MP_INT_A", 3, labels3Updated, 0);

// Sort items: 2, 1, 3
c.SortActiveList("MP_INT_A", new int[] { 2, 1, 3 });

// Remove item 1
c.RemoveActiveListItem("MP_INT_A", 1);

c.Save();
}
Debugger.Output(this, "*** Finished ActiveList Example");
}
}
} </syntaxhighlight>

[[Category:ActiveList|UBIK Active Lists]]
[[Category:Server|UBIK Active Lists]]

= Further Notes =

* ActiveLists are designed for lightweight, instance-specific value lists that can be updated without ACM rebuilds.
* They are ideal for use cases where list content varies between instances of the same MetaClass.
* When both an ActiveList and a SelectiveList are defined for the same MetaProperty, the SelectiveList overrides the ActiveList on the client.

[[Category:Server|UBIK Active Lists]]
[[Category:ActiveList|UBIK Active Lists]]

Version 5.1 (Mobile)

2026-03-23T13:56:59Z

ARU: /* Release */

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

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

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

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

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

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

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

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

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

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

= Release Notes =

== Release ==
=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Introduced a new [[MRO_Objects_(Client)#Picture_Task|picture task]] type which can only be finished when there's at least one valid child document.
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]
* Replaced app closing after repeated failed login attempts with a client-side temporary login block, including user feedback that indicates when login becomes available again.
* Added French localization to the app.
* [[MRO_Objects_(Client)#Signature_Task|MRO Signature Tasks]] have been introduced, which automatically displays the signee as well as the validation timestamp after the task has been signed.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.
* Fixed an issue where the application crashed on Windows when navigating back from the VideoPlayer.
* Icon set Addition 8: 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.

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

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

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

Version 5.1 (Mobile)

2026-03-10T09:58:15Z

ARU: /* 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}} ===
* 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.

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

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

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

MRO (Plugin)

2026-03-02T15:47:22Z

ARU:

The MRO plugin provides a set of {{UBIK}} objects which allow to represent and document maintenance, repair and operations work on the mobile client. An respective implementation of this set of features is available on {{UBIK WinX}}.

== Basic Features ==
Objects classified as MRO objects in general provide a technical and organisational status as well as the overall work progress based on the underlying data branch.

=== Technical Status ===
For detailed information, see [[MRO Objects (Client)#Technical Status|Technical Status]]

=== Organisational Status ===
For detailed information, see [[MRO Objects (Client)#Organisational Status|Organisational Status]]

=== Work Progress ===
For detailed information, see [[MRO Objects (Client)#Work Progress|Work Progress]]

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====
A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken).

==== Progress Task ====
[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

==== Check Task ====
[[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.

==== Inspection Task ====
A [[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).

== MRO Implemented Objects ==
A set of specific objects extending functionalities of existing MRO elements.<br />
For Task Objects, Value properties are assigned by default and implement necessary classifications.

=== Procedure Workpackage ===
A [[MROCLS_PROCEDURE|Procedure Workpackage]] is a specialized type of [[MROCLS_MRO_WORKPACKAGE|Work Package]] designed to model complex workflows. It consists of sequential tasks that can include branching logic, modular structures, and references to linked data. Procedure Workpackages allow the execution of structured processes that may adapt dynamically depending on conditions. They support both online and offline execution, with certain steps (e.g. data exchange) triggered once connectivity is available.

=== Switch Start Task ===
A [[MROCLS_SWITCH_START_TASK|Switch Start Task]] is a type of sequential task used within a Procedure Workpackage to define branching logic. It evaluates a predefined (boolean) condition, which can be checked by the client, to determine which branch (true or false) of the workflow will be followed. Each branch represents a different execution path composed of its own set of tasks. A Switch Start Task always requires a corresponding [[MROCLS_SWITCH_END_TASK|Switch End Task]], where all branches converge and the unified procedure continues.

=== Switch End Task ===
A [[MROCLS_SWITCH_END_TASK|Switch End Task]] marks the end of a branching structure initiated by a [[MROCLS_SWITCH_TASK|Switch Task]]. It is a sequential task that connects the different branches back into a single workflow path. Each Switch End Task is directly linked to its respective Switch Task and ensures that, regardless of which branch was taken, the overall procedure continues in a consistent and controlled manner.

=== Check Task ===
A [[MRO_Implemented_Objects|Check Task]] allows the user to check the task as completed or Not Applicable.

=== Numeric Task ===
A [[MRO_Implemented_Objects|Numeric Task]] allows the user to input a numeric value (double). It includes a defined value range, and if the entered value falls outside this range, the task is visually marked as problematic.

=== Inspection Task ===
An [[MRO_Implemented_Objects|Inspection Task]] presents the user with two customizable buttons representing different inspection outcomes, along with a Not Applicable option. The labels of the buttons can be defined during the procedure creation.

=== Text Task ===
A [[MRO_Implemented_Objects|Text Task]] provides a text input field for the user to enter free-form information. This task is useful for capturing qualitative data or comments during the procedure.

=== Picture Task ===
A [[MRO_Implemented_Objects|Picture Task]] enables the user to take and attach one or more photos. It includes a button to initiate the camera and another to confirm the task. The confirmation button remains disabled until at least one picture has been successfully captured.

=== Dynamic List Task ===
A [[MRO_Implemented_Objects|Dynamic List Task]] presents a button that, when clicked, displays a list of selectable options. These options are defined by the procedure creator and can vary depending on the context. This task is ideal for scenarios requiring user selection from a predefined but flexible set of choices.

=== Supervisor Task ===
A [[MRO_Implemented_Objects|Supervisor Task]] includes a button for NFC reading. If a supervisor successfully authenticates, it enables confirmation buttons, input fields, or other interactive elements.

=== Interface Task ===
An [[MRO_Implemented_Objects|Interface Task]] performs a REST API request automatically when it becomes active. It does not include any visible buttons or user interaction. Once the server responds, the task is automatically confirmed based on the response.

=== Calculation Task ===
A [[MRO_Implemented_Objects|Calculation Task]] is used to evaluate a predefined expression and apply its result to a predefined property on its owner. It supports logical or numerical expressions. The result type is defined explicitly to ensure correct handling and validation by the client.

=== Signature Task ===
Signature Task prompts the user to provide a written signature to confirm task completion. The task is marked complete once the signature is submitted.

== See also ==
* [[MROCLS_MRO_TASKOWNER#Task Owner]] (Classification)
* [[MROCLS_MRO_WORKPACKAGE#Work Package]] (Classification)
* [[MROCLS_MRO_TASK#Task]] (Classification)
* [[MROCLS_MRO_MEASUREMENT_TASK#Measurement Task]] (Classification)
* [[MROCLS_MRO_PROGRESS_TASK# Progress Task]] (Classification)
* [[MROCLS_MRO_CHECK_TASK#Check Task]] (Classification)
* [[MROCLS_MRO_INSPECTION_TASK#Inspection Task]] (Classification)
* [[MROCLS_SEQUENTIALTASK]] (Classification)
* [[MROCLS_GROUPEDTASK]] (Classification)
* [[MROCLS_PROJECT]] (Classification)
* [[MROCLS_PROJECTINFORMATION]] (Classification)
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_START_TASK#Switch Start Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Module|MRO (Plugin)]]

MRO Objects (Client)

2026-03-02T15:45:19Z

ARU: /* MRO Objects */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

==== Signature Task {{Version/MobileSince|5.1}} ====

The Signature Task is a task type that is completed by capturing a handwritten signature from the user. The task contains an editor field that serves as the entry point for the signing process. When the user clicks (or taps) on the editor field, a signature dialog opens. Within this dialog, the user can provide their signature. After confirming the input, the signature is saved and the task is automatically marked as completed.

If the task is signed while the client is online:
* The User (signee) is resolved immediately by the server and displayed.
* The ValidationTimestamp is generated and displayed.
* Both values are shown directly in the editor field after signing.

{{Hint|The User only gets resolved by the server and displayed once you're in online mode}}

If the displayed User and/or ValidationTimestamp cannot be fully shown due to limited space in the editor field, the complete information can be accessed via a tooltip.

* In '''UBIK WinX (UWP)''', hover over the editor field with the mouse.
* In '''UBIK Mobile''', perform a long press on the editor field.
A tooltip will appear, displaying the full User and ValidationTimestamp without truncation.

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

Version 5.1 (Mobile)

2026-03-02T15:43:47Z

ARU: /* 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}} ===
* 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.

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

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

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

MRO Objects (Client)

2026-03-02T14:00:35Z

ARU: /* MRO Objects */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

==== Signature Task ====

The Signature Task is a task type that is completed by capturing a handwritten signature from the user. The task contains an editor field that serves as the entry point for the signing process. When the user clicks (or taps) on the editor field, a signature dialog opens. Within this dialog, the user can provide their signature. After confirming the input, the signature is saved and the task is automatically marked as completed.

If the task is signed while the client is online:
* The User (signee) is resolved immediately by the server and displayed.
* The ValidationTimestamp is generated and displayed.
* Both values are shown directly in the editor field after signing.

{{Hint|The User only gets resolved by the server and displayed once you're in online mode}}

If the displayed User and/or ValidationTimestamp cannot be fully shown due to limited space in the editor field, the complete information can be accessed via a tooltip.

* In '''UBIK WinX (UWP)''', hover over the editor field with the mouse.
* In '''UBIK Mobile''', perform a long press on the editor field.
A tooltip will appear, displaying the full User and ValidationTimestamp without truncation.

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

MRO Objects (Client)

2026-03-02T13:42:54Z

ARU: /* Technical Status */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

{{UnderConstructionStart}}

==== Signature Task ====

The Signature Task is a task type that is completed by capturing a handwritten signature from the user. The task contains an editor field that serves as the entry point for the signing process. When the user clicks (or taps) on the editor field, a signature dialog opens. Within this dialog, the user can provide their signature. After confirming the input, the signature is saved and the task is automatically marked as completed.

'''Online Mode''' <br/>
If the task is signed while the client is online:
* The User (signee) is resolved immediately by the server and displayed.
* The ValidationTimestamp is generated and displayed.
* Both values are shown directly in the editor field after signing.
<br/>
'''Offline Mode''' <br/>
If the task is signed while the client is offline:
* The ValidationTimestamp is generated locally and displayed.
* The User cannot yet be resolved by the server; therefore, no user information is displayed at this time. <br/>
As soon as the client reconnects and goes back online, the User is resolved by the server and the editor field is updated accordingly.

If the displayed User and/or ValidationTimestamp cannot be fully shown due to limited space in the editor field, the complete information can be accessed via a tooltip.

* In '''UWP''', hover over the editor field with the mouse.
* In '''MAUI''', perform a long press on the editor field.
A tooltip will appear, displaying the full User and ValidationTimestamp without truncation.

{{UnderConstructionEnd}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

MRO Objects (Client)

2026-03-02T12:55:06Z

ARU:

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===
{{UnderConstructionStart}}

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

{{UnderConstructionEnd}}

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

{{UnderConstructionStart}}

==== Signature Task ====

The Signature Task is a task type that is completed by capturing a handwritten signature from the user. The task contains an editor field that serves as the entry point for the signing process. When the user clicks (or taps) on the editor field, a signature dialog opens. Within this dialog, the user can provide their signature. After confirming the input, the signature is saved and the task is automatically marked as completed.

'''Online Mode''' <br/>
If the task is signed while the client is online:
* The User (signee) is resolved immediately by the server and displayed.
* The ValidationTimestamp is generated and displayed.
* Both values are shown directly in the editor field after signing.
<br/>
'''Offline Mode''' <br/>
If the task is signed while the client is offline:
* The ValidationTimestamp is generated locally and displayed.
* The User cannot yet be resolved by the server; therefore, no user information is displayed at this time. <br/>
As soon as the client reconnects and goes back online, the User is resolved by the server and the editor field is updated accordingly.

If the displayed User and/or ValidationTimestamp cannot be fully shown due to limited space in the editor field, the complete information can be accessed via a tooltip.

* In '''UWP''', hover over the editor field with the mouse.
* In '''MAUI''', perform a long press on the editor field.
A tooltip will appear, displaying the full User and ValidationTimestamp without truncation.

{{UnderConstructionEnd}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

Version 5.1 (Mobile)

2026-03-02T12:25:36Z

ARU: /* 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}} ===
* 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.
* A standard for MRO Signature Tasks has been introduced, which automatically displays the signee as well as the validation date after the task has been signed.

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

=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded.
* Fixed an issue where changes in property editing were not discarded when using the default Back button.

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

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

MRO Objects (Client)

2026-03-02T12:24:52Z

ARU:

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===
{{UnderConstructionStart}}

The technical status indicator is shown on all objects that represent a technical state or receive the technical status from subsequent objects in the underlying data branch. If e.g. a inventory object is reported as damaged, its parent objects will all display the exclamation mark symbol to indicate that a problem was reported in the child items.

{{UnderConstructionEnd}}

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

Version 5.1 (Mobile)

2026-03-02T08:00:21Z

ARU:

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

=== 5.1.?? 2026-??-?? {{key press|Android: Store}}{{key press|iOS: Store}} ===
* Fixed an issue that prevented any documents from being uploaded.
* Fixed an issue where changes were not discarded when using the default Back button.

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

Version 5.1 (Mobile)

2026-02-17T10:44:54Z

ARU: /* 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}} ===
* The system flashlight can now also be enabled or disabled via XAML customization. For detailed information, see [[Mobile XAML#Flashlight|Flashlight]]

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

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

Version 5.1 (Mobile)

2026-02-17T10:37:44Z

ARU:

{{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}} ===
* The system flashlight can now also be enabled or disabled via XAML customization.

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

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

= ⚠️ XAML Notes =
Due to the change of the underlying XAML technology, the existing XAMLs for the old mobile clients (pre 5.0) are no longer compatible. Please refer to [[HowTo:Convert_Xamarin_XAMLs_to_Maui]] for migrating them to the new client.

<headertabs />

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

Mobile XAML

2026-02-17T10:07:10Z

ARU: /* Feature related */

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

Mobile XAML

2026-02-17T09:32:08Z

ARU: /* General performance tips */

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

{{UnderConstructionStart}}

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

{{UnderConstructionEnd}}

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

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

Mobile XAML

2026-02-17T09:31:37Z

ARU: /* Feature related */

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

{{UnderConstructionStart}}

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

{{UnderConstructionEnd}}

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

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

Mobile XAML

2026-02-17T06:54:49Z

ARU: /* Feature related */

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

{{UnderConstructionStart}}

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

{{UnderConstructionEnd}}

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

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

MRO (Plugin)

2026-02-10T08:31:40Z

ARU: /* Basic Features */

The MRO plugin provides a set of {{UBIK}} objects which allow to represent and document maintenance, repair and operations work on the mobile client. An respective implementation of this set of features is available on {{UBIK WinX}}.

{{UnderConstructionStart}}

== Basic Features ==
Objects classified as MRO objects in general provide a technical and organisational status as well as the overall work progress based on the underlying data branch.

=== Technical Status ===
For detailed information, see [[MRO Objects (Client)#Technical Status|Technical Status]]

=== Organisational Status ===
For detailed information, see [[MRO Objects (Client)#Organisational Status|Organisational Status]]

=== Work Progress ===
For detailed information, see [[MRO Objects (Client)#Work Progress|Work Progress]]

{{UnderConstructionEnd}}

[[Category:Module|MRO (Plugin)]]

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====
A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken).

==== Progress Task ====
[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

==== Check Task ====
[[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.

==== Inspection Task ====
A [[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).

== MRO Implemented Objects ==
A set of specific objects extending functionalities of existing MRO elements.<br />
For Task Objects, Value properties are assigned by default and implement necessary classifications.

=== Procedure Workpackage ===
A [[MROCLS_PROCEDURE|Procedure Workpackage]] is a specialized type of [[MROCLS_MRO_WORKPACKAGE|Work Package]] designed to model complex workflows. It consists of sequential tasks that can include branching logic, modular structures, and references to linked data. Procedure Workpackages allow the execution of structured processes that may adapt dynamically depending on conditions. They support both online and offline execution, with certain steps (e.g. data exchange) triggered once connectivity is available.

=== Switch Start Task ===
A [[MROCLS_SWITCH_START_TASK|Switch Start Task]] is a type of sequential task used within a Procedure Workpackage to define branching logic. It evaluates a predefined (boolean) condition, which can be checked by the client, to determine which branch (true or false) of the workflow will be followed. Each branch represents a different execution path composed of its own set of tasks. A Switch Start Task always requires a corresponding [[MROCLS_SWITCH_END_TASK|Switch End Task]], where all branches converge and the unified procedure continues.

=== Switch End Task ===
A [[MROCLS_SWITCH_END_TASK|Switch End Task]] marks the end of a branching structure initiated by a [[MROCLS_SWITCH_TASK|Switch Task]]. It is a sequential task that connects the different branches back into a single workflow path. Each Switch End Task is directly linked to its respective Switch Task and ensures that, regardless of which branch was taken, the overall procedure continues in a consistent and controlled manner.

=== Check Task ===
A [[MRO_Implemented_Objects|Check Task]] allows the user to check the task as completed or Not Applicable.

=== Numeric Task ===
A [[MRO_Implemented_Objects|Numeric Task]] allows the user to input a numeric value (double). It includes a defined value range, and if the entered value falls outside this range, the task is visually marked as problematic.

=== Inspection Task ===
An [[MRO_Implemented_Objects|Inspection Task]] presents the user with two customizable buttons representing different inspection outcomes, along with a Not Applicable option. The labels of the buttons can be defined during the procedure creation.

=== Text Task ===
A [[MRO_Implemented_Objects|Text Task]] provides a text input field for the user to enter free-form information. This task is useful for capturing qualitative data or comments during the procedure.

=== Picture Task ===
A [[MRO_Implemented_Objects|Picture Task]] enables the user to take and attach one or more photos. It includes a button to initiate the camera and another to confirm the task. The confirmation button remains disabled until at least one picture has been successfully captured.

=== Dynamic List Task ===
A [[MRO_Implemented_Objects|Dynamic List Task]] presents a button that, when clicked, displays a list of selectable options. These options are defined by the procedure creator and can vary depending on the context. This task is ideal for scenarios requiring user selection from a predefined but flexible set of choices.

=== Supervisor Task ===
A [[MRO_Implemented_Objects|Supervisor Task]] includes a button for NFC reading. If a supervisor successfully authenticates, it enables confirmation buttons, input fields, or other interactive elements.

=== Interface Task ===
An [[MRO_Implemented_Objects|Interface Task]] performs a REST API request automatically when it becomes active. It does not include any visible buttons or user interaction. Once the server responds, the task is automatically confirmed based on the response.

=== Calculation Task ===
A [[MRO_Implemented_Objects|Calculation Task]] is used to evaluate a predefined expression and apply its result to a predefined property on its owner. It supports logical or numerical expressions. The result type is defined explicitly to ensure correct handling and validation by the client.

[[Category:Module|MRO (Plugin)]]

=== Signature Task ===
Signature Task prompts the user to provide a written signature to confirm task completion. The task is marked complete once the signature is submitted.

[[Category:Module|MRO (Plugin)]]

== See also ==
* [[MROCLS_MRO_TASKOWNER#Task Owner]] (Classification)
* [[MROCLS_MRO_WORKPACKAGE#Work Package]] (Classification)
* [[MROCLS_MRO_TASK#Task]] (Classification)
* [[MROCLS_MRO_MEASUREMENT_TASK#Measurement Task]] (Classification)
* [[MROCLS_MRO_PROGRESS_TASK# Progress Task]] (Classification)
* [[MROCLS_MRO_CHECK_TASK#Check Task]] (Classification)
* [[MROCLS_MRO_INSPECTION_TASK#Inspection Task]] (Classification)
* [[MROCLS_SEQUENTIALTASK]] (Classification)
* [[MROCLS_GROUPEDTASK]] (Classification)
* [[MROCLS_PROJECT]] (Classification)
* [[MROCLS_PROJECTINFORMATION]] (Classification)
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_START_TASK#Switch Start Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Module|MRO (Plugin)]]

MRO Objects (Client)

2026-02-10T08:31:35Z

ARU: /* Basic User Interface */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

{{UnderConstructionStart}}
== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===
The technical status indicates whether all tasks on an object or on its subsequent objects within the underlying data branch have been completed. It also aggregates additional state information, such as issues reported on child items. For example, if an inventory object is marked as damaged, this status is propagated to its parent objects, which will display a corresponding indicator (an exclamation mark) to signal a problem originating from a child item.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}
{{UnderConstructionEnd}}

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

MRO Objects (Client)

2026-02-10T08:25:01Z

ARU: /* Basic User Interface */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

{{UnderConstructionStart}}
== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===
The technical status indicates whether all tasks on an object or on its subsequent objects within the underlying data branch have been completed. It also aggregates additional state information, such as issues reported on child items. For example, if an inventory object is marked as damaged, this status is propagated to its parent objects, which will display a corresponding indicator (an exclamation mark) to signal a problem originating from a child item.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

=== Organisational Status ===
The organisational status indicates the amount of confirmed work within the data branch, including already confirmed work packages as well as tasks that are locked by their owning work package. The organisational status indicator is displayed on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch, and visualizes the amount of confirmed work performed within that branch.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is shown on all objects that represent the current work progress or receive the work progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}
{{UnderConstructionEnd}}

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

MRO Objects (Client)

2026-02-10T08:14:39Z

ARU: /* Technical Status */

[[File:UI_WinX_MRO_ChildList.png|thumb|alt=MRO Child List UI (WinX)|MRO UI (WinX)]]
[[File:Android_mro_ui.jpg|thumb|alt=MRO Child List UI (Android)|MRO UI (Android)]]
The WinX client UI displays MRO configured objects like any other root- or child-object enriched by some additional logic and features.

== Basic User Interface ==
The representation of MRO features comprises some indicators and interactive controls. In the {{UBIK}} child list, the main object displays cumulated technical and organisational status as well as the overall work progress based on the underlying data branch. Objects classified as MRO objects in general provide indicators for the MRO status. This means the status is shown next to the main icon of a child-/details-/documents-page as well as next to the icons of the child list items:

=== Technical Status ===
The technical status indicates whether all tasks on an object or on its subsequent objects within the underlying data branch have been completed. It also aggregates additional state information, such as issues reported on child items. For example, if an inventory object is marked as damaged, this status is propagated to its parent objects, which will display a corresponding indicator (an exclamation mark) to signal a problem originating from a child item.

<gallery>
File:UI_WinX_MRO_TechnicalStatusIndicator.png|thumb|Technical Status Indicator (WinX)
File:Android_tech_status.PNG|thumb|Technical Status Indicator (Android)
</gallery>

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

=== Organisational Status ===
The organisational status indicator is shown on all objects that represent an organisational state or receive the organisational status from subsequent objects in the underlying data branch. This indicator shows the amount of confirmed work done in the data branch. It can as well display a work package to be already confirmed or show tasks that are already locked by their owning workpackage.
<gallery>
File:UI_WinX_MRO_OrganisationalStatusIndicator.png|Organisational Status Indicator (WinX)
File:UI_WinX_MRO_WPConfirmedIndicator.png|MRO Workpackage Confirmed (Flag) Indicator (WinX)
File:Android_orga_status.PNG|Organisational Status Indicator (Android)
File:Android_orga_status_finished.PNG|MRO Workpackage Confirmed Indicator (Android)
</gallery>

=== Work Progress ===
The work progress is shown on all objects that represent the current work progress or receive the work progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

{{Version/WinXSince|5.0}} {{Version/MobileSince|5.0}} By default, the progress is displayed with maximum one decimal place. For example, 99.75% is displayed as 99.8%. The format string used to achieve this is <code>{0:0.#}%</code>.

If other numeric formats are preferred in your usecases, you can refer to [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings custom numeric format strings] for more information. The template to customize for this is the UBIKMROProgressBadge within UBIKThemes.

{{Clear}}

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

<gallery>
File:UI_WinX_MRO_WPConfirmButton.png|MRO Workpackage confirm button (WinX)
File:UI_WinX_MRO_WPRevokeConfirmButton.png|MRO Workpackage revoke confirmation button (WinX)
File:Android_finish_workpackage.PNG|MRO Workpackage confirm button (Android)
File:Android reopen workpackage.PNG|MRO Workpackage revoke confirmation button (Android)
</gallery>

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

On both clients, a Task can be reverted by clicking twice on the Not Applicable button.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====

A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Therefore, clicking the value on the shown task opens an editor to enter the desired value. If no value was entered before, an empty line will be shown. Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken). An additional small value indicator below the main value can report e.g. the previously entered value. The behaviour of this previous value indicator has to be specified separately in the customizing.
{{Clear}}

<gallery widths=497px heights=69px>
File:Measurment Task Empty UWP.png|Measurement Task without a reported value (WinX)
File:Measurment Task Not Empty UWP.png|Measurement Task with a reported value (WinX)
File:Measurment Task Empty Android.jpg|Measurement Task without a reported value (Android)
</gallery>

==== Progress Task ====

[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

There is also an [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] available for progress tasks.{{Version/WinXSince|2.5.4}}
{{Clear}}

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with a reported work progress (WinX)
File:Progress Task Android.jpg|Progress Task with a reported work progress and a previous progress(Android)
</gallery>

==== Check Task ====

A [[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.
{{Clear}}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Unfinished MRO CheckTask (WinX)
File:Check Task android.jpg|Not Applicable MRO CheckTask (Android)
</gallery>

==== Inspection Task ====

[[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).
{{Clear}}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished MRO InspectionTask (WinX)
File:Inspection task android.jpg|Finished MRO InspectionTask (Android)
</gallery>

==== Sequential Task ====
The [[MROCLS_SEQUENTIALTASK|sequential task classification]] allows you to pre-define a sequence in which tasks are to be resolved by users. This means that it is required for one or multiple tasks to be finished in order for other tasks to become "unlocked" and editable. A task can have any number of "predecessors". Predecessors are the tasks that are required to be finished first.

A task can have predecessors that live anywhere else in the object hierarchy. It is not necessary for a task and its predecessors to be part of the same work package, even though this is likely the most common use case.

The state of a sequential task is evaluated both offline and online to get the best possible user experience. The user will see dependent tasks update immediately if their successors were finished, if those tasks are currently visible in the UI. There is 1 case in which the server-side state will override the client-side (offline) evaluation, discussed below.
The state of each sequential task is evaluated the following way:

# If the server-side state says the task is open, we consider this as the truthful state and don't do any other evaluation.
# Check if the task has any predecessors.
# Try to load each predecessor task.
#* If loading of any predecessor fails (the object is not available offline), the task will be locked.
# If all predecessor tasks are finished, the task is open and can be edited. Otherwise, the task is locked.

The customizer setting up the task dependency relations needs to ensure that the dependencies are not cyclical. In this case, it would be impossible for any tasks in the "cycle" to be finished.

'''Example'''

As a demonstration of this feature, see [[Media:Sequential_tasks_winx.mp4|this video]]. The relations between tasks are defined as in [[Media:Task_relations.png|this image]], starting at A1 and A2, which are not dependent on any other tasks. The lines (from left to right) indicate dependencies. This means that B2 has tasks A1 and A2 as its predecessors, for example.

==== Grouped Task {{Version/WinXSince|4.2}}{{Version/XamarinSince|4.2}} ====
Sometimes, not all tasks have to be finished. More specifically, there might be a predefined condition where you only need to finish a certain number of tasks among a group of them. These are known in {{UBIK}} as [[MROCLS_GROUPEDTASK|grouped tasks]].

The idea is, a group of tasks can be defined as siblings to each other and they also share the same server configured threshold. When the number of finished tasks among that group exceeds the threshold, the entire group is considered as no longer necessary. When reflected in the overall status of the task owner(s), these tasks would appear as if they are finished.

{{Hint|Technically speaking, the finished status is completely independent from the not necessary status on a task. A grouped task which is no longer necessary can be both finished or not yet finished. In other words, users don't have to finish a not necessary grouped task, but they still can.}}

{{Hint|The precise status calculation for grouped tasks and their task owners requires the knowledge of all siblings tasks. Imagine 2 out of 3 tasks must be finished but the client only knows 1 in total and the others are only available at the server at that time. This makes it impossible to draw conclusions whether the task(s) should be necessary or not. Under such circumstances, the local status calculation is done as if these are just regular tasks.}}

{{Hint|Like with the other MRO objects, the client always chooses the best available statuses for grouped tasks to present to the users. More specifically, it uses the statuses calculated by the server when the client is not offline and there are no uncommitted local changes on the involved objects. Otherwise, it uses the statuses calculated locally to the best of its knowledge.}}

A task can also be a grouped and a sequential one at the same time. In such a case, the grouped nature of the sibling tasks will affect the way the task sequence completes.

For example, task A1, A2 and A3 are 3 grouped sibling tasks and only 1 of them needs to be finished. At the same time, they are all predecessors of task B. Normally, all predecessors must be finished (and locked) before task B becomes the next one in the sequence and therefore unlocked. In this case, however, as soon as one of the predecessors is finished, all three become unnecessary (and locked) and task B unlocks as a result of that.

==== Supervisor Task {{Version/XamarinSince|4.8}} ====
As the name suggests, supervisor tasks are those that must be finished under supervision. When users want to finish a [[MROCLS_MRO_SUPERVISOR_TASK|supervisor task]], they must hand over their work devices to a supervisor. The latter checks the work status and scans an NFC tag if the work is approved. If the [[MROCLS_MRO_SUPERVISOR|supervisor]] has sufficient permissions for the task and the correct supervisor PIN is given, the task gets unlocked and the users can proceed to finish it.

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Task Before Verification/Unlocking (Mobile)
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor Task Enter PIN (Mobile)
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Task After Verification/Unlocking (Mobile)
</gallery>

A thing to note is that while the need to verify a supervisor task can be seen as a type of locking, it's certainly not the only reason for a [[Locked_Objects|locked object]]. This means a supervisor task can remain locked (although for different reasons) even after a supervisor has successfully verified it. This can often be the case if you use it in combination with other features such as [[MRO_Objects_(Client)#Sequential_Task|sequential tasks]], [[User_Rights|user rights]].

{{Hint|For security reasons, the verification process is cancelled if the supervisor enters the wrong PIN for three times. Scanning the tag again is required in that case.}}
{{Hint|A setting controls [[RFID_tags#Choose_which_information_to_use_from_a_tag|which information in a scanned tag is used]] during this process.}}

=== MRO objects with project information (WinX only) {{Version/WinXSince|2.5.4}} ===
[[File:UI_WinX_MRO_ProjectInfo.png|thumb|MRO Object with Project Info (WinX)]]
An MRO object (except tasks) might also bring along [[MROCLS_PROJECTINFORMATION|project information]]. In this case, the project information together with the MRO progress are displayed in a bar chart. The start & end dates of the MRO object are displayed on the progress bar. The length and the position of the progress bar, together with the current date mark indicate the timeline.
{{Clear}}

== Locking ==
When an (MRO) object is locked, editing it becomes impossible. More details about [[Locked_Objects|locked objects]].

== See also ==
* [[MRO (Plugin)]]
* [[MROCLS_PROJECT]]
* [[MROCLS_PROJECTINFORMATION]]
* [[MROCLS_SEQUENTIALTASK]]
* [[MROCLS_GROUPEDTASK]]
* [[MROCLS_MRO_CHECK_TASK]]
* [[MROCLS_MRO_INSPECTION_TASK]]
* [[MROCLS_MRO_MEASUREMENT_TASK]]
* [[MROCLS_MRO_PROGRESS_TASK]]
* [[MROCLS_MRO_TASK]]
* [[MROCLS_MRO_TASKOWNER]]
* [[MROCLS_MRO_WORKPACKAGE]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_TASK#Switch Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Android|MRO Objects (UBIK WinX)]]
[[Category:Client|MRO Objects (Client)]]
[[Category:Mobile|MRO Objects (Client)]]
[[Category:Pages with broken file links|MRO Objects (Client)]]
[[Category:WinX|MRO Objects (UBIK WinX)]]

MRO (Plugin)

2026-02-10T08:14:03Z

ARU: /* Technical Status */

The MRO plugin provides a set of {{UBIK}} objects which allow to represent and document maintenance, repair and operations work on the mobile client. An respective implementation of this set of features is available on {{UBIK WinX}}.

== Basic Features ==
Objects classified as MRO objects in general provide a technical and organisational status as well as the overall work progress based on the underlying data branch.

=== Technical Status ===
For detailed information, see [[MRO Objects (Client)#Technical Status|Technical Status]]

[[Category:Module|MRO (Plugin)]]

=== Organisational Status ===
The organisational status indicates the amount of confirmed work done in the data branch. It can include a work package already confirmed or tasks that are already locked by their owning workpackage.

=== Work Progress ===
The work progress is calculated from the current work progress and from the progress cumulated from subsequent objects in the underlying data branch. This indicator shows the amount of work done in the data branch.

== MRO Objects ==
A set of specific objects can be used to provide the required structure for MRO:

=== Task Owner ===
A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object having a substructure of jobs to be done. It can have a tree of other task owners or work packages underneath that will update the status of the task owner. This status consists of technical, organisational and progress information. With a task owner a user can get an overview of all the work to be done in the underlying job structure.

=== Work Package===
A [[MROCLS_MRO_WORKPACKAGE|Work Package]] is a collection of objects to collect and summarize other task owning objects, workpackages, or tasks. A simple workpackage has a certain amount of tasks that have to be finished in order to confirm the workpackage as done. More complex workpackages can also own other underlying workpackages that have to be confirmed. Confirming a workpackage itself requires a progress of 100% of all related tasks, as well as 100% confirmed sub work packages.

=== Task ===
A [[MROCLS_MRO_TASK|Task]] is an object reporting a certain progress to the owning workpackage. There are several specialized types of task objects. All kinds of tasks have a property called '''VALUE''' in common. It is very important, that this property is able to be validated. Therefore, a MetaAttribute (providing a validation timestamp by default) has to be attached on the used MetaProperty.

{{Attention|The MetaProperty ''VALUE'' has to use [[Attributes]] in order to be validated. Otherwise, the calculation of work progress will not be possible.}}

==== Measurement Task ====
A [[MROCLS_MRO_MEASUREMENT_TASK|Measurement Task]] inherits from [[MROCLS_MRO_TASK|Task]] and documents a measured value (e.g. read from a pressure gauge). Once a value has been entered, the task is finished. Alternatively, the task can also be closed by the option ''Not Applicable'' to document the situation of not being able to fullfill the measurement (e.g. the pressure gauge is broken).

==== Progress Task ====
[[MROCLS_MRO_PROGRESS_TASK| Progress Task]] inherits from [[MROCLS_MRO_MEASUREMENT_TASK|Task]] and reports a certain progress while fullfilling a task. The progress will influence the overall progress of the owning workpackage. If the task cannot be fullfilled, it can also be finished with the option ''Not Applicable''.

==== Check Task ====
[[MROCLS_MRO_CHECK_TASK|Check Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished by reporting ''Done'' or ''Not Applicable''. This is intended for a simple To-Do task that is either done or not.

==== Inspection Task ====
A [[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] inherits from [[MROCLS_MRO_TASK|Task]] and is finished, when the user reports with a positive or negative answer or ''Not Applicable'' (e.g. reporting a yes/no answer for existing equipment).

== MRO Implemented Objects ==
A set of specific objects extending functionalities of existing MRO elements.<br />
For Task Objects, Value properties are assigned by default and implement necessary classifications.

=== Procedure Workpackage ===
A [[MROCLS_PROCEDURE|Procedure Workpackage]] is a specialized type of [[MROCLS_MRO_WORKPACKAGE|Work Package]] designed to model complex workflows. It consists of sequential tasks that can include branching logic, modular structures, and references to linked data. Procedure Workpackages allow the execution of structured processes that may adapt dynamically depending on conditions. They support both online and offline execution, with certain steps (e.g. data exchange) triggered once connectivity is available.

=== Switch Start Task ===
A [[MROCLS_SWITCH_START_TASK|Switch Start Task]] is a type of sequential task used within a Procedure Workpackage to define branching logic. It evaluates a predefined (boolean) condition, which can be checked by the client, to determine which branch (true or false) of the workflow will be followed. Each branch represents a different execution path composed of its own set of tasks. A Switch Start Task always requires a corresponding [[MROCLS_SWITCH_END_TASK|Switch End Task]], where all branches converge and the unified procedure continues.

=== Switch End Task ===
A [[MROCLS_SWITCH_END_TASK|Switch End Task]] marks the end of a branching structure initiated by a [[MROCLS_SWITCH_TASK|Switch Task]]. It is a sequential task that connects the different branches back into a single workflow path. Each Switch End Task is directly linked to its respective Switch Task and ensures that, regardless of which branch was taken, the overall procedure continues in a consistent and controlled manner.

=== Check Task ===
A [[MRO_Implemented_Objects|Check Task]] allows the user to check the task as completed or Not Applicable.

=== Numeric Task ===
A [[MRO_Implemented_Objects|Numeric Task]] allows the user to input a numeric value (double). It includes a defined value range, and if the entered value falls outside this range, the task is visually marked as problematic.

=== Inspection Task ===
An [[MRO_Implemented_Objects|Inspection Task]] presents the user with two customizable buttons representing different inspection outcomes, along with a Not Applicable option. The labels of the buttons can be defined during the procedure creation.

=== Text Task ===
A [[MRO_Implemented_Objects|Text Task]] provides a text input field for the user to enter free-form information. This task is useful for capturing qualitative data or comments during the procedure.

=== Picture Task ===
A [[MRO_Implemented_Objects|Picture Task]] enables the user to take and attach one or more photos. It includes a button to initiate the camera and another to confirm the task. The confirmation button remains disabled until at least one picture has been successfully captured.

=== Dynamic List Task ===
A [[MRO_Implemented_Objects|Dynamic List Task]] presents a button that, when clicked, displays a list of selectable options. These options are defined by the procedure creator and can vary depending on the context. This task is ideal for scenarios requiring user selection from a predefined but flexible set of choices.

=== Supervisor Task ===
A [[MRO_Implemented_Objects|Supervisor Task]] includes a button for NFC reading. If a supervisor successfully authenticates, it enables confirmation buttons, input fields, or other interactive elements.

=== Interface Task ===
An [[MRO_Implemented_Objects|Interface Task]] performs a REST API request automatically when it becomes active. It does not include any visible buttons or user interaction. Once the server responds, the task is automatically confirmed based on the response.

=== Calculation Task ===
A [[MRO_Implemented_Objects|Calculation Task]] is used to evaluate a predefined expression and apply its result to a predefined property on its owner. It supports logical or numerical expressions. The result type is defined explicitly to ensure correct handling and validation by the client.

[[Category:Module|MRO (Plugin)]]

=== Signature Task ===
Signature Task prompts the user to provide a written signature to confirm task completion. The task is marked complete once the signature is submitted.

[[Category:Module|MRO (Plugin)]]

== See also ==
* [[MROCLS_MRO_TASKOWNER#Task Owner]] (Classification)
* [[MROCLS_MRO_WORKPACKAGE#Work Package]] (Classification)
* [[MROCLS_MRO_TASK#Task]] (Classification)
* [[MROCLS_MRO_MEASUREMENT_TASK#Measurement Task]] (Classification)
* [[MROCLS_MRO_PROGRESS_TASK# Progress Task]] (Classification)
* [[MROCLS_MRO_CHECK_TASK#Check Task]] (Classification)
* [[MROCLS_MRO_INSPECTION_TASK#Inspection Task]] (Classification)
* [[MROCLS_SEQUENTIALTASK]] (Classification)
* [[MROCLS_GROUPEDTASK]] (Classification)
* [[MROCLS_PROJECT]] (Classification)
* [[MROCLS_PROJECTINFORMATION]] (Classification)
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROCLS_PROCEDURE#Procedure Workpackage]] (Classification)
* [[MROCLS_SWITCH_START_TASK#Switch Start Task]] (Classification)
* [[MROCLS_SWITCH_END_TASK#Switch End Task]] (Classification)
* [[MROCLS_CALCULATION_TASK#Calculation Task]] (Classification)

[[Category:Module|MRO (Plugin)]]

HowTo:Convert Xamarin XAMLs to Maui

2025-12-12T11:50:45Z

ARU: /* UBIKTabView */

== Information ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

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

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}
== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}
== Highly Recommended ==
=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
UBIKTabView has been adapted so that it now supports lazy loading when used in combination with a UBIKContentView or ContentControl. This results in a performance boost because the contents of non-selected tabs are no longer rendered in the UI automatically unless the tab is explicitly selected by the user. Therefore, the LazyLoading property should be set to true for tabs that are not the “default” tabs—i.e., tabs that are not initially selected when a page is opened (Property or Document tabs).

Add the following namespace to use the UBIKTabView:
<syntaxhighlight lang="xml">
xmlns:controls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI"
</syntaxhighlight>

'''From a performance perspective, our UBIKTabView should be used instead of the SfTabView going forward, as it supports lazy loading.'''{{Version/MobileSince|5.1}}

{| class="wikitable" style="width:100%; table-layout:fixed;"
! style="width:60%;" | Xamarin
! style="width:40%;" | MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

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

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
'''There are some other properties that have changed their names on SfListView/SfListViewExt. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

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

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
* <sync:SfListView.LayoutManager>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<sync:SfListView.ItemsLayout>
</syntaxhighlight>
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

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

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

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

== SfTabView ==

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

=== Remove Obsolete Converters ===
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

=== Add StringFormatConverter ===
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

=== FontImageSource Styling ===
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

=== TabView Structure ===
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

=== Property Changes ===
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

=== Rename SfPullToRefresh properties ===
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

=== Avoid multiple SfPullToRefresh controls ===
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

=== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ===
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

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

Mobile XAML

2025-12-12T10:43:25Z

ARU: /* Performance */

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

Please note: 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, we have added a LazyLoading property 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. This can be used in combination with a UBIKTabView, so that only the content of the selected tab is rendered, while the content of non-selected tabs is not. When switching tabs, the content for the newly selected tab is rendered on demand. Lazy loading requires a trigger to determine when the content should be loaded. In the case of a UBIKTabView, this occurs when switching tabs. Alternatively, it can be triggered by, for example, a button with an IsClicked behavior. However, lazy loading always requires a trigger; otherwise, the content would never be loaded.

{| 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.Content>
<controls:ContentControl LazyLoading="True">
<controls:ContentControl.ContentTemplate>
<DataTemplate>
<Grid RowDefinitions="*,Auto">
<Label Text="MyLabel" />
<controls:CheckBox
Grid.Row="1"
IsChecked="True"
IsToggleButton="True" />
</Grid>
</DataTemplate>
</controls:ContentControl.ContentTemplate>
</controls:ContentControl>
</tabView:SfTabItem.Content>
</syntaxhighlight>

⚠️Please note: Although this is possible, care must be taken not to create excessive nesting, as this can ultimately lead to performance degradation if overused. For example, a grid inside a grid, inside another grid, and so on.

|-
|}

'''Another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. For instance, interacting with such a control can trigger lazy loading for a UBIKContentView or ContentControl.

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

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

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

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

= Known issues =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="xml">

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

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

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

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

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

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

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

<syntaxhighlight lang="xml">

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

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

<syntaxhighlight lang="xml">

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

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

<syntaxhighlight lang="xml">

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

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

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

<syntaxhighlight lang="xml">

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

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

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

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

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

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

HowTo:Convert Xamarin XAMLs to Maui

2025-12-12T10:42:43Z

ARU: /* UBIKTabView */

== Information ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

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

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}
== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}
== Highly Recommended ==
=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
We have adapted our UBIKTabView for MAUI so that, when used in combination with a UBIKContentView or ContentControl, it now supports lazy loading. 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.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

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

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
'''There are some other properties that have changed their names on SfListView/SfListViewExt. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

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

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
* <sync:SfListView.LayoutManager>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<sync:SfListView.ItemsLayout>
</syntaxhighlight>
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

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

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

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

== SfTabView ==

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

=== Remove Obsolete Converters ===
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

=== Add StringFormatConverter ===
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

=== FontImageSource Styling ===
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

=== TabView Structure ===
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

=== Property Changes ===
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

=== Rename SfPullToRefresh properties ===
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

=== Avoid multiple SfPullToRefresh controls ===
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

=== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ===
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

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

Mobile XAML

2025-12-12T10:07:43Z

ARU: /* Performance */

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 ===
⚠️Important Note: 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.
<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>

Please note: 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, we have added a LazyLoading property 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. This can be used in combination with a UBIKTabView, so that only the content of the selected tab is rendered, while the content of non-selected tabs is not. When switching tabs, the content for the newly selected tab is rendered on demand. Lazy loading requires a trigger to determine when the content should be loaded. In the case of a UBIKTabView, this occurs when switching tabs. Alternatively, it can be triggered by, for example, a button with an IsClicked behavior. However, lazy loading always requires a trigger; otherwise, the content would never be loaded.

{| 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.Content>
<controls:ContentControl LazyLoading="True">
<controls:ContentControl.ContentTemplate>
<DataTemplate>
<Grid RowDefinitions="*,Auto">
<Label Text="MyLabel" />
<controls:CheckBox
Grid.Row="1"
IsChecked="True"
IsToggleButton="True" />
</Grid>
</DataTemplate>
</controls:ContentControl.ContentTemplate>
</controls:ContentControl>
</tabView:SfTabItem.Content>
</syntaxhighlight>

⚠️Please note: Although this is possible, care must be taken not to create excessive nesting, as this can ultimately lead to performance degradation if overused. For example, a grid inside a grid, inside another grid, and so on.

|-
|}

'''Another control as a trigger for lazy loading'''

Other controls (e.g., Button, CheckBox, etc.) can also serve as triggers for lazy loading. For instance, interacting with such a control can trigger lazy loading for a UBIKContentView or ContentControl.

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

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

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

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

= Known issues =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="xml">

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

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

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

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

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

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

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

<syntaxhighlight lang="xml">

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

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

<syntaxhighlight lang="xml">

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

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

<syntaxhighlight lang="xml">

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

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

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

<syntaxhighlight lang="xml">

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

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

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

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

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

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

HowTo:Convert Xamarin XAMLs to Maui

2025-12-12T09:39:18Z

ARU: /* UBIKTabView */

== Information ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

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

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}
== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}
== Highly Recommended ==
=== CircularImage to AvatarView ===
'''Use AvatarView instead of CircularImage.'''
CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:
<syntaxhighlight lang="xml">
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
</syntaxhighlight>

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame><CircularImage Source="..." /></Frame>
| <toolkit:AvatarView ImageSource="..." BorderWidth="..." BackgroundColor="..." />
|}

=== GlyphSize to FontSize and Alignment ===
'''Use FontSize and alignment properties instead of GlyphSize.'''
The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Setter Property="GlyphSize" Value="13.0" />
| <Setter Property="FontSize" Value="16" /><br/><Setter Property="VerticalOptions" Value="Center" /><br/><Setter Property="HorizontalOptions" Value="Center" /><br/><Setter Property="VerticalTextAlignment" Value="Center" /><br/><Setter Property="HorizontalTextAlignment" Value="Center" />
|}

=== StaticResource to DynamicResource ===
'''Use DynamicResource and BaseResourceKey.'''
For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

{| class="wikitable"
! Xamarin
! MAUI
|-
| BasedOn="{StaticResource SomeStyle}"
| BaseResourceKey="SomeStyle"
|-
| Style="{StaticResource SomeStyle}"
| Style="{DynamicResource SomeStyle}"
|}

=== UBIKPropertyDirectEditListPopup and Guid link direct editing ===
We have changed the way the content item template is defined and used in UBIKPropertyDirectEditListPopup, which is used in the direct editing of Guid link properties. This change aims to simplify the template and is also due to the fact that the old approach has a poor performance in the new MAUI app.

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<DataTemplate x:Key="PopupFilterQueryItemTemplate">
...
</DataTemplate>
</syntaxhighlight>
||
The DataTemplate "PopupFilterQueryItemTemplate" is no longer needed and should be removed.
|-
|
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{StaticResource PopupFilterQueryItemTemplate}" />
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:SfListViewExt
x:Name="FilterQueryResultList"
...
ItemTemplate="{Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}">
<controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding SetPropertyValueCommand}" Converter="{StaticResource ItemTappedEventArgsToViewModelConverter}" />
<behaviors:InvokeCommandAction Command="{Binding ConfirmEditCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors>
</controls:SfListViewExt>
</syntaxhighlight>
|}
In comparison, the old solution defines a "PopupFilterQueryItemTemplate" DataTemplate which simply wraps the needed selection related behaviors to the existing "UBIKChildItem" template. The new solution reuses the "UBIKChildItem" template directly and add the same but adapted behaviors to the list view instead.

=== UBIKTabView ===
We have adapted our UBIKTabView for MAUI so that, when used in combination with a UBIKContentView or ContentControl, it now supports lazy loading. 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..'''

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

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

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
'''There are some other properties that have changed their names on SfListView/SfListViewExt. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

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

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
* <sync:SfListView.LayoutManager>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<sync:SfListView.ItemsLayout>
</syntaxhighlight>
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

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

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

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

== SfTabView ==

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

=== Remove Obsolete Converters ===
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

=== Add StringFormatConverter ===
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

=== FontImageSource Styling ===
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

=== TabView Structure ===
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

=== Property Changes ===
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

=== Rename SfPullToRefresh properties ===
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

=== Avoid multiple SfPullToRefresh controls ===
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

=== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ===
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

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

HowTo:Convert Xamarin XAMLs to Maui

2025-12-12T07:05:06Z

ARU: /* Highly Recommended */

== Information ==
=== Frame to Border ===
'''Use [https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/border?view=net-maui-9.0 Border] instead of Frame.'''
Frame is deprecated in MAUI. Attributes;
* Stroke (previously BorderColor)
* Use StrokeShape (previously CornerRadius) to define the corners. Eg. <nowiki>StrokeShape="RoundRectangle 8,8,8,8"</nowiki> where the corner curve can be written as 1 value (all the same), 2 values (horizontal and vertical), or 4 values (each corner defined seperately). The default StrokeShape is 'Rectangle', which effectively equals a CornerRadius of 0.
* StrokeThickness can be used to define the thickness of the border.
* Other properties documented in the link above can be used to define the look of the border.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <Frame ... />
| <Border ... />
|}

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

=== LayoutOptions with "...AndExpand" ===
'''Replace "...AndExpand" with Grid layout.'''
Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

=== GlyphLabel and Styles ===
'''Use Label with new styles.'''
Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

{| class="wikitable"
! Xamarin
! MAUI
|-
| controls:GlyphLabel
| Label with UBIKSymbolText style
|}

=== SfTabView Virtualization ===
'''Enable virtualization.'''
Add `EnableVirtualization="True"` to all SfTabView instances or styles.

=== Swipe Menu Icons on Android ===
'''Refactor swipe templates and label styles.'''
Icons in swipe menus were truncated on Android. Fixed via refactoring.

=== Color Style Changes ===
'''Dark theme adjustments.'''
Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

=== Strikethrough Converter ===
'''Use `TextDecorations="Strikethrough"` instead of converter.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| Text="{Binding ..., Converter={StaticResource StrikethroughConverter}}"
| Text="{Binding ...}" TextDecorations="Strikethrough"
|}

=== Button Disabled Trigger ===
'''Add trigger for disabled buttons.'''
Maui buttons don’t visually change when disabled. Add trigger to style.

=== TapGestureRecognizer Replacement ===
'''Use TappedBehavior instead.'''
TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <... .GestureRecognizers><TapGestureRecognizer Command="{Binding ...}" /></... .GestureRecognizers>
| <... .Behaviors><behaviors:TappedBehavior><behaviors:InvokeCommandAction Command="{Binding ...}" /></behaviors:TappedBehavior></... .Behaviors>
|}

=== TapGestureRecognizer and Swipe Conflict ===
'''Remove TapGestureRecognizer from root Grid.'''
TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation. An example of such behaviors can be seen in UBIKChildArea.

=== Navigation in UBIKChildItem ===
'''Use EventHandlerBehavior for navigation.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| [none]
| <controls:SfListViewExt.Behaviors><behaviors:EventHandlerBehavior EventName="ItemTapped"><behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" /></behaviors:EventHandlerBehavior></controls:SfListViewExt.Behaviors>
|}
== Recommended ==
=== Extract DataTemplates from UBIKThemes ===
'''Create separate .xamlx files for the following DataTemplates.'''
It's not so easy about the namespaces:
* In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;
* xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
* xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
* xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
* xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
* xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".
* But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.
{| class="wikitable"
!   !! Templates !!  
|-
| UBIKMainItem || UBIKChildItem || UBIKTaskItem
|-
| UBIKTaskProperty || UBIKTaskPropertyString || UBIKTaskPropertyDouble
|-
| UBIKTaskPropertyInt || UBIKTaskPropertyNumeric || UBIKTaskPropertyDateTime
|-
| UBIKTaskPropertyGeoData || UBIKTaskPropertyBool || UBIKTaskPropertyPopup
|-
| UBIKTaskPropertyList || UBIKTaskPropertyGuid || UBIKPropertyItem
|-
| UBIKPropertyTextLengthHint || UBIKPropertyDirectEditButtons || UBIKTaskPropertyEditButtons
|-
| UBIKPropertyDirectItemString || UBIKPropertyDirectItemDouble || UBIKPropertyDirectItemInt
|-
| UBIKPropertyDirectItemMinMax || UBIKPropertyDirectItemNumeric || UBIKPropertyDirectItemDateTime
|-
| UBIKPropertyDirectItemGeoData || UBIKPropertyDirectItemBool || UBIKPropertyDirectItemPopup
|-
| UBIKPropertyDirectItemList || UBIKPropertyDirectItemGuid || UBIKDocumentItem
|-
| UBIKSearchResultItem || UBIKDefaultHotSpot || UBIKAngularLinkHotSpot
|-
| UBIKRoundLinkHotSpot || UBIKInputHotSpot || UBIKSignatureHotSpot
|-
| UBIKObjectHotSpot || UBIKMediaHotSpot ||
|}
=== VideoPlayer Adjustments ===
'''This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the
Aspect property'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">VideoPlayer...</syntaxhighlight>
| <syntaxhighlight lang="xml">VideoPlayer Aspect="AspectFit"</syntaxhighlight>
|}

'''The UriToVideoSourceConverter is no longer needed because the conversion of the
VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI, Converter={StaticResource UriToVideoSource}}"/></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... Source="{Binding DocumentViewModel.LocalURI}"/></syntaxhighlight>
|}

'''The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer
by itself.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><controls:VideoPlayer... StopTimer="{Binding Unloaded}" /></syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:VideoPlayer... /></syntaxhighlight>
|}
=== SearchBar Style Fix on iOS ===
'''On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">[issue on iOS only] UBIKThemes: SearchBar style: <Setter Property="BackgroundColor" Value="Transparent" /></syntaxhighlight>
| <syntaxhighlight lang="xml">Delete this setter</syntaxhighlight>
|}

=== Remove TapGestureRecognizer from Main Item ===
'''Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKMainItem)
<Grid.GestureRecognizers>
<TapGestureRecognizer Command="{Binding NavigateToChildrenCommand}" />
</Grid.GestureRecognizers></syntaxhighlight>
| <syntaxhighlight lang="xml">[nothing]</syntaxhighlight>
|}
=== Add Navigation Behavior in Child Area ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">(In UBIKChildArea)
[nothing]</syntaxhighlight>
| <syntaxhighlight lang="xml"><controls:SfListViewExt.Behaviors>
<behaviors:EventHandlerBehavior EventName="ItemTapped">
<behaviors:InvokeCommandAction Command="{Binding AppStatus.RootList.Items[0].NavigateToChildrenCommand}" />
</behaviors:EventHandlerBehavior>
</controls:SfListViewExt.Behaviors></syntaxhighlight>
|}
== Highly Recommended ==
=== 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 ===
We have adapted our UBIKTabView for MAUI so that, when used in combination with a UBIKContentView or ContentControl, it now supports lazy loading. 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>

{| class="wikitable"
! Xamarin
! MAUI
|-
|
<syntaxhighlight lang="xml">
<tabView:SfTabView>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKPropertyArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<ContentView Content="{Binding [UBIKDocumentArea], Source={x:Static services:TemplateService.Instance}}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</syntaxhighlight>
||
<syntaxhighlight lang="xml">
<controls:UBIKTabView
x:Name="ContentTabs"
Style="{DynamicResource TabViewBaseStyle}"
TabHeaderPadding="0">
<controls:UBIKTabView.Items>
<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer"
Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKPropertyArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>

<tabView:SfTabItem>
<tabView:SfTabItem.Content>
<controls:UBIKContentView
Converter="{StaticResource TemplateConverter}"
ConverterParameter="UBIKDocumentArea"
LazyLoading="True" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</controls:UBIKTabView.Items>
</controls:UBIKTabView>
</syntaxhighlight>
|-
|}

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

== Mandatory ==

=== Namespace conversion ===
'''Update all namespaces to MAUI equivalents.'''
All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

{| class="wikitable"
! Xamarin
! MAUI
|-
| xmlns="http://xamarin.com/schemas/2014/forms"
| xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|-
| clr-namespace:Xamarin.Forms.PlatformConfiguration.AndroidSpecific;assembly=Xamarin.Forms.Core
| clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;assembly=Microsoft.Maui.Controls
|-
| clr-namespace:UBIK.CPL.Behaviors;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Behaviors;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Classes;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Classes;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Converters;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Platform.Renderers;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Platform.Controls;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Services;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.CPL.Resources;assembly=UBIK.CPL
| clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI
|-
| clr-namespace:UBIK.Scanning.Forms;assembly=UBIK.Scanning.Forms
| clr-namespace:UBIK.MAUI.Controls.ZXingScanner;assembly=UBIK.MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.Xforms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|-
| clr-namespace:Syncfusion.ListView.XForms;assembly=Syncfusion.SfListView.XForms
| clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView
|-
| clr-namespace:Syncfusion.XForms.TreeView;assembly=Syncfusion.SfTreeView.XForms
| clr-namespace:Syncfusion.Maui.TreeView;assembly=Syncfusion.Maui.TreeView
|-
| clr-namespace:Syncfusion.XForms.TextInputLayout;assembly=Syncfusion.Core.XForms
| clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core
|-
| clr-namespace:Syncfusion.SfChart.XForms;assembly=Syncfusion.SfChart.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.Charts;assembly=Syncfusion.Maui.Toolkit
|}

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

=== Syncfusion control updates ===
'''There are some other properties that have changed their names on SfListView/SfListViewExt. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
SfListViewExt:
* ItemHolding
</syntaxhighlight>
| ItemLongPress
|}

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

=== Layout name change ===
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
* <sync:SfListView.LayoutManager>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<sync:SfListView.ItemsLayout>
</syntaxhighlight>
|}

=== TemplateService binding for extracted templates ===
'''1. We need to add the following namespace where the changes are applied:
xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
2. We need to search for both "StaticResource" and "DynamicResource";
3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| {StaticResource UBIKChildItem}
| {Binding [UBIKChildItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKDocumentItem}
| {Binding [UBIKDocumentItem], Source={x:Static services:TemplateService.Instance}}
|-
| {StaticResource UBIKMainItem}
| {Binding [UBIKMainItem], Source={x:Static services:TemplateService.Instance}}
|}

=== OnPlatform and OnIdiom syntax changes ===
'''All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax has changed.'''

{| class="wikitable"
! Xamarin
! MAUI
! style="width:7%" | Notes
|-
| OnPlatform
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnPlatform Android=False, iOS=True}" />

<TheControl
...
TheProperty="{OnPlatform Android={Binding ...}, iOS={Binding ...}}" />
</syntaxhighlight>
| rowspan="2" | It is recommended to use the inline syntax as a default wherever possible, but there are also other approaches.
When using Bindings, Resources, or other complex values in OnIdiom or OnPlatform values, it should '''only''' be used with the inline syntax.
|-
| OnIdiom
| <syntaxhighlight lang="xml">
<TheControl
...
TheProperty="{OnIdiom Phone=False, Desktop=True}" />

<TheControl
...
TheProperty="{OnIdiom Desktop={Binding ...}, Phone={Binding ...}}" />
</syntaxhighlight>
|-
| <syntaxhighlight lang="xml">
e.g.
<ColumnDefinition.Width>
<OnIdiom
...
Desktop="Auto"
Phone="*" />
</ColumnDefinition.Width>
or
<RowDefinition.Height>
<OnPlatform
...
Android="Auto"
iOS="*" />
</RowDefinition.Height>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ColumnDefinition Width="{OnIdiom Desktop='Auto', Phone='*'}" />

<RowDefinition Height="{OnPlatform Android='Auto', iOS='*'}" />
</syntaxhighlight>
| When using GridLength as a type (e.g,. in ColumnDefinition.Width or RowDefinition.Height) in OnIdiom or OnPlatform, it should '''only''' be used with the inline syntax.
|-
| WinPhone
| WinUI
| In the scope of any OnPlatform/On Platform, WinPhone needs to be replaced with WinUI.
|}

⚠️ Please refer to the wiki for more details and possibilities (e.g., if the value contains multiple elements): [https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom Platform and Device-specific UI with OnPlatform and OnIdiom].

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

=== Remove default ControlTemplate ===
'''The default ControlTemplate should be removed from the ContentView if the ControlTemplate property of that ContentView is determined by DataTriggers. The same applies to ContentControls. The default ContentTemplate should be removed from the controls:ContentControl if the ContentTemplate property of that ContentControl is determined by DataTriggers.'''
Using only DataTriggers without a default ControlTemplate ensures that content is created only after the trigger evaluation is complete. If a default ControlTemplate is set, it is always loaded immediately, even if another template is applied right after.
For more details refer to [[Xamarin_XAML#Conflicting_Triggers|Conflicting Triggers]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName" ControlTemplate="{StaticResource YourTemplate}">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView x:Name="containerName">
<ContentView.Triggers>
<DataTrigger
Binding="{Binding Source={x:Reference containerName}, Path=...}"
TargetType="ContentView"
Value="true">
<Setter Property="ControlTemplate"
Value="{StaticResource YourTemplate}" />
</DataTrigger>
...
</ContentView.Triggers>
</ContentView>
</syntaxhighlight>
|}

=== Remove HeadlessLayout style ===
'''This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<Style x:Key="HeadlessLayout" TargetType="Layout">
<Setter Property="CompressedLayout.IsHeadless" Value="{OnPlatform False, Android=True}" />
</Style>
</syntaxhighlight>
| Delete it from your custom UBIKThemes file
|}

=== Additional mandatory rule ===
'''In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
Style="{DynamicResource HeadlessLayout}"
VerticalOptions="Start" />
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<ContentView
Grid.Column="2"
ControlTemplate="{DynamicResource ChildCountBadge}"
HorizontalOptions="Start"
VerticalOptions="Start" />
</syntaxhighlight>
|}

=== Rename progress colors ===
'''Renamed in Maui.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| ProgressBackgroundColor, ProgressStrokeColor
| ProgressBackground, ProgressColor
|}

=== Rename Default Font Name ===
'''The name of the default font was slightly renamed in the UBIKThemes file in MAUI — the first letter now needs to be capitalized. Otherwise, on iOS, bold or italic styles are not applied correctly, and changing a property in Direct Editing, for example, would result in no visible change.'''
{| class="wikitable"
! Xamarin
! MAUI
|-
| <x:String x:Key="TextFontFamily">inter</x:String>
| <x:String x:Key="TextFontFamily">Inter</x:String>
|}

=== Chart control updates ===
'''The Title, Legend, and Zoom & Pan behavior syntax of the Chart control have changed. Further, some SyncFusion Chart components & Properties have changed.'''
<br>⚠️ For more information and examples about changed SyncFusion Chart components & Properties, please refer to the [https://help.syncfusion.com/maui/cartesian-charts/overview Syncfusion Maui Charts documentation]. For more info on how to customize a chart, refer to [[Charts#Mobile_Chart_Customizing|Mobile Chart Customizing]].
{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<chart:SfChart.Title>
<chart:ChartTitle Text="{Binding Header}" />
</chart:SfChart.Title>
<chart:SfChart.Legend>
<chart:ChartLegend />
</chart:SfChart.Legend>
<chart:SfChart.ChartBehaviors>
<chart:ChartZoomPanBehavior />
</chart:SfChart.ChartBehaviors>

<chart:NumericalStripLine
Width="2"
StrokeColor="{Binding Color, Converter={StaticResource IntToColor}}"
IsPixelWidth="True"
StrokeWidth="5"
Start="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Color="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue">
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfChartExt.Title>
<Label Text="{Binding Header}" HorizontalOptions="Center" />
</controls:SfChartExt.Title>
<controls:SfChartExt.Legend>
<chart:ChartLegend />
</controls:SfChartExt.Legend>
<controls:SfChartExt.ZoomPanBehavior>
<chart:ChartZoomPanBehavior />
</controls:SfChartExt.ZoomPanBehavior>

<chart:NumericalPlotBand
StrokeWidth="2"
Stroke="{Binding Color, Converter={StaticResource IntToColor}}"
Start="{Binding Value}"
End="{Binding Value}" />

<chart:FastLineSeries
ItemsSource="{Binding Items}"
Label="{Binding Name}"
Fill="{Binding Color, Converter={StaticResource IntToColor}}"
XBindingPath="XValue"
YBindingPath="YValue"
StrokeWidth="2"
EnableAntiAliasing="True" />
</syntaxhighlight>
|}

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

== SfTabView ==

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.XForms.TabView;assembly=Syncfusion.SfTabView.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.TabView;assembly=Syncfusion.Maui.Toolkit
|}

=== Remove Obsolete Converters ===
'''Remove ItemCountToBoolConverter from Resources.'''
This converter is no longer usable in TabView headers.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml"><converters:ItemCountToBoolConverter x:Key="ItemCountToBool" /></syntaxhighlight>
| [remove]
|}

=== Add StringFormatConverter ===
'''Use StringFormatConverter for combined header strings.'''
Syncfusion MAUI TabView uses a single `Header` property instead of templates.
For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [template-based header]
| <syntaxhighlight lang="xml"><converters:StringFormatConverter x:Key="ChildrenTabFormatter" Parameter1="{resources:Translate ChildrenTitle}" /></syntaxhighlight>
|}

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value.
⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

=== FontImageSource Styling ===
'''Add local style for FontImageSource.'''
Global styles are not supported.

{| class="wikitable"
! Xamarin
! MAUI
|-
| [global FontImageSource style]
| <syntaxhighlight lang="xml">
<Style TargetType="FontImageSource">
<Setter Property="FontFamily" Value="{DynamicResource UBIKSymbols}" />
<Setter Property="Color" Value="{DynamicResource UBIKLightThemeColor}" />
</Style>
</syntaxhighlight>
|}

=== TabView Structure ===
'''Use Grid to wrap TabView.'''
MAUI TabView requires a different structure and property set.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<tabView:SfTabView VisibleHeaderCount="3">
...
</tabView:SfTabView>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<tabView:SfTabView>
<tabView:SfTabItem Header="string example header">
<tabView:SfTabItem.ImageSource>
<FontImageSource Glyph="{x:Static resources:UBIKIcons.XXX}" />
</tabView:SfTabItem.ImageSource>
<tabView:SfTabItem.Content>
<controls:UBIKContentView x:Name="ChildContainer" Converter="{StaticResource ChildAreaTemplateConverter}" />
</tabView:SfTabItem.Content>
</tabView:SfTabItem>
</tabView:SfTabView>
</Grid>
</syntaxhighlight>
|}

=== Property Changes ===
'''Update renamed or removed properties.'''

{| class="wikitable"
! Xamarin
! MAUI
|-
| VisibleHeaderCount
| [not available yet]
|-
| UBIKCenterButtonSettings
| CenterButtonSettings
|-
| SelectionIndicatorSettings
| IndicatorPlacement, IndicatorStrokeThickness, IndicatorBackground
|-
| SelectionColor
| Use VisualStateManager instead
|}

⚠️ Refer to [https://help.syncfusion.com/maui/tabview/migration Syncfusion migration guide] for full property list.

== SfPullToRefresh ==

'''It is recommended to get rid of all SfPullToRefresh controls due to some issues that might occur.''' For more information refer to [[Mobile_XAML#Issues_with_SfPullToRefresh_in_MAUI|this article]]. In our Maui standard client, the PullToRefresh control has already been replaced by a Refresh button in the Context Menu, so there's no need for a custom Refresh button.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<controls:SfListViewExt
.../>
</syntaxhighlight>
|}
<br>

⚠️ '''If SfPullToRefresh is still required, the following points should be considered.'''

=== Namespace Update ===
'''Update Syncfusion TabView namespace.'''
Replace the Xamarin namespace with the MAUI equivalent.

{| class="wikitable"
! Xamarin
! MAUI
|-
| clr-namespace:Syncfusion.SfPullToRefresh.XForms;assembly=Syncfusion.SfPullToRefresh.XForms
| clr-namespace:Syncfusion.Maui.Toolkit.PullToRefresh;assembly=Syncfusion.Maui.Toolkit
|}

=== Rename SfPullToRefresh properties ===
'''Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings.'''
SfPullToRefresh:
{| class="wikitable"
! Xamarin
! MAUI
|-
| RefreshContentHeight, RefreshContentWidth
| RefreshViewHeight, RefreshViewWidth
|}

=== Avoid multiple SfPullToRefresh controls ===
'''To prevent an issue that causes the app to freeze, avoid placing more than one SfPullToRefresh controls as siblings in a xaml hierarchy'''. If switching between contents in a SfPullToRefresh control is necessary use separate DataTemplates for the contents and use e.g. a DataTrigger to set one of them as the ControlTemplate of a ContentControl inside the SfPullToRefresh control.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB, Converter={StaticResource BoolToNotBool}}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentA"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>

<pullToRefresh:SfPullToRefresh IsVisible = {Binding ShowContentB}>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
x:Name="ContentB"
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="TemplateA">
<controls:SfListViewExt
x:Name="ContentA"
.../>
</DataTemplate>
<DataTemplate x:Key="TemplateB">
<controls:SfListViewExt
x:Name="ContentB"
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl>
<controls:ContentControl.Triggers>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="false">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateA}" />
</DataTrigger>
<DataTrigger
Binding="{Binding ShowContentB}}"
TargetType="controls:ContentControl"
Value="true">
<Setter Property="ContentTemplate" Value="{DynamicResource TemplateB}" />
</DataTrigger>
</controls:ContentControl.Triggers>
</controls:ContentControl>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

=== Avoid using SyncFusion ListViews directly in SfPullToRefresh controls ===
'''To prevent an issue on some Android devices that can cause some items in a SfListViewExt to be rendered incorrectly or not at all after triggering a PullToRefresh, avoid placing a SfListViewExt directly in a SfPullToRefresh control'''.
Instead, wrap the ListView in a DataTemplate and use it in a ContentControl as a child of the SfPullToRefresh control, as shown in the Xaml example below.

{| class="wikitable"
! Xamarin
! MAUI
|-
| <syntaxhighlight lang="xml">
<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:SfListViewExt
.../>
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</syntaxhighlight>
| <syntaxhighlight lang="xml">
<Grid>
<Grid.Resources>
<ResourceDictionary>
<DataTemplate x:Key="ListViewTemplate">
<controls:SfListViewExt
.../>
</DataTemplate>
</ResourceDictionary>
</Grid.Resources>

<pullToRefresh:SfPullToRefresh>
<pullToRefresh:SfPullToRefresh.PullableContent>
<controls:ContentControl ContentTemplate="{DynamicResource ListViewTemplate}" />
</pullToRefresh:SfPullToRefresh.PullableContent>
</pullToRefresh:SfPullToRefresh>
</Grid>
</syntaxhighlight>
|}

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

XAML Best practices

2025-12-04T10:36:43Z

ARU:

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

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

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

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

=== Formatting ===

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

==== Best Practices ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Layout Compression ====

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

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

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

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

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

<pre>2025.12.03 13:39:35:4747 | Grid 'UBIKChildITEM_RootGrid' rendered in 28.3865 ms</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Image:XBP_ContentTemplates.png]]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Improving performance on complex List item templates ==

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

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

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

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

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

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

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

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

<br>

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

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

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

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

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

[[File:Binding_logs.png]]

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

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

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

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

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

XAML Best practices

2025-12-03T13:06:59Z

ARU: /* Performance analysis (Mobile only) {{Version/MobileSince|5.0}} */

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

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

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

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

=== Formatting ===

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

==== Best Practices ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Layout Compression ====

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

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

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

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

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

<pre>2025.12.03 13:39:35:4747 | Grid 'UBIKChildITEM_RootGrid' rendered in 28.3865 ms</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Image:XBP_ContentTemplates.png]]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{UnderConstructionEnd}}

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

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

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

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

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

{{UnderConstructionStart}}

== Improving performance on complex List item templates ==

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

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

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

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

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

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

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

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

<br>

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

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

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

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

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

[[File:Binding_logs.png]]

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

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

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

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

{{UnderConstructionEnd}}

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