Style guide API

The Seamly style guide is a standalone entry point available in the Web UI package. It uses the Seamly rendering engine to render static views based on pre-defined static states. This allows for easy navigation and discovery of the various vew permutation available in Seamly to facilitate easier styling of Seamly itself as well as custom implementations.

The style guide has been created in such a way that it can be easily incorporated in Seamly custom implementations. This document explains how the style guide can be incorporated in such an implementation and how the API functions.

Setting up the style guide

The style guide applications uses a similar interface to the web UI.

Firstly the application needs to be started:

import initStyleGuide from '@seamly/web-ui/src/javascripts/style_guide'

import 'custom-styles.scss'
import '@seamly/web-ui/src/stylesheets/style-guide.scss'

initStyleGuide(
  {
    //Standard Seamly config values
  },
  {
    showLayoutModes: ['inline', 'window'],
  },
)

Initialising takes two configuration objects. The first object can be an replica of the normal Seamly configuration object. However, only a subset of the values will have any effect on how the style guide renders. With the exception of a small number of keys, which will later be discussed in the section on initializing the instance, it is usually better to drive them from the static states.

Also note that the standard style guide styles need to be loaded after loading the custom styles for the implementation. The styles don't have any impact on the display of the UI itself, but ensure that the menu's are displayed correctly.

Configuration

A number of configuration options exists:

showLayoutModes

All layout modes are not always used in every implementation. To enable focussing on those that are used, this setting allows selection of the layout modes to render.

The option accepts an array with the layout modes to render.

showLayoutModes: ['inline', 'window']

If not provided, it will default to ['inline', 'window'].

customComponents

Providing custom implementations for the main Seamly view should be done using this setting, instead of the normal setting in the Seamly config.

It accepts an optional component per layout mode, thereby giving the user the flexibility to render all layout modes in one style guide instance even when difference custom view components are used for each mode.

The setting accepts an object with a property for each of the known layout modes: 'inline' and 'window'.

customComponents: {
    inline: <InlineViewComponent>,
    window: <WindowViewComponent>
}

When not specified for any or all of the layout modes, the standard internal view of Seamly will be used for any layout mode without a custom view.

customMessageEventBodies

Seamly allows for custom messages and the injection of custom view components to render those messages.

In order to support this the style guide application state should be extendable from the implementation itself.

This property accepts an array of custom message event body data objects that take the form of:

{
key: 'uniqueStringKey',
description: 'Optional item description',
headingText: 'Heading text of item in the style guide',
body: {
  data: {
   // Custom data values for the custom message
  },
  text: 'Required text representation of the component',
  type: 'messageType',
},
},

The style guide will generate extra states for each of the custom message bodies and will add them to the menu.

stateUpdateCallback

Whenever a new view is selected, that state is selected from the global library object.

This setting accepts a function that will have that state portion injected which can then be modified and returned to alter the displayed values in the style guide. It is then possible to operate on a smaller state object when modifying the content of already defined static state.

If provided, this function HAS to return a valid partial state object or the application will probably fail.

stateUpdateCallback: state => {
    const customState = doSomethingWithState(state)

    return customState
}

Initializing the style guide instance

Once the application has been started, it can be initialized with a similar interface to that of the Web UI.

This is done by pushing an init action to the seamlyStyleGuide API on the window object:

window.seamlyStyleGuide = window.seamlyStyleGuide || []

window.seamlyStyleGuide.push({
action: 'init',
args: {
    parentElement: <HTMLElement>,
    namespace: 'style-guide',
},
})

Note that we once again need to pass in an HTML element to render the style guide into, as well as the namespace to use. The latter can be important for styling purposes.

translations

The standard translations can be overridden at init time:

window.seamlyStyleGuide = window.seamlyStyleGuide || []

window.seamlyStyleGuide.push({
action: 'init',
args: {
    parentElement: <HTMLElement>,
    namespace: 'style-guide',
    translations: <TranslationsObject>
},
})

The translations object needs to exactly replicate the structure of one of the existing standard language files in the Web UI.

showLayoutModes

The showLayoutModes setting can be overridden during init.

This allows finer control over what is displayed, without the need to create different versions of the app start JavaScript.

When setting this, a second object needs to be provided to the init call:

window.seamlyStyleGuide.push({
action: 'init',
args: [{
        parentElement: <HTMLElement>,
        namespace: 'style-guide',
    },
    {
        showLayoutModes: ['inline']
    }]
})