Displays are essential to every component as they specify the "container" in which the component will be rendered. This could be a modal, popover, inline, or any other type of container.

In addition to specifying the container, displays also control the visibility of the component. For example, a modal display will render the component in a modal container and prevent other parts of the page from being interacted with until the modal is dismissed. Different displays can be used in different contexts to provide the best user experience.

Displays are distinct from Elements and Layouts because they do not inherit from the Element class, but rather from the LitElement class, thereby becoming web components themselves.

As such, they have a slightly different implementation than Elements and Layouts. Check out our displays that are available in our open-source framework: https://bit.cloud/unless/component-library/display/bar.

Import

import {Display} from '@unless/component-library.display.display'

Abstract methods

When creating a new display, these methods must be implemented.

Static methods

While TypeScript does not formally implement abstract static, these methods must be implemented, otherwise, the component will not render correctly.

MethodArgumentsReturn TypeDescription
defaultSettingsnoneanyThis static method should return the type any due to a TypeScript bug in order for correct compilation.
copyWith...settingsChanges: TSetting[]anyThis method is used during compilation with the compose function to generate the settings.

Static properties

In addition to ‘abstract’ static methods that must be implemented, the static property of type must also be implemented.

PropertyTypeDescription
typeDisplayTypeThis property is utilised by both the Unless script to ensure that the same component type is not instantiated twice on the page, and by the compiler to transmit display type information to the layouts.

Instance methods

These methods should be implemented when creating a new display. Some of these methods are marked as protected and should not be called outside of the display class itself.

MethodArgumentsReturn TypeDescription
getDisplaynoneTemplateResultThis method should return the display's main template, which will be rendered by the render method.
getLayoutnoneTemplateResultThis method should return the layout's main template or an array of templates to be rendered. One should not typically have to override this method.
addRefreshCallbacks...callback: ((content: TSettings, settings: OtherSettings) => void)[]voidThis method should be used to add callbacks that will be triggered when the component's settings are refreshed.

Instance properties

These properties are available in display instances.

PropertyTypeDescription
displayTypeDisplayTypeThe display type of the component.
scriptNamestringThe name of the script that the component is being used in.
contentTSettingsThe content settings for the display.
settingsOtherSettingsThe other settings for the display.
themestringThe theme string for the display.
personalizationIdstringThe personalization ID for the display.
customCssCustomCssThe custom CSS for the display.
uiSizeSizeThe UI size for the display.
layoutSizeSizeThe layout size for the display.

Lifecycle methods

These methods are automatically called during the display's lifecycle.

MethodArgumentsReturn TypeDescription
firstUpdated_changedProperties?: PropertyValueMap<any>voidCalled after the display has been rendered for the first time. Use this method to add event listeners, initialise properties, or perform other setup tasks.
updated_changedProperties?: PropertyValueMap<any>voidCalled after the display has been updated. Use this method to perform tasks that should occur after the component has been updated.
disconnectedCallbacknonevoidCalled when the display is disconnected from the DOM. Use this method to remove event listeners or perform other cleanup tasks.

Constructor

This constructor should be called when creating a new display instance.

ConstructorArgumentsDescription
Displaycontent: TSettings, settings: OtherSettingsInitialises a new display instance with the given content and settings.

Display settings

Display settings are crucial in any component library, as they allow users to customise the appearance and behavior of display components to fit their specific needs. In this section, we will explain what display settings are, how to use them, and some best practices for implementing them.

What are display settings?

Display settings are options that can be configured for a display component within a component library. They allow users to modify the appearance and behavior of the display component without changing its underlying code. Examples of display settings include CSS selectors, positions, background colours, and shadows. By providing users with display settings, you can make your display components more flexible and adaptable to different use cases.

How to use display settings

To use display settings in your components, you first need to define them by creating a settings model that extends the DisplaySettings class.

Here's an example of how to define a display settings model:

import { 
    BooleanSelectSetting, 
    CssSelectorSetting, 
    SelectSetting, 
    Setting 
} from '@unless/component-library.utils.types'
import { DisplaySettings } from '@unless/component-library.display.display'

interface InlineSetting extends Setting {
  selector: CssSelectorSetting
  position: SelectSetting
  shadow: SelectSetting
  margin: BooleanSelectSetting
}

export type InlineSettings = DisplaySettings<'inline', InlineSetting>

Once the display settings model is defined, you need to create the default settings file.

Here's an example of how to create the default settings file:

/* esbuild-ignore */

import { InlineSettings } from './settings-model'
import { 
    backgroundColorSetting, 
    destroyUponNavigateSettings, 
    stepperSettings 
} from '@unless/component-library.display.display'
import { BooleanOptions } from '@unless/component-library.utils.types'

const settings: InlineSettings = {
  inline: {
    selector: {
      label: 'css selector',
      type: 'cssSelector',
      value: '#placeholder',
      placeholder: 'Enter a valid CSS selector',
      helpText: 
                'Enter a CSS selector after which the custom inline add-on will be inserted.',
      fallback: undefined as string | undefined,
    },
    position: {
      label: 'position',
      type: 'select',
      options: ['before', 'after', 'replace', 'replace-child'],
      value: 'after',
      placeholder: 'after',
      helpText: 
                'Choose where to insert the inline add-on. Either before, after or replace the selected element.',
    },
    backgroundColor: { ...backgroundColorSetting, expert: true },
    shadow: {
      expert: true,
      label: 'shadow',
      type: 'select',
      options: ['none', 'small', 'regular', 'large'],
      value: 'none',
      placeholder: 'none',
      helpText: 'Show a shadow on the inline component.',
    },
    destroyUponNavigate: destroyUponNavigateSettings,
    margin: {
      expert: true,
      label: 'margin',
      type: 'select',
      options: Object.values(BooleanOptions),
      value: BooleanOptions.No,
      placeholder: BooleanOptions.No,
      helpText: 'Show a margin on the inline component.',
    },
  },
  stepper: stepperSettings,
}

export default settings

Best practices for implementing display settings

  1. Use DisplaySettings: Ensure that your display settings model uses the DisplaySettings type. This provides a consistent structure for display settings across your component library.
  2. Provide default values: Always provide default values for your display settings. This ensures that your display component works out of the box and allows users to customise only the settings they need.
  3. Use the esbuild-ignore comment: Include the /* esbuild-ignore */ comment at the beginning of your settings file to

What’s Next