Whisper Updates

Whisper Basics

Whispers are the main way that your Loop conveys and receives information from your user. They also serve as the primary UI for your Loop. As such, the Whisper Aptitude will more than likely one of your most commonly used resources. As an initial example, let's say that we want to display to the user a simple message with a link. To achieve this, we would use both the Markdown and Link component like this:

import { whisper } from '@oliveai/ldk';

const whisperConfig = {
  label: 'External Link Test',
  onClose: () => {
    // Does nothing
  },
  components: [
    {
      body: 'Check out this documentation!',
      type: WhisperComponentType.Markdown,
    },
    {
      href: 'https://www.oliveai.dev',
      style: Urgency.None,
      text: 'https://www.oliveai.dev',
      textAlign: TextAlign.Left,
      type: WhisperComponentType.Link,
    },
  ],
};

whisper.create(whisperConfig);

Using this will generate a Whisper that looks like this:

When written this way, the contents of a Whisper are static, and unable to be changed. But, there are ways to define more dynamic content.

Changing the content of a Whisper

Let's say that you would like the content of your Whisper to be more dynamic within the Whisper, like wanting to add or remove form fields from a whisper based on the answer to another field, or display a loading message and then results from making a network call. When needing to create a Whisper like this, you will need to use the update() function found on the Whisper object produced by the Whisper Aptitude's create() method. Take the previous example. There are two modifications we would have to make to create an updatable Whisper, as well as something extra to keep in mind.

1. Add the key property to every component that will be receive updates. This property is used by Olive Helps to keep track of the component, and is a string and must be unique within the Whisper.

2. Use the callback function provided by the create() method, and then provide new values for the components that you want to change.

3. The Whisper needs to remain open, so if it is closed, the update will not appear / occur.

import { whisper } from '@oliveai/ldk';

const whisperConfig = {
  label: 'External Link Test',
  onClose: () => {
    // Does nothing
  },
  components: [
    {
      body: 'Check out this documentation!',
      key: 'id1',
      type: WhisperComponentType.Markdown,
    },
    {
      href: 'https://www.oliveai.dev',
      key: 'id2',
      style: Urgency.None,
      text: 'https://www.oliveai.dev',
      textAlign: TextAlign.Left,
      type: WhisperComponentType.Link,
    },
  ],
};

whisper.create(whisperConfig).then((whisperObj) => {
  // ...wait for some trigger to occur
  whisperObj.update({
    label: 'Link To Documentation',
    components: [
      {
        body: 'Check out this documentation!',
        key: 'id1',
        type: WhisperComponentType.Markdown,
      },
      {
        href: 'https://www.oliveai.dev',
        key: 'id2',
        style: Urgency.Error,
        text: 'https://www.oliveai.dev',
        textAlign: TextAlign.Left,
        type: WhisperComponentType.Link,
      },
    ]
  });
});

This Whisper created at first will look like the previous screenshot. After two seconds, the Whisper looks like this:

Success! Notice that the link now has a red outline, as well as the title of the Whisper has changed. But, as you might be able to see, using the methods described above to facilitate an update to a Whisper could quickly get complicated. To make this easier, Whispers can be described using a JSX format.