Skip to main content

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 where the widget is displayed.

Available properties:

  • Various page-related properties from the Staffbase Web Extensions (see Staffbase documentation)

Usage:

{{page.propertyName}}

user​

Contains information about the current user viewing the widget.

Available properties:

  • User profile information from Staffbase
  • Properties depend on the Staffbase user object structure

Usage:

{{user.firstName}}
{{user.email}}

widget​

Contains metadata about the widget itself and contextual information.

Available properties:

PropertyTypeDescription
widget.baseIdstringUnique base identifier for the widget instance
widget.classNamestringGenerated CSS class name for styling isolation
widget.titlestringThe widget's title
widget.updatedstringLast update timestamp of the widget
widget.contentLanguagestringThe 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>

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