Edit this page

Settings

note

RadRichTextEditor uses format providers in order to utilize import from and export to different file formats. You can learn more about the basics of using the format providers over here.

As sometimes the formats may support several ways for presenting one and the same content, some customization options have been provided in order to specify the result which the user expects. This is achieved with the help of import and export settings, which some format providers expose (HtmlFormatProvider, PdfFormatProvider,RtfFormatProvider and DocxFormatProvider). You need to create an instance of the settings and assign it to the property of the provider you will be using. Then, you can set (or retrieve) the properties you need.

HtmlFormatProvider

HtmlFormatProvider makes use of HtmlExportSettings and HtmlImportSettings to control import/export.

HtmlExportSettings provide the following options:

  • Title – allows you to set a Title to the generated HTML file.

  • DocumentExportLevel – you can choose between Document and Fragment. Document is the default value, which includes the HTML declaration, the ,

    , and tags, whereas setting the document export level to Fragment results in exporting the content of the tag only.
  • StylesExportMode – the options here are Inline and Classes, the default one being Classes. Predefined classes is the preferred way for setting styles, yet inline styles may be useful with regard to the consumer of the HTML.

  • StyleRepositoryExportMode – specifies if the styles of the document kept in the StyleRepository of the document should be serialized. The options are ExportStylesAsCssClasses (the default value) and DontExportStyles.

  • ExportFontStylesAsTags - specifies if <i>, <b> and <u> tags should be used instead of setting properties as elements of a style.

  • ExportBoldAsStrong - controls whether elements with font-weight bold are exported as <strong> tag.

  • ExportItalicAsEm - controls whether elements with font weight italic are exported as <em> tag.

  • ExportHeadingsAsTags - specifies if Heading styles are exported as <h1> to <h6> tags.

  • ImageExportMode – the user can choose between several options or even provide his own implementation by choosing the ImageExportingEvent option for the ImageExportMode property and handling the ImageExportingEvent. The UriSource option can be used if you want to export an image by setting its src property to the URL rather than having the raw data in the exported document.

  • PropertiesToIgnore - properties added to this dictionary will not be exported. The full collection of properties that can be excluded is as follows:


HtmlExportSettings htmlExportSettings = new HtmlExportSettings();
htmlExportSettings.PropertiesToIgnore["span"].Add("color");
htmlExportSettings.PropertiesToIgnore["span"].Add("text-decoration");
htmlExportSettings.PropertiesToIgnore["span"].Add("font-weight");
htmlExportSettings.PropertiesToIgnore["span"].Add("font-style");
htmlExportSettings.PropertiesToIgnore["span"].Add("font-family");
htmlExportSettings.PropertiesToIgnore["span"].Add("font-size");
htmlExportSettings.PropertiesToIgnore["span"].Add("dir");

htmlExportSettings.PropertiesToIgnore["p"].Add("margin-top");
htmlExportSettings.PropertiesToIgnore["p"].Add("margin-bottom");
htmlExportSettings.PropertiesToIgnore["p"].Add("margin-left");
htmlExportSettings.PropertiesToIgnore["p"].Add("margin-right");
htmlExportSettings.PropertiesToIgnore["p"].Add("line-height");
htmlExportSettings.PropertiesToIgnore["p"].Add("text-indent");
htmlExportSettings.PropertiesToIgnore["p"].Add("text-align");
htmlExportSettings.PropertiesToIgnore["p"].Add("direction");

htmlExportSettings.PropertiesToIgnore["table"].Add("border-top");
htmlExportSettings.PropertiesToIgnore["table"].Add("border-bottom");
htmlExportSettings.PropertiesToIgnore["table"].Add("border-left");
htmlExportSettings.PropertiesToIgnore["table"].Add("border-right");
htmlExportSettings.PropertiesToIgnore["table"].Add("table-layout");
htmlExportSettings.PropertiesToIgnore["table"].Add("margin-left");
htmlExportSettings.PropertiesToIgnore["table"].Add("border-spacing");

htmlExportSettings.PropertiesToIgnore["td"].Add("border-top");
htmlExportSettings.PropertiesToIgnore["td"].Add("border-bottom");
htmlExportSettings.PropertiesToIgnore["td"].Add("border-left");
htmlExportSettings.PropertiesToIgnore["td"].Add("border-right");
htmlExportSettings.PropertiesToIgnore["td"].Add("padding");
htmlExportSettings.PropertiesToIgnore["td"].Add("vertical-align");

Dim htmlExportSettings As New HtmlExportSettings()
htmlExportSettings.PropertiesToIgnore("span").Add("color")
htmlExportSettings.PropertiesToIgnore("span").Add("text-decoration")
htmlExportSettings.PropertiesToIgnore("span").Add("font-weight")
htmlExportSettings.PropertiesToIgnore("span").Add("font-style")
htmlExportSettings.PropertiesToIgnore("span").Add("font-family")
htmlExportSettings.PropertiesToIgnore("span").Add("font-size")
htmlExportSettings.PropertiesToIgnore("span").Add("dir")
htmlExportSettings.PropertiesToIgnore("p").Add("margin-top")
htmlExportSettings.PropertiesToIgnore("p").Add("margin-bottom")
htmlExportSettings.PropertiesToIgnore("p").Add("margin-left")
htmlExportSettings.PropertiesToIgnore("p").Add("margin-right")
htmlExportSettings.PropertiesToIgnore("p").Add("line-height")
htmlExportSettings.PropertiesToIgnore("p").Add("text-indent")
htmlExportSettings.PropertiesToIgnore("p").Add("text-align")
htmlExportSettings.PropertiesToIgnore("p").Add("direction")
htmlExportSettings.PropertiesToIgnore("table").Add("border-top")
htmlExportSettings.PropertiesToIgnore("table").Add("border-bottom")
htmlExportSettings.PropertiesToIgnore("table").Add("border-left")
htmlExportSettings.PropertiesToIgnore("table").Add("border-right")
htmlExportSettings.PropertiesToIgnore("table").Add("table-layout")
htmlExportSettings.PropertiesToIgnore("table").Add("margin-left")
htmlExportSettings.PropertiesToIgnore("table").Add("border-spacing")
htmlExportSettings.PropertiesToIgnore("td").Add("border-top")
htmlExportSettings.PropertiesToIgnore("td").Add("border-bottom")
htmlExportSettings.PropertiesToIgnore("td").Add("border-left")
htmlExportSettings.PropertiesToIgnore("td").Add("border-right")
htmlExportSettings.PropertiesToIgnore("td").Add("padding")
htmlExportSettings.PropertiesToIgnore("td").Add("vertical-align")

note

In order to achieve best compatibility of the generated HTML with Telerik Reporting , you should apply the following settings:

  • DocumentExportLevel - Fragment;
  • StylesExportMode - Inline;
  • StyleRepositoryExportMode - DontExportStyles;
  • ExportFontStylesAsTags - true. >

Here are some examples for using the settings in code-behind:

public void SetupDefaultHtmlFormatProvider()
{
    //Obtain a reference to the format provider used by the default UI - RadRichTextBoxRibbonUI
    HtmlFormatProvider htmlFormatProvider = DocumentFormatProvidersManager.GetProviderByExtension("html") as HtmlFormatProvider;
    HtmlExportSettings htmlExportSettings = new HtmlExportSettings();
    htmlExportSettings.DocumentExportLevel = DocumentExportLevel.Fragment;
    htmlExportSettings.StylesExportMode = StylesExportMode.Inline;
    htmlExportSettings.StyleRepositoryExportMode = StyleRepositoryExportMode.DontExportStyles;
    htmlExportSettings.ExportFontStylesAsTags = true;

    htmlFormatProvider.ExportSettings = htmlExportSettings;
}

Public Sub SetupDefaultHtmlFormatProvider()
    'Obtain a reference to the format provider used by the default UI - RadRichTextBoxRibbonUI
    Dim htmlFormatProvider As HtmlFormatProvider = TryCast(DocumentFormatProvidersManager.GetProviderByExtension("html"), HtmlFormatProvider)
    Dim htmlExportSettings As New HtmlExportSettings()
    htmlExportSettings.DocumentExportLevel = DocumentExportLevel.Fragment
    htmlExportSettings.StylesExportMode = StylesExportMode.Inline
    htmlExportSettings.StyleRepositoryExportMode = StyleRepositoryExportMode.DontExportStyles
    htmlExportSettings.ExportFontStylesAsTags = True
    htmlFormatProvider.ExportSettings = htmlExportSettings
End Sub

HtmlImportSettings provide the following options:

  • UseDefaultStylesheetForFontProperties – a Boolean property indicating whether the default font properties of RadRichTextEditor or the defaults in the HTML specification should be used for the elements that do not set their FontSize, FontFamily, FontWeight and FontStyle explicitly.

  • LoadImageFromUrl event – this event was introduced at a time when HtmlFormatProvider did not automatically load images from URLs. The feature is currently supported out of the box, but this event can be useful if using virtual directories and files on the server.

PdfFormatProvider

PdfFormatProvider exposes an ExportSettings property of type PdfExportSettings, which can be used in the same way as the export settings of HtmlFormatProvider.

PdfExportSettings include the following options:

  • ContentsCompressionMode – this property allows you to choose if you wish to make use of compression (by setting it to Deflate or Automatic) or not (PdfContentsCompressionMode.None) of the text content of the document.

  • ContentsDeflaterCompressionLevel – an integer between -1 and 9, used to get or set the compression level to be used when deflating the content of the document. Default Compression is -1, No Compression is 0 and Best Compression is 9;

  • ImagesCompressionMode – the user can choose between None, Jpeg (supported only for images, imported as JPEG), Deflate (the deflate algorithm will be applied to compress the images) or Automatic (the best algorithm will be automatically decided upon for you).

  • ImagesDeflaterCompressionLevel – same as ContentsDeflaterCompressionLevel, but applied to the images in the document. This property is respected when an image is compressed with Deflate.

  • DocumentInfo - allows you to add entries to the information dictionary such as title, author, etc.

note

PDF import is currently not supported, so there are no import settings.

note

There are not any Import or ExportSettings for XAML either, as the XAML serialization is loss-less and all elements are imported and exported as they would appear if declared in a XAML page in the application. DocxFormatProvider does not currently provide any settings as the document content is matched as closely as possible to the Word document.

RtfFormatProvider

RtfFormatProvider has ImportSettings, which provide an event - FontSubstituting, which allows you to handle the cases when the Rtf source specifies a Font that is not available to the RichTextEditor.

void Settings_Load(object sender, EventArgs e)
{
    RtfFormatProvider rtfFormatProvider = DocumentFormatProvidersManager.GetProviderByExtension("rtf") as RtfFormatProvider;
    RtfImportSettings rtfImportSettings = new RtfImportSettings();
    rtfImportSettings.FontSubstituting += rtfImportSettings_FontSubstituting;
    rtfFormatProvider.ImportSettings = rtfImportSettings;
}

public void rtfImportSettings_FontSubstituting(object sender, FontSubstitutingEventArgs e) 
{ 
    if (e.OriginalFontName.Equals("Cambria"))
    {
        e.SubstitutionFontFamily = new FontFamily("Calibri");
    }
}

Private Sub Settings_Load(ByVal sender As Object, ByVal e As EventArgs)
    Dim rtfFormatProvider As RtfFormatProvider = TryCast(DocumentFormatProvidersManager.GetProviderByExtension("rtf"), RtfFormatProvider)
    Dim rtfImportSettings As New RtfImportSettings()
    AddHandler rtfImportSettings.FontSubstituting, AddressOf rtfImportSettings_FontSubstituting
    rtfFormatProvider.ImportSettings = rtfImportSettings
End Sub
Public Sub rtfImportSettings_FontSubstituting(ByVal sender As Object, ByVal e As FontSubstitutingEventArgs)
    If e.OriginalFontName.Equals("Cambria") Then
        e.SubstitutionFontFamily = New FontFamily("Calibri")
    End If
End Sub

DocxFormatProvider

DocxFormatProvider exposes ExportSettings, which allow customization in how fields are exported. By default, all fields are exported using their result value in the docx document. If you would like to save the document of the editor as a mail merge template and not include the value of the current item of the MailMergeDataSource, a new instance of DocxExportSettings should be created and assigned to the format provider. The value of the FieldResultMode of these settings must be set to FieldDisplayMode.DisplayName.

Here is an example how you can get a reference to the format provider used by the OpenDocument and the SaveCommand and adjust the export, so that the document is saved as a template:

public void SetupDefaultDocxFormatProvider()
{
    //Obtain a reference to the format provider used by the default UI - RadRichTextBoxRibbonUI
    DocxFormatProvider docxFormatProvider = DocumentFormatProvidersManager.GetProviderByExtension("docx") as DocxFormatProvider;
    DocxExportSettings docxExportSettings = new DocxExportSettings();
    docxExportSettings.FieldResultMode = FieldDisplayMode.DisplayName;
    docxFormatProvider.ExportSettings = docxExportSettings;
}

Public Sub SetupDefaultDocxFormatProvider()
    'Obtain a reference to the format provider used by the default UI - RadRichTextBoxRibbonUI
    Dim docxFormatProvider As DocxFormatProvider = TryCast(DocumentFormatProvidersManager.GetProviderByExtension("docx"), DocxFormatProvider)
    Dim docxExportSettings As New DocxExportSettings()
    docxExportSettings.FieldResultMode = FieldDisplayMode.DisplayName
    docxFormatProvider.ExportSettings = docxExportSettings
End Sub

Was this article helpful? Yes No
Thank you for your feedback!

Give article feedback

Tell us how we can improve this article

close
Dummy