New to Telerik UI for WPF? Download free 30-day trial

Settings

HtmlFormatProvider allows for import of HTML documents and respectively export of RadRichTextBox to HTML. Additionally, the import/export settings provide modification options. The current article outlines the available settings.

Export Settings

HtmlFormatProvider exposes ExportSettings, which allow you to control the export of the RadRichTextBox document.

ExportSettings Properties

  • DocumentExportLevel: A property of type DocumentExportLevel that gets or sets which element tags should be exported.
    • Document: This is the default value. Includes the HTML declaration, more specifically <HTML>, <TITLE>, <HEAD> and <BODY> tags.
    • Fragment: When this setting is applied, only the HTML <BODY> tag will be exported.
  • ExportBoldAsStrong: A property of type bool that controls whether elements with font-weight bold are exported as tag.
  • ExportEmptyDocumentAsEmptyString: A property of type bool that gets or sets whether an empty document should be exported as an empty string. The default value of this property is false.
  • ExportFontStylesAsTags: A property of type bool that gets or sets whether the font styles should be exported as tags. Specifies if <i>, <b> and <u> tags should be used instead of setting properties as elements of a style.
  • ExportHeadingsAsTags: A property of type bool that gets or sets whether Heading styles should be exported as HTML heading tags (<h1>, <h2> etc.).
  • ExportItalicAsEm: A property of type bool that controls whether elements with font weight italic are exported as <em> tag.
  • ExportLocalOrStyleValueSource: A property of type bool. Gets or sets whether only properties which have local or style value source will be exported.
  • ExportStyleMetadata: A property of type bool that sets whether the additional metadata should be exported when exporting CSS classes.
  • ImageExportMode: A property of type ImageExportMode that gets or sets how the image should be exported. This property is an enumeration and it allows the following values:
    • None: Images are not exported.
    • AutomaticInline: The best mode to export the image is chosen automatically.
    • Base64EncodedSplit: Images are inline Base64 encoded and split into parts laid out in a table.
    • Base64Encoded: Images are inline Base64 encoded.
    • ImageExportingEvent: Event is fired on exporting.
    • UriSource: The UriSource property is set as src attribute of the img tag.
  • PropertiesToIgnore: A property of type Dictionary that allows you add properties which will not be exported for certain HTML tags. The full collection of properties that can be excluded is demonstrated in Example 1.
  • SpanExportMode: A property of type SpanExportMode that gets or sets how the spans in the document are exported. This option does not affect the content of the span but only how the span tag is exported. This property is an enumeration and it allows the following values:
    • DefaultBehavior: HTML <span> tags will be exported when they have styling.
    • AlwaysExport: HTML <span> tags will be always exported.
  • StyleRepositoryExportMode: A property of type StyleRepositoryExportMode that gets or sets the style repository export mode. This property is an enumeration and it allows the following values:
    • ExportStylesAsCssClasses: Export styles from the document styles repository to CSS classes.
    • DontExportStyles: Don't export styles from the document styles repository.
  • StylesExportMode: A property of type StylesExportMode that gets or sets the styles export mode. This controls how the properties of the document elements will be exported.
    • Classes: Create CSS classes containing properties of document elements.
    • Inline: Inline properties of document elements using style attribute.
  • Title: A property of type string that allows you to set a Title to the generated HTML file.

Example 1: Exclude properties

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"); 

Microsoft Office does not support HTML that has multiple CSS class selectors applied on a single element. As we are aiming for compliance with the HTML standard, this syntax should be supported in RadDocument. In order to generate HTML that is compliant with MS Office, please use the StylesExportMode.Inline setting of HtmlExportSettings.

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.

ExportSettings Events

  • CssClassExporting: This event is fired on every attempt to export a CSS class. The CssClassExporting event is triggered only when StyleRepositoryExportMode is set to ExportStylesAsCssClasses.
  • FloatingUIContainerExporting: This event is fired on every attempt to export a FloatingUIContainer.
  • ImageExporting: This event is fired only when the respective option of ImageExportMode is applied.
  • InlineUIContainerExporting: This event is fired on every attempt to export an InlineUIContainer. For more information, please refer to the article about InlineUIContainers.

Example 2: Setting the ExportSettings of the HtmlFormatProvider

HtmlExportSettings htmlExportSettings = new HtmlExportSettings(); 
htmlExportSettings.ExportBoldAsStrong = true; 
htmlExportSettings.SpanExportMode = SpanExportMode.AlwaysExport; 
 
HtmlFormatProvider htmlFormatProvider = new HtmlFormatProvider(); 
htmlFormatProvider.ExportSettings = htmlExportSettings; 

Import Settings

The HtmlFormatProvider exposes ImportSettings (of type HtmlImportSettings), which allows you to control the import of the HTML file.

With the 2024 Q2 (2024.3.924) release the HtmlImportSettings class now inherits the XamlImportSettings. This enforces the automatic XML verification needed to handle security risks related to the execution of XML content in the application.

ImportSettings Properties

  • UseDefaultStylesheetForFontProperties: A property of type bool that indicates whether the default font properties of RadRichTextBox or the defaults in the HTML specification should be used for the elements that do not set their FontSize, FontFamily, FontWeight and FontStyle explicitly.
  • UseHtmlHeadingStyles: A property of type bool that indicates whether the heading style of the imported HTML should be imported or not.

ImportSettings Events

  • FloatingUIContainerImporting: This event is fired on every attempt to import a FloatingUIContainer.
  • FloatingUIContainerImported: This event is fired every time when the FloatingUIContainer is imported.
  • FontSubstituting: This event allows you to handle the cases when the HTML source specifies a Font that is not available to the RichTextBox.
  • InlineUIContainerImported: This event is fired every time when the InlineUIContainer is imported.
  • InlineUIContainerImporting: This event is fired on every attempt to import a InlineUIContainer.
  • LoadImageFromUrl: 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.

Example 3: Setting the ImportSettings of the HtmlFormatProvider

HtmlImportSettings htmlImportSettings = new HtmlImportSettings(); 
htmlImportSettings.UseDefaultStylesheetForFontProperties = true;     
 
HtmlFormatProvider htmlFormatProvider = new HtmlFormatProvider(); 
htmlFormatProvider.ImportSettings = htmlImportSettings; 

See Also

In this article