Layout Context

When creating widget layouts in the Widget Builder, you have access to various data objects and properties through Handlebars expressions. This guide explains what data is available and how to use it in your layout.

Available Context Objects

The following objects and properties are available in your widget layout:

settings

Contains the configuration values for your widget that were set by the editor when adding the widget to a page.

Usage:

{{settings.title}}
{{settings.color}}
{{settings.customProperty}}

Example: If you define a text field called "title" in your Widget Settings, it will be accessible as {{settings.title}}.

data

Contains the response data from your API request (if configured). This is the main data source for most dynamic widgets.

Usage:

{{#each data}}
  <div>{{this.name}}</div>
{{/each}}

page

Contains information about the current Staffbase page and environment where the widget is displayed. Only primitive values (strings, numbers, booleans) from the Staffbase Web Extensions are included.

Available properties:

Property	Type	Description	Example
page.appState	string	Current application state	"active"
page.browser	string	Browser engine identifier	"moz", "webkit"
page.branchDefaultLanguage	string	Default language for the Staffbase branch	"en_US"
page.branchId	string	Unique ID of the current Staffbase branch	"abc123def456"
page.compact	boolean	Whether compact mode is active	false
page.component	string	Component type	"client"
page.contentLanguage	string	Current content language	"en_US"
page.loading	boolean	Whether the page is still loading	false
page.mobile	boolean	Whether the user is on a mobile device	false
page.native	boolean	Whether the user is in the Staffbase native app	false
page.os	string	Operating system	"mac", "windows", "android"
page.platform	string	Platform type	"web", "mobile"
page.publicMode	boolean	Whether the page is in public/guest mode	false
page.spaceId	string	Unique ID of the current Staffbase space	"xyz789"
page.touch	boolean	Whether the device supports touch input	false
page.currentURL	string	Current page URL path	"/content/page/abc123"

Usage:

{{!-- Show different content for mobile vs desktop --}}
{{#if page.mobile}}
  <div class="mobile-layout">{{settings.title}}</div>
{{else}}
  <div class="desktop-layout">{{settings.title}}</div>
{{/if}}

{{!-- Detect native app --}}
{{#if page.native}}
  <p>You are viewing this in the Staffbase app.</p>
{{/if}}

user

Contains information about the current user viewing the widget. This data comes from the Staffbase SDK's user object.

Commonly used properties:

Property	Type	Description	Example
user.id	string	Unique user ID	"user-abc123"
user.firstName	string	User's first name	"Anna"
user.lastName	string	User's last name	"Schmidt"
user.fullName	string	Full display name	"Anna Schmidt"
user.email	string	User's email address	"anna@example.com"
user.locale	string	User's locale preference	"en_US"
user.role	string	User's Staffbase role	"editor", "admin"
user.department	string	User's department	"Engineering"
user.position	string	User's job position	"Frontend Developer"
user.location	string	User's location	"Berlin, Germany"

Additional properties:

Property	Type	Description
user.branchID	string	Branch ID the user belongs to
user.branchRole	string	User's role in the branch
user.phoneNumber	string	User's phone number
user.created	string	Account creation timestamp (ISO 8601)
user.updated	string	Last profile update timestamp (ISO 8601)
user.enabled	boolean	Whether the account is enabled
user.status	string	Account status (e.g., "activated")
user.externalID	string	External identifier (e.g., from SSO)
user.groupIDs	array	IDs of groups the user belongs to
user.profile.avatar.original.url	string	URL to the user's avatar image

Usage:

{{!-- Personalized greeting --}}
<h2>Hello, {{user.firstName}}!</h2>

{{!-- Show department-specific content --}}
{{#if (eq user.department "Engineering")}}
  <p>Check out the latest dev updates.</p>
{{/if}}

{{!-- Display user avatar --}}
{{#if user.profile.avatar.original.url}}
  <img src="{{user.profile.avatar.original.url}}" alt="{{user.fullName}}" />
{{/if}}

{{!-- Role-based visibility --}}
{{#if (eq user.role "admin")}}
  <a href="/admin">Admin Panel</a>
{{/if}}

note

The user object may be empty if the user is not authenticated (e.g., in public mode). Always use conditional checks like {{#if user.firstName}} to handle this gracefully.

widget

Contains metadata about the widget itself and contextual information.

Available properties:

Property	Type	Description
widget.baseId	string	Unique base identifier for the widget instance
widget.className	string	Generated CSS class name for styling isolation
widget.title	string	The widget's title
widget.updated	string	Last update timestamp of the widget
widget.contentLanguage	string	The content language for the widget (see Language Support)

Usage:

<div id="{{widget.baseId}}" class="{{widget.className}}">
  <h2>{{widget.title}}</h2>
  <p>Language: {{widget.contentLanguage}}</p>
</div>

variables

Contains custom variables that you define in the Widget Builder. These can be used to store state or dynamic values that change during user interaction.

Usage:

{{variables.current_date}}
{{variables.selectedItem}}

You can update variables using JavaScript functions like setVariable() in your template.

defaultLocale

Contains the default locale from Staffbase's contentLanguage setting (e.g., "en_US", "de_DE").

Usage:

<p>Default locale: {{defaultLocale}}</p>

browserLanguage

Contains the browser's language from navigator.language (e.g., "en", "de").

Usage:

<p>Browser language: {{browserLanguage}}</p>

browserTimezone

Contains the browser's timezone detected via the Intl API (e.g., "Europe/Berlin", "America/New_York").

Usage:

<p>Your timezone: {{browserTimezone}}</p>

baseUrl

Contains the Staffbase instance URL for your organization (e.g., "https://yourcompany.staffbase.com"). This is useful for linking to Staffbase pages, making API calls to your Staffbase instance, or building URLs that work correctly within the app.

Common use cases:

• Linking to Staffbase pages: Build links that open correctly inside the Staffbase app.

  <a href="{{baseUrl}}/content/pages/{{settings.pageId}}">Open Page</a>

• Making API calls to Staffbase: Use as the base for API requests to your Staffbase instance.

  GET {{baseUrl}}/api/some-endpoint
  Authorization: Bearer {{staffbaseAccessToken}}

• Fixing in-app links: When relative or hardcoded links don't work correctly inside the Staffbase app, use baseUrl to construct absolute URLs.

  {{! Instead of a relative link that may break }}
  <a href="{{baseUrl}}/profile/{{user.id}}">View Profile</a>

Language Support

The Widget Builder automatically detects and provides the content language through widget.contentLanguage. This value follows a priority chain:

1. contentLanguage from Staffbase SDK -

Usage example:

{{#if (eq widget.contentLanguage "de")}}
  <p>Willkommen!</p>
{{else}}
  <p>Welcome!</p>
{{/if}}

Using with datetime helper:

{{datetime with_locale=widget.contentLanguage output_format="LLLL"}}

This will format dates according to the user's language preference.

Timezone Support

The Widget Builder provides timezone information through browserTimezone. The timezone is automatically detected from the user's browser via the Intl API (e.g., "Europe/Berlin", "America/New_York"). If detection fails, it falls back to "Europe/Berlin".

Usage example:

<p>Your timezone: {{browserTimezone}}</p>

Using with datetime helper:

{{datetime with_timezone=browserTimezone output_format="LLLL"}}

This will display times in the user's local timezone.

Combining Language and Timezone

You can combine language and timezone for truly localized experiences:

<div class="date-display">
  {{datetime
    with_locale=widget.contentLanguage
    with_timezone=browserTimezone
    output_format="LLLL"
  }}
</div>

This will display the date and time in the user's language and timezone.

Example: Localized Greeting

Here's a complete example showing how to use language and timezone together:

<div class="greeting">
  {{#if (eq widget.contentLanguage "de")}}
    <h2>Guten
      {{#if (gt (datetime output_format="HH") 12)}}Abend{{else}}Tag{{/if}}!</h2>
  {{else if (eq widget.contentLanguage "fr")}}
    <h2>Bon{{#if
        (gt (datetime output_format="HH") 12)
      }}soir{{else}}jour{{/if}}!</h2>
  {{else}}
    <h2>Good
      {{#if
        (gt (datetime output_format="HH") 12)
      }}Evening{{else}}Day{{/if}}!</h2>
  {{/if}}

  <p>
    Current time in your location:
    {{datetime
      with_timezone=browserTimezone
      with_locale=widget.contentLanguage
      output_format="LLL"
    }}
  </p>
</div>

Best Practices

1. Always provide fallbacks: Use conditional helpers to provide content in multiple languages or default values
2. Test with different locales: Preview your widget with different language and timezone settings
3. Use semantic formatting: Leverage the datetime helper's locale-aware formatting instead of hardcoding date formats
4. Consider user preferences: The automatic language/timezone detection respects user settings, so design widgets that adapt gracefully

Related Documentation

• Handlebars Helpers - Learn about all available helpers
• DateTime Helper - Detailed documentation on date/time formatting with locale and timezone support
• Customize a Built-in Widget - See context objects in action