Table of Contents

HTML export

The HTML export produces browser-ready .html output from a List & Label report project. It is provided by the separate combit.ListLabel32.CrossPlatform.Export.Html.dll assembly and selected with LlExportTarget.Html.

The exporter preserves the visual report layout while generating real HTML structures for report content such as text, images, links, and tables. Reports can be written as one HTML document or split into separate page documents.

Note

The HTML package must be installed for HTML export to be available at runtime. See Installing export packages.

Web accessibility

The HTML exporter is designed with web accessibility in mind. It produces semantic HTML and WAI-ARIA metadata to support accessible browser output and WCAG-based accessibility requirements.

Accessibility information is embedded directly into the generated HTML instead of describing report content only through position, geometry, and visual layout without semantic relationships. Among other things, the exporter:

  • Uses native table elements such as table, thead, tbody, tfoot, th, and td.
  • Automatically resolves relationships between table headers and data cells from the rendered table geometry, including column and row spans.
  • Associates table header and data cells using native scope and headers attributes where required.
  • Emits WAI-ARIA roles and aria-label values for report items with accessibility names.
  • Writes alternative text to the alt attribute of exported images.
  • Hides decorative drawings and generated layout-only table rows from assistive technologies with aria-hidden="true".

Accessible names and alternative text are derived from the corresponding report-object name metadata. Use meaningful names in the report project for objects that convey information. For table fields and objects, the accessible text can be explicitly overridden using AccessibilityAltText. Unlike the regular report-object name, AccessibilityAltText supports formulas, which are evaluated during report generation before the value is used for accessibility output.

Note

The exporter provides the semantic and accessibility infrastructure required for accessible HTML, but the report itself must also be semantically structured correctly. For example, rows that are intended to act as table headers or footers must be defined using the corresponding header or footer elements in the report project. A row that only looks like a header visually cannot automatically be treated as a semantic header. The automatic geometric header resolution can associate correctly defined headers with their data cells, but it cannot replace missing semantic information in the report definition.

Accessibility is also a property of the report content itself. Meaningful text alternatives, understandable link text, suitable reading order, sufficient color contrast, and other content-level requirements remain the responsibility of the report author. Therefore, using HTML export alone does not automatically guarantee conformance of every report with a particular WCAG conformance level.

For background information about the Web Content Accessibility Guidelines, see the WCAG overview from the W3C Web Accessibility Initiative.

Output structure and resources

The HTML exporter writes the primary HTML document to the configured export directory and may create additional resources next to it.

Depending on the selected options, the export can contain:

  • A single HTML document containing all report pages.
  • An index document plus one HTML document per report page.
  • Drawing and image resources.
  • Toolbar resources.
  • A generated stylesheet used for the general appearance of the exported HTML.

By default, drawing resources are written to the Images directory and toolbar resources to the Toolbar directory below the export directory. The generated stylesheet is written as styles.css in the export directory.

Resource directories and the stylesheet destination can also be configured with absolute paths or paths relative to the export directory. The exporter creates browser URLs relative to the generated HTML documents. Therefore, an external resource location must be reachable from the HTML output through a relative URL.

Styling the HTML output

The HTML exporter always writes an external stylesheet for report-independent presentation settings such as the document background, page appearance, toolbar colors, and search-result highlighting.

When no custom stylesheet is configured, the exporter writes its default stylesheet. The default stylesheet defines the supported presentation values as CSS custom properties on the :root selector.

The stylesheet is referenced by every generated HTML document. In multi-document output, the index document and the individual page documents use the same stylesheet.

Default stylesheet

The default stylesheet contains the following CSS custom properties:

:root {
    --ll-document-background: #b3b3b3;
    --ll-page-background: #ffffff;
    --ll-page-margin: 12px auto;
    --ll-page-box-shadow: 0 2px 10px rgba(0, 0, 0, 0.35);

    --ll-toolbar-color: #2d2d2d;
    --ll-toolbar-background: #f7f7f7;
    --ll-toolbar-border-color: #d7d7d7;
    --ll-toolbar-control-background: #ffffff;
    --ll-toolbar-control-border-color: #bdbdbd;
    --ll-toolbar-muted-color: #555555;

    --ll-search-highlight-color: #000000;
    --ll-search-highlight-background: #ffe066;
    --ll-search-highlight-active-color: #000000;
    --ll-search-highlight-active-background: #ff8f1f;
}

The following properties form the supported styling interface for the general appearance of the HTML export:

CSS custom property Purpose
--ll-document-background Background of the browser document around the exported report pages.
--ll-page-background Background color of individual report pages and page-like content.
--ll-page-margin Margin around report pages. The default creates vertical spacing and centers pages horizontally.
--ll-page-box-shadow Screen-only shadow used to visually separate report pages from the document background.
--ll-toolbar-color Primary foreground and text color of the HTML toolbar.
--ll-toolbar-background Main toolbar background color.
--ll-toolbar-border-color Border color used to separate the toolbar from the report content.
--ll-toolbar-control-background Background color of toolbar controls such as input fields.
--ll-toolbar-control-border-color Border color of toolbar controls.
--ll-toolbar-muted-color Secondary toolbar text color used for less prominent information.
--ll-search-highlight-color Text color of search-result highlights.
--ll-search-highlight-background Background color of search-result highlights.
--ll-search-highlight-active-color Text color of the currently active search-result highlight.
--ll-search-highlight-active-background Background color of the currently active search-result highlight.

These properties control report-independent presentation only. Report-specific styling such as object positions, page dimensions, fonts, fills, frames, and colors defined by report objects continues to be generated from the report project.

Replacing the stylesheet

Use HtmlStyleSheet to replace the complete default stylesheet with custom CSS.

The option value is CSS content, not a file path. The supplied content is written to the generated stylesheet file exactly as the stylesheet for the export.

Important

HtmlStyleSheet replaces the default stylesheet completely. It is not appended to the default CSS.

The generated HTML uses the CSS custom properties listed above. When replacing the default stylesheet, keep the properties that are required by the exported presentation. Starting with the default stylesheet and changing only the desired values is therefore recommended.

The custom stylesheet may also contain regular CSS rules. It is referenced after the CSS generated by the exporter, so normal CSS cascade and specificity rules can be used to override generated presentation where appropriate.

The CSS custom properties documented above are the recommended stable customization interface. Internal class names and selectors generated for report objects are implementation details and should not be treated as a stable API. In compact output mode, generated identifiers may also be shortened.

Editing the generated stylesheet after export

Because the stylesheet is stored as a separate file, it can also be edited after the export has completed. Reload the HTML document in the browser to apply the changes.

The stylesheet file is generated again on every export. Manual changes to the generated file are therefore overwritten by the next export. To make styling persistent across exports, configure the desired content through HtmlStyleSheet.

The output location of the generated stylesheet is controlled by HtmlStyleSheetPath.

Resource paths

The HTML exporter can write generated resources either below the export directory or to another location that can still be referenced from the generated HTML by a relative URL.

The following options use this path behavior:

  • HtmlToolbarDirectory for toolbar resources.
  • HtmlDrawingDirectory for drawing and image resources.
  • HtmlStyleSheetPath for the generated stylesheet.

Relative paths are resolved against the HTML export directory. Parent-directory references such as ../shared are supported.

Absolute paths are supported when the target location can be referenced from the HTML export directory using a relative URL. The exporter derives the browser URL automatically and normalizes path separators for HTML.

A target location that cannot be represented by a relative URL from the HTML export directory is not supported. On Windows, this applies for example when the HTML output and the resource target are located on different drives.

Note

In multi-document output, the index document and the generated page documents use the same configured resource locations. The exporter creates the required relative browser references automatically.

Supported export options

All options are set on ExportConfiguration.ExportOptions using the LlExportOption keys listed below. Values are always strings.

ExportAllInOneFile

Controls whether report pages are written into one HTML document or into separate page documents.

Value Meaning
"0" Write one HTML document per report page. The primary output is an index document that references the generated page files.
"1" Write all report pages into one HTML document.

When this option is not supplied, the HTML exporter uses single-document output.

ExportInfinitePage

Renders the report onto a single, very tall page instead of breaking it according to the project's page size.

Value Meaning
"0" Default. Page breaks follow the project's page size.
"1" The report is rendered as a single continuous page.

HtmlTitle

Sets the text written to the HTML document's title element.

  • Value: any string.
  • Default: LL-Report.

The document language is derived from the current culture and written to the root html element.

HtmlCompressionMode

Controls whether generated HTML, CSS, identifiers, and class names favor readability or compact output.

Value Meaning
"0" Readable output.
"1" Default. Compact output.

HtmlFixedHeader

Controls whether table headers remain visible while scrolling.

Value Meaning
"0" Default. Table headers scroll normally.
"1" Keep the resolved table header row fixed while scrolling.

HtmlIncludeToolbar

Controls whether the HTML toolbar and its resources are included.

Value Meaning
"0" Do not include toolbar resources.
"1" Default. Include the toolbar.

The toolbar is hidden automatically in print CSS.

HtmlToolbarDirectory

Sets the output directory for generated toolbar resources such as toolbar stylesheets, scripts, and related assets.

  • Value: an absolute path or a path relative to the export directory.
  • Default: Toolbar below the export directory.

See Resource paths for the common path and URL resolution rules.

HtmlDrawingDirectory

Sets the output directory for generated drawing and image resources used by the exported report.

  • Value: an absolute path or a path relative to the export directory.
  • Default: Images below the export directory.

The exporter creates the individual drawing resource names inside this directory according to HtmlResourceNamingMode.

See Resource paths for the common path and URL resolution rules.

HtmlStyleSheet

Specifies the complete CSS content of the generated HTML stylesheet.

  • Value: CSS content.
  • Default: the stylesheet described in Default stylesheet.
  • The value is CSS content, not a file path.
  • When specified, the value replaces the default stylesheet completely.
  • The stylesheet is generated for every export, even when this option is not specified.

Use this option to persistently customize the general appearance of exported HTML. For the supported CSS custom properties and a complete example, see Styling the HTML output.

HtmlStyleSheetPath

Specifies the output file path of the generated HTML stylesheet.

Unlike HtmlToolbarDirectory and HtmlDrawingDirectory, this option identifies a file rather than a directory.

  • Value: an absolute file path or a file path relative to the export directory.
  • Default: styles.css in the export directory.

In multi-document output, the index document and the individual page documents reference the same stylesheet.

See Resource paths for the common path and URL resolution rules.

HtmlResourceNamingMode

Controls how names for generated drawing resources are created.

Value Meaning
"0" Default. Use GUID identifiers.
"1" Use deterministic identifiers within the export run.

Use deterministic naming when reproducible resource names are useful for testing, comparisons, caching, or downstream processing.

Resolution

Sets the minimum resolution in PPI of the objects that are exported as images, such as charts, barcodes and drawings. Gauges, data graphics and PDF objects are always rendered at 600 PPI or more.

  • Value: a positive integer PPI value up to "2400", for example "300". A higher value is reduced to "2400"; any other value is ignored and the default applies.
  • Default: "300".

Configuration example

ExportConfiguration config = new ExportConfiguration(
    LlExportTarget.Html, ...);

config.ExportOptions[LlExportOption.ExportInfinitePage] = "1";
config.ExportOptions[LlExportOption.HtmlTitle] = "Sales report";
config.ExportOptions[LlExportOption.HtmlFixedHeader] = "1";
config.ExportOptions[LlExportOption.HtmlIncludeToolbar] = "1";

// Relative path below the export directory.
config.ExportOptions[LlExportOption.HtmlToolbarDirectory] =
    "assets/toolbar";

// Absolute path.
config.ExportOptions[LlExportOption.HtmlDrawingDirectory] =
    @"C:\ReportResources\Images";

// Replace the default stylesheet.
config.ExportOptions[LlExportOption.HtmlStyleSheet] = """
    :root {
        --ll-document-background: #b3b3b3;
        --ll-page-background: #ffffff;
        --ll-page-margin: 12px auto;
        --ll-page-box-shadow: 0 2px 10px rgba(0, 0, 0, 0.35);

        --ll-toolbar-color: #2d2d2d;
        --ll-toolbar-background: #f7f7f7;
        --ll-toolbar-border-color: #d7d7d7;
        --ll-toolbar-control-background: #ffffff;
        --ll-toolbar-control-border-color: #bdbdbd;
        --ll-toolbar-muted-color: #555555;

        --ll-search-highlight-color: #000000;
        --ll-search-highlight-background: #ffe066;
        --ll-search-highlight-active-color: #000000;
        --ll-search-highlight-active-background: #ff8f1f;
    }
    """;

// Parent-relative file outside the export directory.
config.ExportOptions[LlExportOption.HtmlStyleSheetPath] =
    "../shared/report.css";

Restrictions

The HTML export cannot reproduce every aspect of the rendered report exactly. The following differences are inherent to browser-based rendering or the current exporter implementation:

  • Element positions may differ by up to approximately one CSS pixel compared with the PDF export. The PDF renderer can preserve the report layout using the original micrometer-based coordinates, whereas HTML positions must be converted to CSS units and are ultimately subject to the browser's layout and rounding behavior.

  • Line breaks may differ from the PDF export in rare cases. Text layout and wrapping in HTML are performed by the browser and therefore depend on its font metrics and text layout engine. PDF rendering uses List & Label's own layout logic, so wrapping decisions may differ slightly.

  • Border rendering can differ from the PDF export. Very thin lines, such as hairlines, are subject to the minimum line width that can effectively be represented by the browser. In addition, HTML tables use CSS border-collapse, so adjacent cell borders are not drawn independently. While overlapping borders in the PDF renderer are determined by drawing order, browsers resolve collapsed-border conflicts according to CSS border conflict resolution rules. For example, a thicker border generally takes precedence over a thinner adjacent border.

Note

Interactive elements are not yet supported by the HTML exporter. Support for interactive report content is currently under development and is planned for a future version.