---
title: User Settings for Calendar Views
sources: [ai-wiki/wiki/calendar-control.md, src/User/BO/BoUser/Mv1/BoUser.GetCallCalendarSettings.bl.js]
last_updated: 2026-04-27
---

# User Settings for Calendar Views

Calendar behavior can be configured per-user via `BoUserSettings`. Settings are loaded at
process startup and passed to the `CalendarControl` via a flat key/value LO.

---

## Available Settings

| Setting key                      | Type                  | Purpose                                              |
| -------------------------------- | --------------------- | ---------------------------------------------------- |
| `ClbCalendarInitialViewMobility` | enum (Weekly / Daily) | Default view on open                                 |
| `ClbCalendarInitialTime`         | DomTime               | Scroll-to time on open                               |
| `ClbCalendarDefaultCallStatus`   | enum                  | Default status for new calendar items                |
| `ClbAgendaDisplayTimeMobility`   | DomBool               | Show time labels on items                            |
| `ClbShowCalendarWeekMobility`    | DomBool               | Show ISO week number in header                       |
| `DisplayWeekend`                 | DomBool               | Show Saturday/Sunday columns                         |
| `FirstDayOfWeek`                 | String                | First column: Monday or Sunday (from SysSettings LU) |

Real anchor: `src/User/BO/BoUser/Mv1/BoUser.GetCallCalendarSettings.bl.js`

---

## Loading Settings in a Process

Settings are loaded in EntryActions using:

```xml
<Action name="AssignUserSettings" actionType="LOGIC"
        call="ApplicationContext::User.getCallCalendarSettings">
  <Return name="ProcessContext::userSettings" />
</Action>
```

This populates `ProcessContext::userSettings` with a `LoUserSetting` whose items each have
`name` and `value` properties.

The CalendarControl then reads them automatically when bound:

```xml
<Settings dataSource="ProcessContext::userSettings" keyAttribute="name" valueAttribute="value" />
```

Real anchor: `src/Visit/PR/Visit_Calendar/Visit_CalendarProcess.processflow.xml`

---

## Reading a Single Setting in BL

If you only need one setting (e.g., to display the ISO week header), call it directly from
the process:

```xml
<Action name="InitializeCWWithUserSetting" actionType="LOGIC"
        call="ApplicationContext::User.boUserSettings.getClbShowCalendarWeekMobility">
  <Return name="ProcessContext::DisplayCalendarWeek" />
</Action>
```

Available getters on `boUserSettings`:

-   `getClbCalendarInitialViewMobility()`
-   `getClbCalendarInitialTime()`
-   `getClbShowCalendarWeekMobility()`
-   `getDisplayWeekend()`
-   `getClbAgendaDisplayTimeMobility()`
-   `getClbDisplayTrafficInMapMobility()` (map-paired only)
-   `getClbDisplayRouteInMapMobility()` (map-paired only)

---

## Persisting the User's Chosen View

When the user switches between Weekly and Daily view, persist the choice so the calendar
opens in the same view next session.

Pattern:

1. Add a `currentAgendaView` declaration in the process (`type="String"`)
2. On view-switch events, LOGIC `Utils.identity` → `ProcessContext::currentAgendaView`
3. Use `DECISION` on `currentAgendaView` to route to the correct VIEW action on next open
4. Write the choice back to `BoUserSettings` via a BL method if persistence beyond the
   current session is needed

Zoom/pan state (scroll position within a week) is session-only — the framework does not
persist it and there is no API to do so.

---

## When to Skip User Settings

Omit user-settings integration when:

-   The calendar always opens in a fixed view (no user preference needed)
-   It is an embedded sub-view inside a larger process (not a standalone calendar screen)
-   The entity is not Visit/Call — most other entities do not have pre-built settings

In that case use `<Settings />` (empty element — still required by the schema):

```xml
<Settings />
```

---

## Cross-References

-   [[business-logic]] — `BoUser.getCallCalendarSettings.bl.js` implementation
-   [[business-objects]] — `BoUserSettings` BO structure
-   `ai-wiki/wiki/calendar-control.md` — full settings-key table