UserInterface

Login

When an application calls the Login method of the SessionKit, a series of events is triggered against an implemented UserInterface and its methods.

Listed below are all of the methods this sequence will call, in chronological order:

onLogin: () => Promise<void>

login(context: LoginContext): Promise<UserInterfaceLoginResponse>

onLoginComplete: () => Promise<void>

Transact

When an application calls the Transact method on a Session, a series of events is triggered against an implemented UserInterface and its methods.

Listed below are all of the methods this sequence will call in chronological order:

onTransact: () => Promise<void>

onSign: () => Promise<void>

onSignComplete: () => Promise<void>

onBroadcast: () => Promise<void>

onBroadcastComplete: () => Promise<void>

onTransactComplete: () => Promise<void>

Rendering

It is the responsibility of the UserInterface to implement the prompt call, interpret its request, and render the appropriate elements to the end user.

The arguments passed to the UserInterface that are accepted by the prompt call will match:

interface PromptArgs {
  title: string
  body?: string
  elements: PromptElement[]
}

It’s up to the renderer to decide the best use of this information, but in general the elements are meant for the following purposes:

• The title is provided as a header for the display that will be rendered to the user
• A body may optionally be defined with a text-based description of what you are prompting for
• The elements array consists of one or more PromptElement instances, which instruct the UserInterface on how to present this prompt to the user

The elements array is populated by one or more PromptElement objects that make up the desired layout presented to the user.

interface PromptElement {
  type:
    | "accept"
    | "asset"
    | "button"
    | "close"
    | "countdown"
    | "link"
    | "qr"
    | "textarea"
  label?: string
  data?: unknown
}

These should be pre-built elements internal to the UserInterface that can accommodate for certain types of interactive events.

• The type field must match one of the strings included. Each string represents a different type of prompt.
• A label for the element, typically providing context to the element.
• A data object for the element, which is specific to the element itself and how it’s rendered.

Responding

The prompt call is asynchronous and the SessionKit or Plugin will await a response from the UserInterface before moving on. Based on how the user responds to the rendered elements, the UserInterface is responsible for responding to the promise by:

• Resolving the promise (which acts as an “accept and move on” response)
• Rejecting the promise (which acts as “reject and move on” response)
• Canceling the promise (which aborts the entire login/transact request)

This response contains no specific data but instead offers the three above logic paths using the CancelablePromise pattern.

status

status: (message: string) => void

The status method is a generic string-based system on the user interface which allows any process or plugin to provide basic messages directly to the user interface. These can be included in the UI to update the user about details of what process is occurring, or for the developer to output as logs for debugging.

translate

translate: UserInterfaceTranslateFunction

This method must follow the UserInterfaceTranslateFunction interface and utilize whichever technologies are best suited to the task of facilitating content translation. The WebRenderer serves as an example of how this can be done, as it translates Wharf’s expectation of a translation string into the i18n library it’s using.

export type UserInterfaceTranslateFunction = (
  key: string,
  options?: UserInterfaceTranslateOptions,
  namespace?: string
) => string

getTranslate

getTranslate: (namespace?: string) => UserInterfaceTranslateFunction

This method defines how Wharf or Plugins should retrieve an instance of the UserInterfaceTranslateFunction of a given namespace. Plugins specifically will make use of this call to access and provide translations for their content within a given user interface.

By default the AbstractUserInterface class will define this method for use in plugins.

addTranslations

addTranslations: (translations: LocaleDefinitions) => void

The final translation responsibility of the UserInterface is the ability for Wharf or a plugin to be able to dynamically add translation strings into the user interface. This method is added so that the SessionKit and various Plugins can programmatically add translation strings to the dictionary.

The WebRenderer again serves as an example of how this can be done.

onError

onError: (error: Error) => Promise<void>

A UserInterface must define an onError method to define how the user interface handles errors thrown by the SessionKit. These can be displayed directly to users, interpreted and handled based on their content, and logged externally to help troubleshoot issues.