Arelle iXBRL Viewer

!ixbrl-viewer

Table of Contents

• Arelle iXBRL Viewer

Description

The Arelle iXBRL Viewer allows Inline XBRL (or iXBRL) reports to be viewed interactively in a web browser. The viewer allows users to access the tagged XBRL data embedded in an iXBRL report. Key features include:

• Full text search on taxonomy labels and references
• View full details of tagged facts
• Export tables to Excel
• Visualize and navigate calculation relationships
• Produce on-the-fly graphs using XBRL data

The viewer project consists of two components:

• A plugin for the Arelle XBRL tool
• The Javascript viewer application

1. A link to the JavaScript viewer
2. A block of JSON data that contains the results of processing the XBRL data and associated taxonomy

It is also possible to place the link to the viewer, and the block of JSON data in a separate file. See Stub Viewer Mode below.

The JavaScript viewer application is a single JavaScript file called ixbrlviewer.js. It contains all of the JavaScript that runs the viewer functionality.

Documentation

Need help with the Arelle iXBRL Viewer? Go check out [our documentation][read-the-docs].

[read-the-docs]: https://arelle-ixbrl-viewer.readthedocs.io/

Installation

The Python portion of this repo is developed using Python 3.15.

1. Clone the [iXBRL Viewer git repository][ixbrlviewer-github].
2. Download and install [Arelle][arelle-download]

Accessing the JavaScript viewer application

Accessing via the CDN

The JavaScript file is available via a CDN. It can be accessed via the following url:

https://cdn.jsdelivr.net/npm/ixbrl-viewer@<version>/iXBRLViewerPlugin/viewer/dist/ixbrlviewer.js

Where is the current version of ixbrl-viewer you are using. For instance [1.2.0][CDN].

Accessing via Github

When a new version of ixbrl-viewer is released, the javascript is included as a release asset. The asset can be found on the releases [page][ixbrlviewer-github-releases] for each version of the ixbrl-viewer.

Building the JavaScript locally

1. Install npm. Instructions can be found here:
2. Install the dependencies for javascript by running: npm install. This

1. Run npm run font. This will build the icon files.
2. Run npm run prod. This will create the ixbrlviewer.js in the

[ixbrlviewer-github]: https://github.com/Arelle/ixbrl-viewer [CDN]: https://cdn.jsdelivr.net/npm/[email protected]/iXBRLViewerPlugin/viewer/dist/ixbrlviewer.js [ixbrlviewer-github-releases]: https://github.com/Arelle/ixbrl-viewer/releases/tag/0.1.58 [arelle-download]: http://arelle.org/pub

JavaScript Versioning

The ixbrl-viewer plugin embeds processed XBRL metadata in the HTML that has a specific format read by the JavaScript. The metadata produced will work with a viewer application that has the same major version, and the same or later minor version as the plugin used to create it.

This means that once an XBRL report has been prepared by the plugin, the associated JavaScript viewer application can be upgraded within the same major version. Any features introduced in newer versions of the viewer that rely on additional metadata will degrade gracefully if that metadata is not present.

Producing an ixbrl-viewer via the Arelle GUI

Preparing an iXBRL file via the GUI

1. Open Arelle and select Manage Plugins from the Help menu.
2. Press Browse under "Find plug-in modules".
3. Browse to the iXBRLViewerPlugin directory within your checkout of the iXBRL Viewer git repository and select

1. Press Close and then Yes when prompted to restart Arelle.
2. You should now have a Save iXBRL Viewer instance on the Tools menu.
3. Open the ixbrl filing zip in Arelle
4. Select Save iXBRL Viewer instance option on the Tools menu
5. Provide a script URL to the ixbrlviewer.js file.

1. https://cdn.jsdelivr.net/npm/ixbrl-viewer@/iXBRLViewerPlugin/viewer/dist/ixbrlviewer.js 2. A relative url to the downloaded ixviewer.js from github 3. A relative url to the locally built ixviewer.js

1. Save the viewer iXBRL file to a new file in the newly created directory by

1. You should now be able to open the created file in Chrome, and the iXBRL viewer

Preparing an iXBRL document set using the Arelle GUI

To prepare an iXBRL document set, open the document set in Arelle. The process is as for a single file, except that a directory should be selected as the output location, rather than a file.

Producing an ixbrl-viewer via the Arelle command line

Preparing an iXBRL file via the command line

The plugin can also be used on the command line:

python3 Arelle/arelleCmdLine.py --plugins=<path to iXBRLViewerPlugin> -f ixbrl-report.html --save-viewer ixbrl-report-viewer.html --viewer-url https://cdn.jsdelivr.net/npm/ixbrl-viewer@<version>/iXBRLViewerPlugin/viewer/dist/ixbrlviewer.js

Notes:

• "Arelle/arelleCmdLine.py" should be the path to your installation of Arelle
• The plugin path needs to an absolute file path to the ixbrl-viewer plugin
• The viewer url can be one of the following:

Preparing an iXBRL document set

The iXBRL Viewer supports Inline XBRL document sets. This requires the inlineXbrlDocumentSet plugin. The input is specified using JSON in the following form:

[
  {
    "ixds": [
      { "file": "file1.html" },
      { "file": "file2.html" },
    ]
  }
]

The output must be specified as a directory. For example:

python3 Arelle/arelleCmdLine.py --plugins '/path/to/iXBRLViewerPlugin|inlineXbrlDocumentSet' -f '[{"ixds":[{"file":"document1.html"},{"file":"document2.html"}]}]'  --save-viewer out-dir --viewer-url https://cdn.jsdelivr.net/npm/ixbrl-viewer@<version>/iXBRLViewerPlugin/viewer/dist/ixbrlviewer.js

Notes:

• The first file specified is the "primary" file, and should be opened in a

• "Arelle/arelleCmdLine.py" should be the path to your installation of Arelle
• The plugin path needs to an absolute file path to the ixbrl-viewer plugin
• The viewer url can be one of the following:

• Due to browser security restrictions, the resulting viewer cannot be loaded

Using build-viewer.py

As an alternative to the standard Arelle command line, the samples/build-viewer.py script can also be used. To use the script, both the Arelle source code and the iXBRLViewerPlugin must be on the Python path. e.g.:

PYTHONPATH=/path/to/Arelle:/path/to/ixbrl-viewer ./samples/build-viewer.py --help

A document set can be processed by passing a directory as input. All .html and .xhtml in the directory will be combined into a document set. The generated files will be saved into the directory specified by the --out option.

Taxonomy packages can be specified using --package-dir. All ZIP files in the specified directories will be loaded as taxonomy packages.

e.g.

PYTHONPATH=/path/to/Arelle:/path/to/ixbrl-viewer ./samples/build-viewer.py --out out-dir --package-dir /my/packages/ ixds-dir

Stub viewer mode

By default, the link to the JavaScript viewer and the JSON data block are added to the iXBRL report file (or to the first file, in the case of a document set).

Stub viewer mode is an optional generation mode that creates an additional, minimal HTML file containing the JSON data block, and the link to the JavaScript viewer. This mode has two advantages over the default approach of embedding the JSON data and JavaScript link in the iXBRL report:

1. Provided that all facts and footnotes in the iXBRL report already have ID

1. The iXBRL viewer loading mask will be displayed much more quickly. This is

The downside of this mode is that due to browser security restrictions, the viewer cannot be loaded directly from files (using file: URLs); they must be served by a web server.

Optional Features

Some features are disabled by default but can be enabled at generation time or with query parameters.

To enable features:

• Via CLI: --viewer-feature-{feature name}
• Via query parameter:?{feature name}=true

This table uses the 'review' feature as an example to demonstrate how these options interact:

| CLI/JSON | Query Param | Result | |----------|-------------|------------| | unset | unset | disabled | | unset | true | enabled | | unset | false | disabled | | review | unset | enabled | | review | true | enabled | | review | false | disabled |

Feature: Review Mode

!ixbrl-viewer

A review mode is available that is intended to assist in reviewing partially tagged or incomplete documents. This mode replaces the namespace-based highlighting with optional highlighting based on untagged numbers and/or dates.

| CLI/JSON | Query Param | |---------------------------|----------------| | --viewer-feature-review | ?review=true |

Runtime config

When launched, the viewer will check for the existence of ixbrlviewer.config.json in the same directory as ixbrlviewer.js. If found, this will be loaded and used to configure the viewer.

The file supports the following keys:

• features - a JSON object containing defaults for features. These will be

• skin - a JSON object supporting the following keys:

• taxonomyNames - a JSON object where:

Relative URLs defined in the config file are resolved relative to the config file.

Disable viewer loading

Loading of the viewer can be disabled by specifying ?disable-viewer as a query parameter. This will leave the iXBRL document loaded in the browser, but without any viewer functionality. In the case of an iXBRL document set, or multi-document viewer, the first document will be shown.

Running tests

Running unit tests

In order to run the javascript unit tests make sure that you have installed all of the npm requirements.

Run the following command to run javascript unit tests: npm run test

In order to run the python unit tests, install the development dependencies with pip install ".[arelle]" --group dev

Run the following command to run python unit tests: pytest tests/unit_tests

Linting with Ruff

ixbrl-viewer uses [Ruff][ruff] to lint the codebase. Make sure you've installed the development dependencies (pip install --group dev), then run the following from the root of the repository to check your changes:

ruff check

Many issues that Ruff detects can be fixed automatically. To have Ruff apply those fixes for you, run:

ruff check --fix

Review any automatic fixes before committing, since not every change is safe to apply blindly.

[ruff]: https://docs.astral.sh/ruff/

Running Playwright tests

Run these commands from the repository root. Viewer generation requires Python, Arelle, and Bash in addition to the Node.js build tools.

1. Install the npm dependencies and Arelle:

npm ci
    pip install .[arelle]

1. Install Chromium, build the viewer, generate the test filings, and run the tests:

npm run test:integration

Playwright starts the HTTP server on port 8080 and stops it after the tests. Outside CI, it can reuse an existing server serving the generated filings. Tests run headlessly by default. To watch the browser, use npm run test:integrationTest -- --headed. To debug interactively, use npm run test:integrationTest -- --ui.

Each run installs the Chromium version required by the locally installed Playwright, rebuilds the viewer, and regenerates the filings. npm run test:integrationBuild prepares these on their own, and npm run test:integrationTest reruns the tests without rebuilding. To install only Chromium and its system dependencies, use npm run test:integrationInstall.

Reports and test results are written to tests/playwright/artifacts/, alongside but separate from the generated filings. Failed tests retain screenshots, videos, and traces. Browser logs are attached to each test in the report. Open it with:

npx playwright show-report tests/playwright/artifacts/report

👥 Contributors

Join our community and become a contributor today! 🚀

License

[Apache License 2.0][license]

[license]: https://arelle-ixbrl-viewer.readthedocs.io/en/latest/license.html