Changes
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.
= 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'''.
= List of Available Converters =
| 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.
|}
