Language, help and read-only mode

UI language#

<report-designer lang="ja"></report-designer>

• Supported: en, es, fr, de, pt-BR, zh-CN, zh-TW, ja, ko. Other tags map to the nearest one (es-MX → es, zh-HK → zh-TW, pt-PT → pt-BR), and unsupported languages fall back to English.
• Unset (''): the browser's navigator.language is used.
• Changing lang switches the UI immediately, without losing work. Catalogs other than English are lazy chunks, loaded on first use.
• There is no language picker inside the designer. Set lang from your user's profile, or build a picker with LANGS and LANG_NAMES (Component API).
• The UI language has nothing to do with the document language. Documents use the template's locale (set by authors), which the render API's options.locale can override per request.

In-app help#

By default, the Help button (?) and F1 open the user guide in a resizable side drawer, at the page that matches what the user is doing. With a table selected, F1 opens "Tables → Table settings". With the Report panel focused, it opens "The Report panel".

Routing help into your own system. The event tells you the topic and the page the drawer would have opened. url is relative to the user guide (07-tables.html#table-settings), or absolute under help-base-url when you set that override. The render service serves the same pages at /help/, so new URL(url, 'https://<render-server>/help/') gives a link you can open anywhere:

import { HELP_TOPICS, type HelpRequestDetail, type HelpTopic, type ReportDesigner } from '@rd/designer';

const designer = document.querySelector('report-designer') as ReportDesigner;

// Your knowledge-base article IDs for the designer's help topics.
const articles: Partial<Record<HelpTopic, string>> = {
    'element.table': 'KB-1042',
    'element.barcode': 'KB-1043',
    'panel.report': 'KB-1050',
};

designer.addEventListener('help-request', (e) => {
    const { topic, url } = (e as CustomEvent<HelpRequestDetail>).detail;
    const article = articles[topic];
    if (article) {
        e.preventDefault();                                   // suppress the drawer
        window.open(`https://support.example.com/articles/${article}`, '_blank', 'noopener');
    }
    // otherwise the built-in drawer opens at that page as usual
    console.debug('help', topic, url, HELP_TOPICS[topic]);
});

Help topics: default, element.text, element.image, element.line, element.rect, element.ellipse, element.barcode, element.checkbox, element.table, element.repeater, element.pageBreak, panel.report, panel.fields, panel.layers, gallery, preview, expression and functions (the function reference, opened by the Functions link under every expression box). HELP_TOPICS maps each to its user-guide page and anchor. If you show help your own way (preventDefault() on help-request), that link sends functions too.

The guide is in English. In other UI languages, the drawer shows a one-line note ("Help is available in English") in the UI language.

Read-only mode#

read-only (readOnly = true) lets users inspect a template, select elements, see properties and preview, but not change anything. It suits approval workflows and template catalogs.

Help: built in, nothing to host#

The Help button and F1 open the user guide in a side drawer. The guide is built into the component. Its pages, images and search index are a lazy chunk that renders inside the designer's Shadow DOM. It works offline, uses no iframe and makes no requests to another host, and you configure nothing.

Inside the drawer, links between chapters navigate within the drawer (with back and forward buttons), search works offline, and Open in new window opens the guide in a new browser window from a blob: URL.

Options:

• help="false" removes help entirely.
• Handle the help-request event to open help in your own help system (Language, help and read-only mode).
• Override with an external copy: help-base-url="https://reports.internal.example.com/help/" makes the drawer show that copy in an iframe instead, for example the render service's /help/ (Guides served by the service). You would do this only to show a different build of the guide. Allow your app's origin in the service's RD_HELP_FRAME_ANCESTORS, and the service's origin in your app's CSP frame-src.