Edit this page
Available for: UI for ASP.NET AJAX | UI for ASP.NET MVC | UI for WPF | UI for WinForms

Settings

HtmlFormatProvider allows you to import HTML documents and to export a RadFlowDocument to HTML. Additionally, the import/export settings provide modification options. This article outlines the available settings.

Import Settings

The import settings are represented by the HtmlImportSettings class. The options that you can specify are as follows:

DefaultStyleSheet

The property specifies the default style sheet that should be used. This is equivalent to the browser's "user agents style defaults" and specifies the formatting that should be applied by default to the elements (before all styles explicitly defined in the document).

The default value, for example, specifies that "b" elements should be imported with "font-weight: bold".

You can set the value of the property to any valid CSS document.

GenericFonts

Contains an instance of GenericHtmlFonts class, which specifies the ThemableFontFamily objects that should be used when importing the 5 generic CSS font families: serif, sans-serif, monospace, cursive and fantasy. By default, these fonts are Times New Roman, Arial, Courier New, Comic Sans MS and Algerian, respectively.

LoadFromUri

The event can be used to override the process of loading of external resources – like external images and external CSS files. When handling the event, you gain access to the LoadFromUriEventArgs instance exposing the following members:

  • Uri: The URI originally specified in the imported HTML file.
  • SetData(): Can be used to set the data (in the form of byte array) that will be loaded.

Example 1 shows how you can create and apply specific import settings.

[C#] Example 1: Create HtmlImportSettings

HtmlFormatProvider provider = new HtmlFormatProvider();
HtmlImportSettings importSettings = new HtmlImportSettings();

importSettings.GenericFonts.Serif = new ThemableFontFamily("Baskerville");

byte[] data = this.GetImageData();
provider.ImportSettings.LoadFromUri += (s, e) =>
{
    if (e.Uri == "test.jpg")
    {
        e.SetData(data);
    }
};

provider.ImportSettings = importSettings;

With Q3 2015 the UriImageSource class has been introduced and it is not necessary to subscribe to the LoadFromUri event when you want to import an image with URI.

UriImageSource Class

When importing HTML, which contains images with URI source, the HtmlFormatProvider will create an UriImageSource object for each of these images. The image data will be downloaded on demand. UriImageSource exposes the following properties:

  • Uri: Gets the URI of the image.
  • Data: Gets a byte[], which represents the data of the image. Accessing this property will download the image data.
  • Extension: Gets the extension. Accessing this property will download the image data only if the extension is not predefined.

Exporting an UriImageSource object to other supported formats will download the image and save it according to the used format specification.

Converting UriImageSource to ImageSource

The UriImageSource objects are always exported as images with URI as their source independently of the export settings. If you need to export this object as an embedded or external image, you could convert the UriImageSource to ImageSource object.

[C#] Example 2: Convert UriImageSource to ImageSource

UriImageSource uriImageSource = imageInline.Image.ImageSource as UriImageSource;
if (uriImageSource != null)
{
    imageInline.Image.ImageSource = new ImageSource(uriImageSource.Data, uriImageSource.Extension);
}

Export Settings

The export settings are represented by the HtmlExportSettings class. The settings that you can specify are as follows:

BordersMinimalThickness

Specifies the minimal exported thickness of the borders of tables and table cells. This could be useful as some browsers cannot properly visualize thin borders (below 1px or similar). The default value is 0, equivalent to exporting all borders with their actual thickness.

DocumentExportLevel

Specifies the export level of the document using the DocumentExportLevel enumeration:

  • Document: Exports full HTML document. This is the default value of the property.
  • Fragment: Exports a fragment of the HTML document – only the 'body' tag.

IndentDocument

Specifies whether the exported document should be indented (formatted with spaces). The default value is false, as this ensures minimum size as opposed to human-readability.

ImagesExportMode

This property is used to control how images are exported. The available options are as external file or as embedded images.

When an image with Uri source is imported, the ImageSource property of the Image contains object of type UriImageSource. Hence, the image is always exported with URI and the ImagesExportMode property is not respected. If you need this property to be respected, you could convert the UriImageSource object to ImageSource.

When working with relative URI, the import/export functionalities only preserve the path to the image and do not modify it.

ImagesFolderPath

This property is used to specify the folder path where external images should be exported. This property is used only when ImageExportMode is set to External.

ImagesSourceBasePath

Specifies the base path for the "src" attribute of the exported image tags. This property is used only when the ImageExportMode is set to External.

ImageExporting

The event is raised for every image in the document. The event argument exposes the following options:

  • Title: Allows you to set the title attribute of the image element.

  • AlternativeText: Can be used to specify the content of the 'alt' attribute of the image. It is null by default and the attribute is not exported.

  • Handled: Marks the event as handled. If ImagesExportMode is set to External and the event is marked as handled, the format provider does not attempt to export the image to an external image file.

  • Image: Can be used to obtain the original Image object, from where you can access image name, image data and image extension.

  • Source: Can be used to specify the value of the 'src' attribute of the 'image' element. If ImagesExportMode is set to External, the source can be set to absolute or to a relative path pointing to the image file.

  • ExportSize: Use this property to specify whether the width and height attributes of an image element should be exported. The default value is true.

StylesExportMode

Specifies the export mode for the styles in RadFlowdDocument's StyleRepository, using the StylesExportMode enumeration:

  • Embedded: RadFlowDocument styles are exported as internal CSS – selectors embedded into the HTML in 'style' element in the 'head' section. This is the default value of the property.

  • External: RadFlowDocument styles are exported as CSS selectors in external CSS file. You have two options:

  • Set StylesFilePath and StylesSourcePath properties, which should be used to export the external file.

  • Handle ExportStylesToExternalSource event, specifying the output stream and reference Uri to be exported.

  • Inline: RadFlowDocument styles are exported as CSS properties in the 'style' attribute of the HTML elements. This ensures maximum compatibility with some applications that don't support external or embedded CSS, for example some email clients.

  • None: RadFlowDocument styles are not exported. Note that the local values of style properties of the DocumentElements are still exported as CSS properties in the 'style' attribute of the HTML elements.

StylesFilePath

This property is used to specify the file path where the external styles should be exported.

StylesSourcePath

The property specifies the base path for the "href" attribute of the "link" element pointing to the file containing the external styles.

ExternalStylesExporting

The event is only raised when the StylesExportMode property is set to External. The event argument exposes the following properties:

  • Css: String containing the actual CSS that will be exported.

  • Handled: Marks the event as handled. If the event is marked as handled, the format provider does not attempt to export the CSS file.

  • Reference: The value that will be set to the "href" attribute of the "link" element tag. In general, this should be set to the absolute or relative path pointing to the file containing the CSS styles.

Example 3 demonstrates how you can create export settings.

[C#] Example 3: Create HtmlExportSettings

HtmlFormatProvider provider = new HtmlFormatProvider();
HtmlExportSettings exportSettings = new HtmlExportSettings();

byte[] data = null;
exportSettings.BordersMinimalThickness = 1;
exportSettings.DocumentExportLevel = DocumentExportLevel.Fragment;
exportSettings.IndentDocument = true;
exportSettings.ImageExporting += (s, e) =>
{
    e.Source = "test.jpg";
    data = e.Image.ImageSource.Data;
    e.Handled = true;
    e.Title = "Test image";
    e.ExportSize = true;
    e.AlternativeText = "You will see this text if the image is not loaded";
};

provider.ExportSettings = exportSettings;

See Also