Worksheet output options#

Each worksheet you include in a report can carry its own Output Options, settings that control how that worksheet appears and behaves in the generated file. They are configured on the Reports step of the Job Editor, per included worksheet, alongside the worksheet's Parameters mapping.

These options apply to a single worksheet. Report-level packaging (collating and splitting) is set through Job options.

Before you begin#

• Include at least one worksheet on the Reports step. Until an Output Options entry is added, the worksheet is generated with default behavior.

Set the options#

On the Reports step, open a worksheet's Output Options panel and set any of the following.

When you set an option in the panel, it wins over the equivalent worksheet formula (RW.Tools.SheetName, RW.Tools.SheetColor, and RW.Tools.SheetSuppress; the short aliases RWSHEETNAME, RWSHEETCOLOR, and RWSHEETSUPPRESS also work). The formula is used only when the panel option is left unset.

Page breaks are not a per-worksheet Output Option. Control them from within the worksheet with the RWPAGEBREAK function. See General report and layout functions.

Shape the PDF bookmark tree and table of contents#

When a report is delivered as PDF, Reportworq builds a bookmark tree in the PDF sidebar. When you turn on Table of Contents in the PDF output options, it builds a matching contents page from the same structure, so anything you do to the bookmark tree shapes the table of contents the same way.

The tree has three levels:

• Level 1 is the root. It defaults to the job name.
• Level 2 is a report node under the root. It defaults to the report name.
• Level 3 is the leaf for each worksheet. It defaults to the worksheet name.

With no overrides, every worksheet sits under one root (the job) and one report node (the report), with the worksheet as the leaf, giving a clean single-root outline.

Set the levels for a worksheet#

Each worksheet's Sheet name option carries all three levels. When PDF is one of the report's output formats, opening that option shows three fields:

• Level 1 (PDF bookmark root)
• Level 2 (PDF bookmark report)
• Level 3 (Sheet name), the worksheet's output name. This is the only field shown when PDF is not an output format.

Each field offers the same three modes:

• Do not modify, the default, leaves the level to inherit (see How worksheet order builds the tree).
• Literal Text lets you type the title, optionally with parameter tokens.
• Cell Reference reads the title from a calculated cell.

Set Level 1 and Level 2 to give a worksheet a custom root and report node; leave a level on Do not modify to inherit it.

The formula equivalent is RW.Tools.SheetName with one, two, or three arguments. The last argument is always Level 3; earlier arguments fill Level 2, then Level 1. Omit an argument to let that level inherit.

=RW.Tools.SheetName(Level3)                    ' sheet name only
=RW.Tools.SheetName(Level2, Level3)            ' report node and sheet name
=RW.Tools.SheetName(Level1, Level2, Level3)    ' root, report node, and sheet name
=RW.Tools.SheetName(, Level3)                  ' set the leaf; Level 2 cascades

If you set the levels in the panel, they win over the formula. See the RW.Tools.SheetName function.

How worksheet order builds the tree#

Reportworq builds the tree by walking the worksheets in output order and grouping adjacent worksheets that resolve to the same title:

• Consecutive worksheets that resolve to the same Level 1 title share one root.
• Within a root, consecutive worksheets that resolve to the same Level 2 title become siblings under one report node.
• A worksheet whose Level 1 differs from the worksheet before it opens a new root, so a PDF can have more than one root.
• A worksheet whose Level 2 differs opens a new report node.

A level left on Do not modify cascades: it inherits the last title an earlier worksheet set explicitly. If nothing earlier set it, Level 1 falls back to the job name and Level 2 to the report name.

Because grouping is by adjacency, two worksheets that resolve to the same title but are not next to each other form separate nodes. So order your worksheets first, then label them.

Worked example. Six worksheets in this output order, with these levels:

builds this tree, and the same table of contents:

FY25 Pack                 (Level 1 root)
    Summary               (Level 2)
        Group             (worksheet 1)
        Regions           (worksheet 2, Level 1 and Level 2 cascade from #1)
    Detail                (Level 2, worksheet 3 opens a new report node)
        North             (worksheet 3)
        South             (worksheet 4, Level 2 cascades from #3)
Appendix                  (Level 1 root, worksheet 5 opens a second root)
    Notes                 (Level 2)
        Cover             (worksheet 5)
        Glossary          (worksheet 6, cascades from #5)

Worksheets 1 and 2 are siblings under Summary because worksheet 2 inherits both levels from worksheet 1. Worksheet 3 sets Level 2 to Detail, opening a new report node, and worksheet 4 cascades into it. Worksheet 5 sets a new Level 1 (Appendix), opening a second root, and worksheet 6 cascades under it.

Leave a worksheet out with a section break#

To keep a worksheet's pages in the PDF but out of the bookmark tree and table of contents, select Omit this worksheet from the PDF bookmarks and table of contents in the Sheet name option, shown under PDF section break when PDF is an output format.

Use this for an intentionally blank divider page. Its pages still print, but the worksheet is left out of the bookmark tree and table of contents, and its pages are excluded from page numbering. The visible numbering stays continuous across it, so page 3 is followed by the next numbered page 4.

The formula equivalent is an optional trailing FALSE on RW.Tools.SheetName:

=RW.Tools.SheetName("Divider", FALSE)    ' name the sheet and omit it
=RW.Tools.SheetName(FALSE)               ' omit it without renaming

The checkbox wins over the formula.

Upgrading from version 5? The Custom TOC Title and PDF Parent Bookmark settings are now part of the Sheet name option: a Custom TOC Title becomes Level 1 and a PDF Parent Bookmark becomes Level 2. Your existing settings carry over automatically.

Suppress a worksheet conditionally#

Sheet suppression deletes the tab from the output, it does not hide it, when its cell or RWSHEETSUPPRESS formula evaluates TRUE (a value of 1 or a boolean true). On FALSE the tab is kept.

A common pattern is a formula that keeps a tab only when it holds data, so recipients never receive an empty schedule. A worksheet is also auto-suppressed when it carries a provider report that returns no data.

When to use it: drop lookup or staging tabs so recipients see only presentation worksheets, or hide a schedule that has nothing to show this period.

Send only on an exception (the exception check)#

The exception check turns a worksheet cell into a send gate for the whole report. The rule is an OR across every worksheet:

• If no worksheet defines an exception cell, the report always sends.
• If one or more worksheets define an exception cell, the report is delivered only when at least one of those cells, anywhere in the report, evaluates TRUE. If all of them are FALSE, delivery is suppressed.

When to use it: send a variance pack only to the managers who are actually over budget. Put an exception cell on a validation tab that turns TRUE when a threshold is breached, and recipients whose reports stay within tolerance receive nothing.

Notes and limits#

• Sheet tab color applies to Excel output; the bookmark levels (Level 1 and Level 2) and the PDF section break apply to PDF output. The options are format-relevant, and the bookmark fields appear only when PDF is an output format.
• Suppression removes the tab entirely. There is no keep-but-hidden state at this layer.

Related topics#

• Choose the source workbook and worksheets
• Job options
• Parameters reference