Styles option

Alongside report templates, Neos supports report style bundles.

A styles bundle is equivalent to an .sts file exported from an existing .mrt report template.

A report style bundle must contain a collection named AutomaticNeosStyles.

When a report names a style bundle, or business code selects one through WithStylesCollection, Neos imports and applies the AutomaticNeosStyles collection to Viewer and PDF output.

Cluster default

A cluster can provide a style for every report that does not declare its own ReportStyleName:

Reporting:
    DefaultReportStyleName: MyClusterReportStyle

MyClusterReportStyle must be a ReportStyle asset in the cluster. Neos resolves the setting when a report is opened or generated, so changing this value also changes the style used by existing reports that do not name a style.

If the setting is absent, style-less reports keep their previous behavior and no style is applied. If the setting names a missing ReportStyle asset, generation fails instead of silently producing an unstyled report.

Older business clusters

Cluster-level default report styles were introduced in Neos 3.2. The reporting service is deployed once for the whole namespace, so it also serves business clusters that predate the feature. Those clusters do not expose the endpoint at all and answer the request with a 404, which the reporting service reads as "this cluster has no cluster-level default style" and continues without one. Reports that name their own ReportStyleName are unaffected.

Because of that, on the default-style endpoint a 404 means "the cluster does not know about cluster-level default styles" and nothing else. A cluster that does know about them, and whose configured default cannot be loaded, reports a server error instead, so a genuine misconfiguration is never mistaken for an older cluster. The one exception is a cluster running exactly 3.2.2, the single release that answered that case with a 404: against it a broken default style is ignored rather than reported.

Precedence

Neos selects one bundle. The first available source in this table wins:

Priority	Source	Used in
1	`WithStylesCollection` in business code	Viewer and PDF generation
2	The report's `ReportStyleName`	Report designer, Viewer, and PDF generation
3	`Reporting:DefaultReportStyleName`	Report designer, Viewer, and PDF generation

An empty ReportStyleName means "use the cluster default". To keep one report unstyled in a cluster that has a default, assign an empty ReportStyle bundle to that report.

Apply a style from code

Business code can override the report and cluster settings for one execution:

var options = new ExecuteReportOptions("MyReport")
    .WithStylesCollection("MyBundleWithTheAutomaticNeosStyles");

await this.ExecuteReportWithOptionsAsync(options);

Edit a style bundle

Report styles use an editor similar to the report template editor.

Select a report as a temporary container to edit and preview the bundle. The cluster default is not imported into ReportStyleDesigner sessions, because doing so would mix its styles into the bundle being edited. Clone the default bundle when it should be the starting point for another bundle.

Report designer behavior

Opening a report imports its own ReportStyle bundle or the cluster default into the in-memory report. The design canvas does not apply those styles automatically. Use Preview to see the result that Viewer and PDF generation will produce.

Changing or removing the report's style while the editor is open replaces the imported AutomaticNeosStyles collection immediately. Other styles authored directly in the report remain intact.

Neos removes the imported AutomaticNeosStyles collection before saving the .mrt, then restores it in the live editor session. The .sts asset remains the single source of truth, so changing a shared bundle does not create style changes in every report template.

Tenant module override

A Tenant module can override the content of a ReportStyle bundle, as it can for a report template. The cluster still selects the bundle by name; the tenant override changes its content.

Table of Contents