View source for Converters In Xamarin

:''See also: [[XAML#Converters|Converters in UWP/WinX]]''

'''Converters''' are used to prepare application data to format a UI defined by a XAML markup. These converters make it possible to show elements only when specific conditions (like data being available) are met. This allows the creation of a good UI with XAML code only, improving code readability while also decreasing code complexity.

This page explains how to properly use converters for customizing the UBIK Xamarin User Interface. Furthermore, all available converters are listed to provide a good reference.

= Definition =
In Xamarin, before converters can be used, they need to be defined in the page's ''Resources'' tag. Make sure to include the <code>UBIK.CPL.Converters</code> namespace in the namespace definitions!
The following example shows how the <code>NullToBoolConverter</code> can be defined:
<syntaxhighlight lang="xml">
<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea" 
    xmlns="http://xamarin.com/schemas/2014/forms" 
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
    xmlns:converters="clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
            <converters:NullToBoolConverter x:Key="NullToBool" />
        </ResourceDictionary>
    </ContentView.Resources>

    <!-- Cuztomizing -->

</ContentView>
</syntaxhighlight>
The key ''NullToBool'' makes this converter accessible from the customizing in this page.
== Definition With Properties ==
In the following example, which is the same example from above, the '''StringFormatConverter''' will be additionally defined. To add more formatting possibilities, it has two extra properties, which need to be prefilled during initialization. Henceforth, these properties can be prefilled with static values or with static references.
<syntaxhighlight lang="xml">
<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea" 
    xmlns="http://xamarin.com/schemas/2014/forms" 
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
    xmlns:converters="clr-namespace:UBIK.CPL.Converters;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
            <converters:NullToBoolConverter x:Key="NullToBool" />
            <converters:StringFormatConverter x:Key="Formatter" Parameter1="5" Parameter2="{Binding Children.Items.Count}" />
        </ResourceDictionary>
    </ContentView.Resources>

    <!-- Cuztomizing -->

</ContentView>
</syntaxhighlight>
Whereever this converter is used within the file it was defined in, ''Formatter'' will always have its ''Parameter1'' set to ''5'' and its ''Parameter2'' to the number of children of the currently viewed UBIK object. If this behavior is not intended, consider defining another ''StringFormatConverter'' with a '''different Key''' in the same way as shown above.<br/>
See below to find out how to use this converter!
= Usage =
A converter can only be used in conjunction with a <code>{Binding}</code>. The following is an easy example, showing how the ''NullToBool'' converter, defined above, can be used.
<syntaxhighlight lang="xml">
<Label Text="My Text" IsVisible="{Binding MyBindableProperty, Converter={StaticResource NullToBool}}"/>
</syntaxhighlight>
If '''MyBindableProperty''' is ''null'' or an empty string, the converter will return '''true''', making the Label visible!
== Parameter ==
Some converters accept a '''ConverterParameter''', that passes additional information. Closely read the description of the available converters to find out which accept or even require a parameter to work properly. In Ubik, some converters accept a string parameter, consisting of multiple individual parameters separated by <code>|</code>.

An example of this behavior is the '''ContainsToBoolConverter''', which checks if the current value is contained within a collection of values (passed as the ''parameter''):
<syntaxhighlight lang="xml">
<Label Text="My Text" IsVisible="{Binding MyValue, Converter={StaticResource ContainsToBool}, ConverterParameter=1|2|3|4|5|6|7|8|9}"/>
</syntaxhighlight>
The label will only be visible if the ''MyValue'' property (which is expected to parse as an Integer in this example) is one of the values of the parameter.<br/>
Again, to get the converter working, don't forget to define it in the page's resources!

== FallbackValue ==
In some rare cases, a converter might not return anything desired (like ''null'') if some condition doesn't work out as it should (e.g. ''value'' is ''null''). To still be able to get a usable return value, it's possible to define a '''FallbackValue'''.

== Example Usage of StringFormatConverter ==
This converter can take up to two additional parameters during definition. Please see [[#Definition With Properties|Definition With Properties]] for more information!
<syntaxhighlight lang="xml">
<Label Text="{Binding MyValue, Converter={StaticResource Formatter}, ConverterParameter=The Value of my value is \{0\}\, compared to \{1\} and \{2\}!}"/>
</syntaxhighlight>
It's important to note that special characters, like <code><nowiki>{</nowiki></code>, <code><nowiki>}</nowiki></code> and <code><nowiki>,</nowiki></code>, need to be escaped using a <code><nowiki>\</nowiki></code>, else the expression will be wrongly interpreted (and nothing happens)!

The text of the '''ConverterParameter''' will be analyzed, and any occurrance (including duplicates) of <code><nowiki>{0}</nowiki></code>, <code><nowiki>{1}</nowiki></code> and <code><nowiki>{2}</nowiki></code> replaced with the '''binding value''', '''Formatter.Parameter1''' and '''Formatter.Parameter2''' respectively!

Make sure to note, that Xamarin Forms has a native '''[https://docs.microsoft.com/en-us/xamarin/xamarin-forms/app-fundamentals/data-binding/string-formatting StringFormat]''' option as well, that is probably way faster than using a converter for it. Furthermore, it supports formatting options!

= Data Source =
Although technically not a converter, the '''SfDataSourceExt''' control is currently on the way of replacing the '''SfDataSourceConverter''', due to improved performance.
The usage is pretty simple: Similar to the converters, it needs to be defined in the '''Page Resources'''. Then, a '''Key''' and '''Expression''', as well as an '''ItemsSource''' have to be defined. Last, but not least, the the converter can be used within the '''ItemsSource''' property of a Syncfusion '''SfListView'''. See the following example:
<syntaxhighlight lang="xml">
<ContentView x:Class="UBIK.CPL.Resources.UBIKChildArea" 
    xmlns="http://xamarin.com/schemas/2014/forms" 
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
    xmlns:controls="clr-namespace:UBIK.CPL.Controls;assembly=UBIK.CPL">
    <ContentView.Resources>
        <ResourceDictionary>
             <controls:SfDataSourceExt
                x:Key="MyDataSource"
                ItemsSource="{Binding Children.Items}"
                Expression="Item.Content.MetaUID.ToString().ToLower()==&quot;85a50533-3817-4a0b-84cd-615b48b62565&quot; &amp;&amp; Item[&quot;ORGA_STATUS&quot;]!=100" />
        </ResourceDictionary>
    </ContentView.Resources>
    <sync:SfListView
           x:Name="ListView1"
           AllowSwiping="True"
           ItemSize="60"
           ItemTemplate="{StaticResource ChildTemplateSelector}"
           ItemsSource="{Binding DisplayItems, Source={StaticResource MyDataSource}}"
           LeftSwipeTemplate="{StaticResource SwipeLeftTemplateSelector}"
           RightSwipeTemplate="{StaticResource SwipeRightTemplateSelector}"
           SelectionMode="None">
</ContentView>
</syntaxhighlight>
Thanks to the given expression, filtering is applied once the data source is evaluated. It's important to have [https://www.advancedinstaller.com/user-guide/xml-escaped-chars.html XML special characters] correctly escaped, like the example shows.


= List of Available Converters =
The following list contains all currently available converters for UBIK Xamarin customizing. 

'''Two-way''' converters can be used with two-way bindings, e.g. a text-box displaying an editable value. If the value updates in the model, the text-box text changes. If the user edits the value, the value in the model behind also gets updated.
As a clarification, '''Value''' refers to the '''Binding Value''', and '''parameter''' to the '''ConverterParameter'''!

{| class="wikitable sortable" style="width:100%"
|-
! Converter !! 2-Way !! Output Type || Input Type || Parameter Type || Description 
|-
| BooleanConverter || style="text-align: center;" | ✓ || Boolean || Boolean, String || || 
Interprets a '''boolean value''' or a '''String value''' and returns it. If the value cannot be interpreted, ''false'' is returned.
|- 
| BooleanInvertConverter || style="text-align: center;" | ✓ || Boolean || Boolean, String || || 
Interprets a '''boolean value''' or a '''String value''' and converts it into its '''inverted value'''. If the value cannot be interpreted, ''false'' is returned.
|- 
| BooleanToFontAttributeConverter || style="text-align: center;" | ✗ || FontAttribute || Boolean || || 
Converts a '''boolean''' into a '''[https://docs.microsoft.com/en-us/dotnet/api/xamarin.forms.fontattributes?view=xamarin-forms font attribute]''' value. In detail, if the value is ''true'', the parameter is interpreted (''Bold'', ''Italic'', ''None'') and returned. The default returned font-attribute is ''None''.
|- 
| ByteToImageSourceValueConverter || style="text-align: center;" | ✗ || ImageSource || Byte[ ],<br/>Byte Stream || || 
Converts a '''byte stream''' value into an '''image source'''.
|- 
| ChildAreaTemplateConverter || style="text-align: center;" | ✗ || Child<wbr/>Area<wbr/>Template || Content<wbr/>ViewModel || || 
Returns a '''ChildAreaTemplate''' from a '''Content<wbr/>ViewModel''' or ''null'' if the ViewModel cannot be interpreted.
|- 
| ChildItem<wbr/>SelectionMode<wbr/>To<wbr/>SfListView<wbr/>SelectionMode<wbr/>Converter || style="text-align: center;" | ✓ || [https://help.syncfusion.com/cr/cref_files/xamarin/Syncfusion.SfListView.XForms~Syncfusion.ListView.XForms.SfListView~SelectionMode.html ListView<wbr/>SelectionMode] || ChildItem<wbr/>SelectionMode || || 
Converts a '''ChildItem<wbr/>SelectionMode''' to a Syncfusion '''[https://help.syncfusion.com/cr/cref_files/xamarin/Syncfusion.SfListView.XForms~Syncfusion.ListView.XForms.SfListView~SelectionMode.html ListView<wbr/>SelectionMode]'''. Default is "Single".
|- 
| ClassificationToBoolConverter || style="text-align: center;" | ✗ || Boolean || ContentViewModel || || 
Returns a '''boolean''' indicating whether the given '''ContentViewModel''' is successfully classified.
|- 
| ContainsToBoolConverter || style="text-align: center;" | ✗ || Boolean || String,<br/>Guid,<br/>Object || || 
Checks if the delivered value is '''contained''' within a collection of values (delivered in the parameter, seperated with <code><nowiki>|</nowiki></code>). If the value is contained, ''true'' will be returned, else ''false''. The functionality is similar to the ''ContainsToVisibilityConverter'' in the WinX project.
|- 
| ContainsToInvertedBoolConverter || style="text-align: center;" | ✗ || Boolean || String,<br/>Guid,<br/>Object || || 
Same as the ''ContainsToBoolConverter'', but with '''inverted output'''.
|- 
| ContentAreaTeamplateConverter || style="text-align: center;" | ✗ || UBIKContentArea || ContentViewModel || || This converter is '''not yet finished''' and just returns the ''UBIKContentArea'' if the value is a ''ContentViewModel''.
|- 
| StringToDateTimeTypesConverter || style="text-align: center;" | ✓  || [https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime], [https://docs.microsoft.com/en-us/dotnet/api/system.timespan TimeSpan] || String || || 
Converts a String to the correct DateType, which can be either '''[https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime]''' or '''[https://docs.microsoft.com/en-us/dotnet/api/system.timespan TimeSpan]'''. If the value cannot be interpreted, the unchanged String value is returned.
|- 
| DateTimeOffsetToDateConverter || style="text-align: center;" | ✓ || [https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime] || [https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset DateTimeOffset] || || 
Converts a '''[https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset DateTimeOffset]''' to the correct '''[https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime]''', applied to the current date and time. If the value cannot be interpreted, a new ''DateTime'', generated from the device's current time (<code>DateTime.Now</code>) is returned.
|- 
| DateTimeToFromNowStringConverter || style="text-align: center;" | ✗ || String || [https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime] || || 
Returns a '''[https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime]''' into a human-readable and easily understandable ''string message'' (the last applying one will be taken):
* Less than 5 minutes in the past: ''Just now''
* Less than 10 minutes in the past: ''A few minutes ago''
* Less than 1 hour in the past: ''An hour ago''
* Less than 23 Hours in the past: ''Some hours ago''
* Less than 1 day in the past: ''Yesterday''
* More than 1 day in the past: The ''DateTime'' value formatted according to the device's localization rules.
* Not interpretable: ''???''
|- 
| DebugConverter || style="text-align: center;" | ✓ || Object || Object || || 
A converter returning the given value for '''debug reasons'''.
|- 
| DistanceToStringConverter || style="text-align: center;" | ✗ || String || Double || || 
Returns the given value interpreted as '''length'''. Values are returned in kilometers with two comma digits (e.g. 2.84km), values smaller than 1km are returned as meters and ''NaN'' will be returned as ''infinity''. If the value cannot be interpreted, an empty string will be returned.
|- 
| EqualityToBoolConverter || style="text-align: center;" | ✗ || Boolean || Object,<br/>String || Object,<br/>String || 
Returns ''true'' if the given value and parameter are '''equal to each other''', ''false'' otherwise.
|- 
| EqualityToInvertedBoolConverter || style="text-align: center;" | ✗ || Boolean || Object,<br/>String || Object,<br/>String || 
Returns ''true'' if the given value and parameter are '''not equal to each other''', ''false'' otherwise.
|- 
| SelectionChangedEventArgsConverter || style="text-align: center;" | ✗ || [https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.selectionchangedeventargs List<wbr/>Selection<wbr/>Changed<wbr/>EventArgs] || [https://help.syncfusion.com/cr/cref_files/xamarin/Syncfusion.SfListView.XForms~Syncfusion.ListView.XForms.ItemSelectionChangedEventArgs.html Item<wbr/>Selection<wbr/>Changed<wbr/>EventArgs] || || 
Converts an Syncfusion '''[https://help.syncfusion.com/cr/cref_files/xamarin/Syncfusion.SfListView.XForms~Syncfusion.ListView.XForms.ItemSelectionChangedEventArgs.html Item<wbr/>Selection<wbr/>Changed<wbr/>EventArgs]''' to a '''[https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.selectionchangedeventargs List<wbr/>Selection<wbr/>Changed<wbr/>EventArgs]'''. <br/>The use-case of this converter is highly specific.
|- 
| FilterCriterionToValueConverter || style="text-align: center;" | ✓ || String || FilterCriterion || || 
Converts a [[Property_Based_Content_Filters|'''FilterCriterion''']] to its value. The functionality is similar to UWP's FilterCriterionToValueConverter.
|- 
| GuidPropertyValueConverter || style="text-align: center;" | ✓ || String || Guid || Binding, where source is ContentViewModel || 
Returns the '''first item''' of the parameter's ''Source-ViewModel'' that '''matches the given GUID''' value. If none is found, ''null'' is returned.
|- 
| IntToColorConverter || style="text-align: center;" | ✗ || Color || Integer || || 
Converts an ARGB '''integer''' value to a '''color'''. If the value cannot be interpreted, the converter tries to parse the parameter as a ''color'' to return it. If everything fails, ''transparent'' is returned.
|- 
| ItemCountToBoolConverter || style="text-align: center;" | ✗ || Boolean || Integer || Integer || 
This converter has a '''property''' to set the '''boolean return value''', called ''LesserOrEqualReturnValue''. This property-value will be returned if the given value is '''smaller than or equal to''' the threshold (parameter, defaults to 0). If the value is '''bigger than''' the threshold, the '''inverted''' ''LesserOrEqualReturnValue'' will be returned.<br/>
In any other case (like the value cannot be interpreted), ''false'' is returned, so it's a good idea to set the converter's property in a way that the return is only ''true'' if you need it.
|- 
| ItemCountToOverflowConverter || style="text-align: center;" | ✗ || String || Integer || Integer || Creates a '''human-readable text''' indicating '''how many items are available'''. The value will be interpreted as the '''total item count''' and the parameter as '''overflow threshold''' (defaults to 99). <br/>If there are more items than the overflow, the overflow value with a + sign will be returned (e.g. 99+). If not, the value itself will be returned. If everything fails, ''null'' is returned.
|- 
| NullToBoolConverter || style="text-align: center;" | ✓ || Boolean || Object,<br/>String|| || 
''Null'' or an '''empty string''' value get converted to ''true'', and everything else to ''false''.
|- 
| NullToInvertedBoolConverter || style="text-align: center;" | ✓ || Boolean || Object,<br/>String || || 
''Null'' or an '''empty string''' value get converted to ''false'', and everything else to ''true''.
|- 
| PathToImageSourceValueConverter || style="text-align: center;" | ✗ || Image Source || String || || 
Reads the '''path''' provided as parameter and creates an '''image source''' from it.
|- 
| PercentageToProgressConverter || style="text-align: center;" | ✗ || Double || Integer,<br/>Double || || 
The '''numeric value'''  (int or double), interpreted as '''percentage from 0 to 100''', get converted to a '''progress level'''  (0 to 1). Values outside this range will be contained.
|- 
| PropertyNameExistsToBoolConverter || style="text-align: center;" | ✗ || Boolean (Nullable) || ContentViewModel,<br/>IContent || || 
Converts a property to a '''boolean''' based on its '''existence'''. If it exists, ''true'' will be returned, else ''false'' or ''null'' (if something couldn't be properly interpreted).
|- 
| PropertyNameExistsToInvertedBoolConverter || style="text-align: center;" | ✗ || Boolean (Nullable) || ContentViewModel,<br/>IContent || || 
Converts a property to a '''boolean''' based on its '''existence'''. If it exists, ''false'' will be returned, else ''true'' or ''null'' (if something couldn't be properly interpreted).
|- 
| RootAreaTemplateConverter || style="text-align: center;" | ✗ || ContentView || Object || || 
If the provided value is '''not null''', the '''UBIKRootArea template''' will be returned.
|- 
| SelectiveItemToValueConverter || style="text-align: center;" | ✓ || Boolean,<br/>String,<br/>Integer,<br/>Double,<br/>DateTime,<br/>Guid,<br/>FileReferenceData,<br/>GeoData,<br/>Object || Boolean,<br/>String,<br/>Integer,<br/>Double,<br/>DateTime,<br/>Guid,<br/>FileReferenceData,<br/>GeoData,<br/>Object || Binding, where source is ContentViewModel || 
Converts a '''item''' of a '''selective list''' to its value. If none is found, the passed ''value'' will be returned.
|- 
| SelectiveListToItemsConverter || style="text-align: center;" | ✗ || List of PropertyItems  || IPropertyItem || || 
Returns all items from a selective list.
|- 
| SfDataSourceConverter || style="text-align: center;" | ✗ || DataSource (for ListView) || Double || String (Expression) || 
It's an advanced converter used for '''loading items''' and '''applying filters''' on it. It replaces to ''CollectionToViewConverter'' from the WinX.UWP project. The data source can be directly used with a ''[https://help.syncfusion.com/xamarin/sflistview/overview SfListView]''.<br/><br/>
'''This converter is obsolete!'''<br/>Use '''SfDataSourceExt''' (see [[#Data Source|Data Source]]) instead!
|- 
| StringContainsToBoolConverter || style="text-align: center;" | ✗ || Boolean || String || String || 
Returns a '''boolean''' indicating whether the parameter string is included in the value string.
|- 
| StringContainsToInvertedBoolConverter || style="text-align: center;" | ✗ || Boolean || String || String || 
Same as the ''StringContainsToBoolConverter'' but with '''inverted output'''.
|- 
| StringFormatConverter || style="text-align: center;" | ✗ || String || Object || String || Allows the creation of a '''nicely formatted ''string'' message''', similar to [https://docs.microsoft.com/en-us/dotnet/api/system.string.format C#'s String.Format method].<br/>The value will be interpreted as the <code><nowiki>{0}</nowiki></code> element, and the parameter is the template string (e.g. <code><nowiki>The total count is: {0}!</nowiki></code>. Up to two additional parameters, named ''Parameter1'' and ''Parameter2'', can be defined at the converter declaration. Adding formatting options to the <code><nowiki>{0}</nowiki></code> notation is not possible.<br/><br/>
'''Attention''', using the native '''[https://docs.microsoft.com/en-us/xamarin/xamarin-forms/app-fundamentals/data-binding/string-formatting StringFormat]''' option is not only faster, but it also offers more customizability of the value!<br/>
You might still want to use the ''StringFormatConverter'' in rare cases, though!
|- 
| ToStringFormatConverter || style="text-align: center;" | ✗ || String || Double,<br/>Float,<br/>Integer,<br/>DateTime,<br/>String || String || Converts '''primitives''' or '''[https://docs.microsoft.com/en-us/dotnet/api/system.datetime DateTime]''' to string and allows the application of '''[https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings formatting options]''' (as parameter). <br/>Adding a <code>.</code> to the end of the format-parameter allows '''[https://docs.microsoft.com/en-us/dotnet/api/system.math.truncate truncation]''' of all decimal places.
|-
| ToTypeConverter || style="text-align: center;" | ✗ || Object || Object || String || Attempts to convert value to the Type specified in parameter, returning the value.
|- 
| TypeNameToBoolConverter || style="text-align: center;" | ✗ || Boolean || Object || String || Returns ''true'' if the type name of the value is present in the parameter-string (seperated by <code><nowiki>|</nowiki></code>).
|- 
| TypeNameToInvertedBoolConverter || style="text-align: center;" | ✗ || Boolean || Object || String || Inverted ''TypeNameTo<wbr/>BoolConverter''.
|- 
| DataTemplateItemTemplateSelectorConverter || style="text-align: center;" | ✗ || ChildItem<wbr/>Template<wbr/>Selector || String || String || Chooses what '''ChildItem<wbr/>Template<wbr/>Selector''' to return. Having a parameter with the content "Small" returns the small item template selector.
|- 
| DataTemplateItemsPanelConverter || style="text-align: center;" | ✗ || ItemsPanelTemplate || Query<wbr/>Details<wbr/>Page<wbr/>ViewModel || || Chooses what '''ItemPanel<wbr/>Template''' to return. Having a parameter with the content "Small" returns the small item template selector.
|}

[[Category:Client | XAML | Xamarin]]

[[Category:Client|Converters In Xamarin]]
[[Category:Xamarin|Converters In Xamarin]]