Data Providers
The RadRichTextBox control allows you to export and import its documents into various document formats - HTML, XAML, RTF, DOCX, PDF. You can export and import the document from and to strings or files. For that purpose you could use the following classes:
PdfFormatProvider(export only)
For more information, check out the Import/Export topic.
However, the format providers cannot be used in XAML and you have to implement a logic that will call their Import() and Export() methods. This is something that you might not want to be concerned with when using RadRichTextBox in a data bound scenarios. For such cases, the DataProvider classes are used. They wrap the FormatProviders' functionality and allow its usage in XAML. Currently, the following DataProvider classes are available:
XamlDataProvider: Use when you want to bind XAML source to RadRichTextBox.
HtmlDataProvider: Use when you want to bind HTML source to RadRichTextBox.
RtfDataProvider: Use when you want to bind RTF source to RadRichTextBox.
DocxDataProvider: Use when you want to bind a docx source to RadRichTextBox.
TxtDataProvider: Use when you want to bind plain text source to RadRichTextBox.
Data providers have to be declared in the visual tree and not the Resource dictionary of a control. You don't have to worry about the place in the visual tree where a provider is, as it does not have a visual representation.
RadRichTextBox's data providers encapsulate the logic of the format providers that come with the control. What they do internally is import/export the document using the respective format provider. By default, the property in your view model will be updated on each document change. As this triggers an export to the document you might notice some delay when typing in the control. You could try customizing this by setting the UpdateSourceTrigger property of the data provider to LostFocus or Explicit.
The DataProviders can be easily used to bind RadRichTextBox to a XAML, HTML, RTF or a plain text string. This is done only in XAML without the usage of any code-behind. Using a two way data binding, you can also keep the string up to date with the changes made to it through the RadRichTextBox. To implement a DataProvider class in your application, you'll have to create an instance and configure it via the following properties:
RichTextBox: Specifies which RadRichTextBox instance this data provider is attached to.
-
Value: Specifies the input/output of the DataProvider in the respective format.
-
String: For XamlDataProvider, HtmlDataProvider, TxtDataProvider, and RtfDataProvider.
Property Data Provider Xaml XamlDataProvider Html HtmlDataProvider Text TxtDataProvider Rtf RtfDataProvider -
IList<byte>orbyte[]: For DocxDataProvider.
Property Data Provider Docx DocxDataProvider -
It is best to declare data providers in the visual tree, as this way the binding will be properly updated when the data context is changed. You don't have to worry about the place in the visual tree where the provider is, as it does not have a visual representation.
Each DataProvider class is located in the same assembly as the corresponding FormatProvider class. For example, the XamlFormatProvider class is in the Telerik.Windows.Documents.FormatProviders.Xaml.dll assembly. Only the TxtDataProvider is located in the Telerik.Windows.Documents assembly. In order to use a data provider, make sure to have referenced the required assembly.
The DataProviders can be accessed via the default Telerik namespace:
Example 1: Define the namespace
xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"
Binding the provider to other UI Elements
In Example 2, two simple UI controls are used - a plain RadRichTextBox and a TextBox, which will display the document as a XAML text. The main functionality is contained in the XamlDataProvider class. It's attached to the RadRichTextBox and its Xaml property is data bound to the TextBox's Text property.
Example 2: Binding the provider to a TextBox
<UserControl x:Class="DataProvidersDemo.MainPage"
xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation">
<Grid x:Name="LayoutRoot"
Background="White">
<Grid.RowDefinitions>
<RowDefinition />
<RowDefinition />
</Grid.RowDefinitions>
<telerik:XamlDataProvider x:Name="xamlDataProvider"
Xaml="{Binding ElementName=textBox, Path=Text, Mode=TwoWay}"
RichTextBox="{Binding ElementName=radRichTextBox}" />
<telerik:RadRichTextBox Margin="2" x:Name="radRichTextBox" />
<TextBox Margin="2" Grid.Row="1" x:Name="textBox" />
</Grid>
</UserControl>
At some point, you may want to start customizing the documents' appearance or modify the document after it has been imported but before it is shown. Data providers facilitate this by exposing a SetupDocument event. It's fired every time the data provider instantiates a new document so you can modify the document. The following code-snippet demonstrates how to do that.
Example 3: Attach to the SetupDocument event
<telerik:XamlDataProvider Name="xamlDataProvider"
Xaml="{Binding ElementName=textBox, Path=Text, Mode=TwoWay}"
RichTextBox="{Binding ElementName=radRichTextBox}"
SetupDocument="XamlDataProvider_SetupDocument"/>
Example 4: Handle the SetupDocument event
private void XamlDataProvider_SetupDocument(object sender, Telerik.Windows.Documents.FormatProviders.SetupDocumentEventArgs e)
{
e.Document.LayoutMode = Telerik.Windows.Documents.Model.DocumentLayoutMode.Paged;
}
Private Sub XamlDataProvider_SetupDocument(sender As Object, e As Telerik.Windows.Documents.FormatProviders.SetupDocumentEventArgs)
e.Document.LayoutMode = Telerik.Windows.Documents.Model.DocumentLayoutMode.Paged
End Sub
In the previous example, the document's LayoutMode property is changed. However, you can apply any number of modifications to the document.
Binding the DataProvider to Dynamic Data
The DataProviders can also be used in DataTemplates to enable DataContext binding.
Example 5 shows using RadRichTextBox in ItemsControl. For each item in the ItemsSource collection an expander is created. The content of the expander is RadRichTextBox control bound to the Body property of the DataContext through HtmlDataProvider.
Example 5: Binding with dynamic data
<ItemsControl>
<ItemsControl.ItemTemplate>
<DataTemplate>
<telerik:RadExpander>
<telerik:RadExpander.Header>
<TextBlock Text="{Binding Name}"/>
</telerik:RadExpander.Header>
<telerik:RadExpander.Content>
<Grid>
<telerik:HtmlDataProvider x:Name="HtmlProvider"
RichTextBox="{Binding ElementName=richTextBox}"
Html="{Binding Body, Mode=TwoWay}" />
<telerik:RadRichTextBox x:Name="richTextBox" Height="150" Width="350"
HorizontalAlignment="Left" BorderBrush="Black" BorderThickness="1" />
</Grid>
</telerik:RadExpander.Content>
</telerik:RadExpander>
</DataTemplate>
</ItemsControl.ItemTemplate>
</ItemsControl>
Here is a sample snapshot:
Settings
The data provider classes expose access to the FormatProvider property that represents the format provider class internally used to import and export content. Through this property you can also change the import/export settings of the respective format provider.
Example 6: Change import settings when using data provider
<telerik:HtmlDataProvider x:Name="HtmlProvider"
RichTextBox="{Binding ElementName=richTextBox}"
Html="{Binding Body, Mode=TwoWay}" >
<telerik:HtmlDataProvider.FormatProvider>
<telerik:HtmlFormatProvider>
<telerik:HtmlFormatProvider.ImportSettings>
<telerik:HtmlImportSettings UseHtmlHeadingStyles="False"/>
</telerik:HtmlFormatProvider.ImportSettings>
</telerik:HtmlFormatProvider>
</telerik:HtmlDataProvider.FormatProvider>
</telerik:HtmlDataProvider>
<telerik:RadRichTextBox x:Name="richTextBox" />
Note that dependency properties in data templates might fall back to their default value unexpectedly according to the information provided on MSDN. This might lead to inability to customize the format provider settings when using a data template. The solution is to use user control in the data template.
Troubleshooting
NullReferenceException on Loading Data Provider
The data providers internally use the corresponding format provider classes, which are automatically loaded by MEF. Sometimes the MEF fails to load a format provider and a NullReferenceException is thrown.
To prevent this error, you will need to load the format provider without using MEF. There are two ways to handle this:
Register the format provider with the DocumentFormatProvidersManager:
Example 7: Using DocumentFormatProvidersManager to manually load format provider
DocumentFormatProvidersManager.RegisterFormatProvider(new HtmlFormatProvider());