# Workspaces and components

> How workspaces organise filters, data types and layout, and how tables, text, metrics, charts and presentation rules are configured.

A workspace (*Arbetsyta*) is one screen of an app: a filter row, a choice of data types, and a layout holding components such as tables, text, metrics and charts. End users switch between workspaces with a selector at the top. Every data component reads from one [dataset](datasets.html).

## Workspaces

A workspace has a name, a hidden flag, and six tabs in the editor: **Components** (*Komponenter*), **Filters** (*Filter*), **Data type / references** (*Datatyp / referenser*), **Value types** (*Värdetyper*), **Actions** (*Handlingar*) and **Layout**. Actions are described in [Actions](actions.html).

### Filters

The **Filters** tab defines the workspace filter row. A filter can be on a dimension, a property, the data type or the value type. Each row has a three-state switch:

| State | Swedish label | Configuration |
|---|---|---|
| Unavailable | *Otillgänglig* | the filter is absent from the workspace filter list |
| Available | *Tillgänglig* | the filter is present |
| Required | *Obligatoriskt* | the filter is present and marked as required |

The order in the tab (drag and drop) is the order users see. Only one filter per dimension is kept. Dimension and property filters have their own **Display as** and **Sort by** settings. Selections are carried in the app URL; see [Using apps](end-user.html#the-app-frame).

#### Required filters

A required filter is configured in the side panel **Filter requirement** (*Filterkrav*):

| Setting | Swedish label | Configuration (JSON) |
|---|---|---|
| Message | *Meddelande* | `Message` |
| Maximum number of selected values | *Maxantal valda värden* | `MaxSelections` |
| Make required for all components | *Gör obligatorisk för alla komponenter* | `AllComponents` |
| Components | chips | `Components[]` |

Until a value is selected, the affected components show the message instead of data, for example *"Select a department"* with maximum 1 on a large table. Requirements can also be put on data-type and value-type filters.

### Data types and references

Apps treat plan data and references as members of a virtual dimension, `DataType`. Its codes are:

| Code | Meaning |
|---|---|
| `Plan` | plan data |
| `Reference_<id>` | a reference in the plan, for example `Reference_12`. Metrics and URLs use the bare ID instead, see [Metric](#metric) |
| *(custom string)* | a custom data type created by a dataset expression on the `DataType` dimension |

The **Data type / references** tab decides which data types the workspace offers.

Plan data has four modes:

| Mode | Meaning |
|---|---|
| `Selected` | offered and pre-selected in the filter |
| `Hidden` | not shown |
| `Required` | users must filter to it; the GUI shows *Required* (*Obligatoriskt*) |
| `Allowed` | offered but not pre-selected |

`UsePlanName` shows the plan's name instead of "Plan", and a name override can be set.

References have three states:

| State | Swedish label | Configuration |
|---|---|---|
| Default | *Förvald* | listed and selected |
| Available | *Tillgänglig* | listed, not selected |
| Unavailable | *Otillgänglig* | not listed |

The display order of data types is set by dragging them from *Unsorted* (*Osorterade*) into *Sorted* (*Sorterade*). Reference data is always read-only in apps. See [References and history](references-history.html).

### Value types

The **Value types** tab holds only display-name overrides and the display order of value types in the workspace.

### Layouts

The **Layout** tab chooses one of two layouts:

| Layout | Swedish label | Behaviour |
|---|---|---|
| `MultiPage` | *Flera sidor* | one component per page; users switch pages with a page selector |
| `Matrix` | *Rutnätslayout* | several components placed on a grid |

The `Matrix` layout is a **12-column grid**. Each component has a location (`X`, `Y`, `Width`, `Height`). The editor shows width and height as percentages: a width of 12 columns is *100 %*, and a height of 5 units is *50 %* (10 units = 100 %). Components can be hidden individually.

Layout **Settings** (*Inställningar*) for the grid layout are **Background** (*Bakgrund*) and **Border** (*Kantlinje*), each an on/off switch with a colour for light and dark mode, and **Spacing** (*Avstånd*): `Minimum`, `Small`, `Medium` (default) or `Large`, stored by name. In a multi-page layout, pages can be hidden from the page selector.

## Component types

| Type | GUI (*Typ*) | Purpose |
|---|---|---|
| `Grid` | Table (*Tabell*) | editable table with groupings, pivots, totals and presentation rules |
| `Label` | Text (*Text*) | static text, plain or Markdown |
| `LayoutableAction` | Layoutable action (*Layoutbar åtgärd*) | places an existing action component in the layout instead of the sidebar |
| `Metric` | Metric (*Mätvärde*) | a KPI box with one value and an optional comparison |
| `BarChart` | Chart → Bar (*Diagram → Stapel*) | bar chart |
| `LineChart` | Chart → Line (*Diagram → Linjer*) | line or area chart |
| `PieChart` | Chart → Pie (*Diagram → Cirkel*) | pie chart |
| `WaterfallChart` | Chart → Waterfall (*Diagram → Vattenfall*) | waterfall (bridge) chart |
| `TreeMapChart` | Chart → Treemap (*Diagram → Trädkarta*) | treemap |

Every component has an ID, a name (shown as the title in a grid layout) and **Show headers** (*Visa rubriker*, `HideHeader`).

### Text

A `Label` component shows text from `Content`. `Format` is `Text` (default) or `Markdown`. Raw HTML is never rendered.

### Layoutable action

A `LayoutableAction` has no logic of its own. It points to an action component by `ActionComponentId` and shows it in the layout.

In the app, a layoutable action renders as an inline form titled with the component name: the action's fields, a *Keep values* toggle (*Behåll värden*), the run button and *Clear* (*Rensa*). Unless the action is hidden from the sidebar, it also appears as a vertical tab at the right edge. The tab has a *Keep open* toggle (*Behåll öppen*) instead. The action's script writes to the plan the app belongs to.

## Tables

A table (`Grid`) is the main editing component. Its **Settings** tab has a *Functions* section (*Funktioner*):

| Setting | Swedish label | Values |
|---|---|---|
| Row totals | *Radsummor* | Left · Right · Disabled (`Left`, `Right`, `Disabled`) |
| Auto-size columns | *Automatisk storlek på kolumner* | Disabled · Cell content · Grid width (`Default`, `FitCellContents`, `FitGridWidth`) |
| Column totals | *Kolumnsummor* | Enabled · Disabled (`EnableColumnTotals`) |

Further flags: `EnableUserConfig` lets users change their own column setup with *Edit* in the component menu, and `EnableComments` allows cell comments.

### Groupings, intermediaries and pivots

A table has three axes:

| Axis | Swedish label | Role | Settings |
|---|---|---|---|
| Groupings | *Grupperingar* | row groups with subtotals, shown in a merged group column | `EnableEdit` |
| Intermediaries | *Intermediaries* | row dimensions shown as their own columns between groups and values | `EnableEdit`, `Link` |
| Pivots | *Pivots* | dimensions turned into columns | `SortDirection` (`Ascending`, `Descending`) |

Each axis entry is one of four kinds: a **dimension**, a **property** of a dimension, the **value type** dimension, or the **data type** dimension. A typical budget table has the value type as grouping, `Account` and `Department` as intermediaries, and `Month` as pivot.

`EnableEdit` on an intermediary makes the column editable, so users can change, for example, the account of a row directly in the table.

#### Dimension links

An intermediary can carry a **link**. Clicking a dimension value then navigates to a component (`NavigateToComponentId`), optionally in another workspace or app (`NavigateToWorkspaceId`, `NavigateToAppId`). `FilterToSelectedValue` filters the target to the clicked value, `IncludeGroupingsInFilter` also passes the row's grouping values, and `OpenInNewTab` and `HideIcon` control how the link opens and shows.

### Component filters

Component filters limit what **this component** shows from its dataset. They are evaluated client-side and do not change the dataset. A filter is a list of sets. Each set has a mode:

- `Include`: show only the selected values;
- `Exclude`: show everything except the selected values.

A set can contain several dimension and property filters, and at most one value type filter and one data type filter. All sets in the list apply together.

Component filters let several components share one dataset. Two tables on the same dataset can each show one value type, for example one showing `Amount` and one showing `Headcount`, while initial values, locks and expressions are maintained once.

### Column settings

The **Columns** tab (*Kolumner*) stores per-column settings. There are two kinds:

| Kind | Identified by | Settings |
|---|---|---|
| `Column` | `Id` (XML `Value`) | `Enabled`, `NameOverride`, `Width`, `SortIndex`, `SortDirection`, `Pinned` |
| `ColumnGroup` | `Id` | `Enabled`, `NameOverride`, `Pinned` |

`Pinned` is `Left` or `Right`. Column IDs follow the pattern `<axis>[~<code>]`, for example `Month~202601` for one pivoted month or `ValueTypeId~Amount` for a pivoted value type. The full grammar is in [App configuration](app-config.html#column-setting-ids).

A `ColumnGroup` is a pivot group header, for example one month above its value-type columns. Column-group settings are created by end users with edit rights in the app, not in the admin **Columns** tab: **Edit** (the pencil), then the menu on a group header offers *Fästning grupp* (pin group) and *Ändra namn* (rename). Saving writes for example:

```json
{"$type": "ColumnGroup", "Id": "TestMonth~202601", "Enabled": true,
 "NameOverride": "Jan 2026", "Pinned": "Left"}
```

### Value type overrides

The tab **Custom aggregations and spreads** (*Egna aggregeringar och spridningar*) overrides aggregation and spread for a value type **in this component only**, optionally per dimension or property. Example: show `Headcount` summed over departments but not aggregated over months, or turn off aggregation for a date value type.

```json
{"ValueTypeId": "Headcount",
 "Dimensions": [{"$type": "Dimension", "DimensionId": "Department", "Aggregation": "Sum"}]}
```

### Header template

`HeaderTemplate` defines a dynamic component header. Placeholders: `{planName}`, `{appName}`, `{appStatus}`, and `{currentSelections_Code}` / `{currentSelections_Name}` for the codes or names of the currently selected cells.

### External links

`ExternalLinks` define links to other systems built from the row's dimension values. `Pattern` is a URL template with `{<DimensionId>}` placeholders. On a group row, the placeholder expands to the values of the child rows, joined with `Delimiter`:

```json
{"Title": "Open in project system",
 "Pattern": "https://projects.example.com/?ids={Project}",
 "Delimiter": ","}
```

External links appear in the cell's right-click menu and open in a new browser tab.

!!! warning "Placeholder syntax"
    Use `{DimensionId}`. The `{d_DimensionId}` form described in the configuration schema produces no link.

### App links (drill-through)

An **app link** turns the values of an intermediary column into links to another app, workspace or component, for drill-through to a detail view. It is set on the intermediary's settings:

```json
{"$type": "Dimension", "DimensionId": "Month",
 "Settings": {"$type": "Intermediary", "EnableEdit": false,
   "Link": {"NavigateToAppId": "<app GUID>", "NavigateToWorkspaceId": 3,
            "NavigateToComponentId": "6", "FilterToSelectedValue": true,
            "IncludeGroupingsInFilter": true, "OpenInNewTab": false, "HideIcon": false}}}
```

| Setting | Effect |
|---|---|
| `NavigateToAppId`, `NavigateToWorkspaceId`, `NavigateToComponentId` | The target. Leave out the app to link within the same app. |
| `FilterToSelectedValue` | Pass the clicked value as a filter |
| `IncludeGroupingsInFilter` | Also pass the values of the grouping levels above the row |
| `OpenInNewTab` | Open the target in a new tab |
| `HideIcon` | Hide the link icon next to the value |

Clicking a value opens the target with the values in the URL, for example `?Month=202602&Account=A1&componentId=6`, and the target shows a back arrow to the source. The values only filter the target where its workspace has a filter for that dimension.

Link values are styled with the presentation-rule target `Link`.

## Presentation rules

Presentation rules (*Presentationsregler*) style table cells based on what they contain and where they come from. The editor's own summary: *"Create custom styles based on conditional statements. When conditions overlap, later entries override earlier ones."* Order matters: rules are dragged into order, and **a later rule overrides an earlier one**.

Each rule has a **name** (*Namn*), an **enabled** switch (*Aktiverad*), the **targets** it applies to (*Applicera på*), optional filters on **line state** (*Applicera på radstatus*) and **access type** (*Applicera på accesstyp*), further **conditions** (*Villkor för applicering*), and **effects** (*Effekter*) such as background and font colour.

The **Example** column (*Exempel*) in the rule list shows a live preview of each rule's style. **Reset default styles** (*Återställ standardstilar*) restores the default rules.

### Targets

| Target | Applies to |
|---|---|
| `Leaf` | value cells at the lowest level (*Löv*) |
| `RowTotal` | row total cells (*Radtotal*) |
| `Group` | cells on group rows (*Grupp*) |
| `GroupRowTotal` | row totals on group rows (*Grupp radtotal*) |
| `ColumnHeader` | the header row, including dimension column headers |
| `Footer` | the column-totals row at the bottom (*Gridfot*) |
| `PivotColumn` | pivoted columns; used with *Visibility* to hide a column, for example one value type or expression, scoped with the rule's value-type selection |
| `RowTotalColumn` | the row-total column; used with *Visibility* to hide it |
| `GridDimensionGrouping` | the grouping column, on group rows and leaf rows |
| `GridDimensionIntermediary` | the intermediary (row-leaf) columns |
| `Row` | whole rows, including group rows; with *Sequence pattern* every row, odd or even rows |
| `Link` | dimension values that are [app links](#app-links-drill-through) |

Verified behaviour:

- Rules are applied in list order, so a later `Row` rule overrides earlier column rules (`GridDimensionGrouping`, `GridDimensionIntermediary`) on the rows it applies to.
- A hidden pivot column is still **included in the row total**. Hiding an expression column does not remove it from the total.
- Style settings on `RowTotalColumn` (such as font colour) have no effect; only *Visibility* does.
- A row total across value types requires the same aggregation for all of them. Mixing, for example, `Quot` and `Sum` gives *Can't aggregate ValueTypes (…) with different aggregations (Quot, Sum)* instead of a table.

Not every setting works on every target:

| Setting | Targets |
|---|---|
| Height | `ColumnHeader`, `Footer`, `Row` |
| Visibility | `PivotColumn`, `RowTotalColumn`, `Row` |
| Sequence pattern | `Row` |
| Value condition, line state, line access | `Leaf`, `RowTotal`, `Group`, `GroupRowTotal`, `Footer` |
| Other styles (colours, font, alignment) | all targets except `PivotColumn` and `RowTotalColumn` |

### Line state and line access

Line state records where a cell's value comes from:

| Code | Line state | Swedish label | Meaning |
|---|---|---|---|
| 0 | `Suggested` | *Föreslagen* | recently imported, or written by a suggestion calculation (`write suggestion to`); users can overwrite it |
| 10 | `Edited` | *Redigerad* | entered by a user |
| 30 | `Calculated` | *Beräknad* | written by a calculation |
| 40 | `InitialValues` | *Initiala värden* | a placeholder from [initial values](datasets.html#initial-values), not yet filled in |

| Code | Line access | Swedish label |
|---|---|---|
| 1 | `Read` | *Läs* |
| 2 | `ReadWrite` | *Läs/Skriv* |

With line state in rules, a cell shows whether its number was entered, suggested, calculated, or is an empty slot. See [Traceability](traceability.html).

### Value conditions

A rule can have a value condition (*Värdevillkor*), decimal or string, with a first comparison and an optional second comparison joined by `And` or `Or`:

| Type | Comparisons |
|---|---|
| Decimal | `Equal` · `NotEqual` · `GreaterThan` · `LowerThan` · `Exists` |
| String | `Equal` · `NotEqual` · `Match` · `Exists` |

Example: highlight values *Greater than 100000* in red to flag outliers.

### Sequence pattern

`SequencePattern` (`Every`, `Odd`, `Even`) applies only to the `Row` target and is used for row banding. Banding takes **two** rules, one `Odd` and one `Even`, each with its own background colour.

### Scoping to specific data

A rule can be limited to specific dimension values, property values, value types or data types. Examples:

- style the value type `AmountActual` in a different colour from the budget rows;
- strike through closed periods: scope to `Month.Closed` = `1` with font decoration `LineThrough`.

### Styles

Available effects: font colour and background colour (each with a light-mode and a dark-mode value), font weight (`Normal`, `Bold`), font style (`Normal`, `Italic`), font decoration (`None`, `Underline`, `LineThrough`), font size, horizontal alignment (`Start`, `Center`, `End`), vertical alignment (`Top`, `Center`, `Bottom`), and, on targets that support them, height and visibility (`Visible`, `Hidden`).

Colours are hex values stored **without** a leading `#`, for example `1F9AAD`.

### Default rules

New apps get three default rules, identified by a default rule key instead of a name:

| Key | Swedish label | Matches | Typical style |
|---|---|---|---|
| `Suggested` | *Föreslaget värde* | line states Suggested and Initial values, access Read/Write | font `1F9AAD`, dark mode `00bcd4` |
| `ReadOnly` | *Skrivskyddat* | access Read | font `595959` (dark `bdbdbd`), grey background |
| `Calculated` | *Beräknat värde* | line state Calculated | font `595959` (dark `bdbdbd`) |

The default rules target `Leaf`, `RowTotal`, `Group`, `GroupRowTotal` and `Footer`. Their exact colours can differ between apps. The `ReadOnly` rule is what makes locked and read-only cells grey. Custom rules placed after the default rules override them.

## Metric

A `Metric` is a KPI box. It shows `ValueTypeId` from `DatasetId` in one data type (`DataType`: `Plan`, or a reference given by its bare ID, for example `"12"`). `Unit` is `Custom` with a free label (for example "FTE") or `Currency` with an ISO 4217 code and optional label. `Compare` adds an optional comparison value.

`Icon` takes a name from a fixed list (see below). An unknown icon name is **silently removed** when the configuration is read.

The comparison is shown next to the main value as a target or reference:

| Compare type | Compares with |
|---|---|
| `ValueType` | another value type |
| `DataType` | the same value type in another data type, for example plan against a budget reference |
| `UserSelectDataType` | the data type the user has currently selected in the workspace's data-type filter |

Each comparison has `Mode` (`Difference` for the absolute difference, `Relative` for the relative difference), an optional name override, and three colour pairs (light/dark): `Color` (equal), `PositiveColor` (greater) and `NegativeColor` (smaller).

In the app, the comparison is shown as a pill next to the value: green with ▲ and a plus sign when greater, red with ▼ when smaller, grey with — when equal. `Relative` is (value − comparison) / comparison.

!!! warning "Reference codes in metrics"
    In `Metric.DataType` and `Compare.DataType`, a reference is identified by its bare ID (`"12"`), which is also what the editor saves. `"Reference_12"` is accepted but silently compares against nothing.

The client renders these icon names:

`Search` · `Time` · `Calendar` · `Done` · `Visibility` · `Key` · `Lock` · `Power` · `Construction` · `Carpenter` · `Money` · `CurrencyExchange` · `PriceTag` · `ShoppingCart` · `Savings` · `AccountBalance` · `Balance` · `Business` · `Store` · `Portfolio` · `Calculate` · `CardMembership` · `AutoGraph` · `BubbleChart` · `LineChart` · `WaterfallChart` · `Numbers` · `Person` · `People` · `Handshake` · `Call` · `Mail` · `Comment` · `Campaign` · `ThumbUp` · `ThumbDown` · `SentimentVerySatisfied` · `SentimentSatisfied` · `SentimentNeutral` · `SentimentVeryDissatisfied` · `RocketLaunch` · `Car` · `Restaurant` · `Hotel` · `Dice` · `Camera` · `Computer` · `Rocket`

!!! warning "User-selected comparison"
    A `UserSelectDataType` comparison could not be made to work in testing: the metric shows *Obligatoriskt filter är inte uppfyllt* (required filter not satisfied). Use `DataType` with a fixed reference until this is resolved.

## Charts

Charts read from a dataset like tables do. Common settings are tooltips, value labels, a palette (the current theme, or user-defined colours) and a legend (hidden, or at the left, top, right or bottom).

Most charts have a **category axis**, which takes a dimension, a property, the value type or the data type, and a **value axis**, which takes a list of value types with linear or logarithmic scaling. Both axes can be moved to the opposite side, reversed, and given grid lines, tick marks and a label. An optional `Series` splits the data by a further dimension or property. Non-numeric value types can only be plotted through a numeric aggregation such as a count.

| Chart | Specific settings |
|---|---|
| Bar | `Layout` (`Vertical`, `Horizontal`), `Stacking` (`None`, `Stacked`) |
| Line | `Mode` (`Lines`, `Area`, `StackedArea`), `Curve` (`Natural`, `Linear`, `Step`), `ConnectEmptyValues`, `ShowMarkers` |
| Pie | `Values` (value types) and `Series` instead of axes |
| Waterfall | `LockedAtZeroCodes` (bars that start at zero, such as opening and closing balances), `Color`, `IncreaseColor`, `DecreaseColor` |
| Treemap | category axis for the boxes; value axis for box size |

When a chart shows several value types, use the value type dimension as category or series so the values can be told apart.

!!! note "Charts are a tenant feature"
    The tenant feature list includes Charts (*Diagram*). If the chart types are missing in the component type list, the feature may not be enabled for the tenant. See [Administration](administration.html).

## Related

- [Datasets](datasets.html)
- [Actions](actions.html)
- [Using apps](end-user.html)
- [App configuration (XML/JSON)](app-config.html)
- [Traceability](traceability.html)
