Skip to main content

IStoryline interface

📖 Description​

Interface that describes the immutable representation of the storyline.

📃 Type declaration​

interface IStoryline {
  moments: Moment[];Readonly
  pages: {
    number: number;
    active: boolean;
    activate: () => void;
  }[];Readonly
  presentMoment: Moment | undefined;Readonly
  presentSection: Section | undefined;Readonly
  presentNodes: IObservableNode[];Readonly
  all: (IObservableNode & {
    bookmark: IBookmark;
  })[];Readonly
  nodes: IObservableNode[];Readonly
  bookmarks: IBookmark[];Readonly
  slides: ISlide[];Readonly
  isEvaluating: boolean;Readonly
  isEmpty: boolean;Readonly
  isAtStart: boolean;Readonly
  isAtHead: boolean;Readonly
  isAtFinish: boolean;Readonly
  isFinishable: boolean;Readonly
  isFinishing: boolean;Readonly
  isFinished: boolean;Readonly
  isPausing: boolean;Readonly
  isPaused: boolean;Readonly
  hasDataCollected: boolean;Readonly
  isFailed: boolean;Readonly
  isPassed: boolean;Readonly
  mode: "paginated" | "continuous" | "progressive" | "ahead";Readonly
  direction: "forward" | "backward";Readonly
  count: number;Readonly
  enumerators: number;Readonly
  percentage: number;Readonly
  stepForward: () => boolean;Function
  stepBackward: () => boolean;Function
  stepToStart: () => boolean;Function
  stepToHead: () => boolean;Function
  stepToPage: (page: number) => boolean;Function
  finish: () => Promise<void> | false;Function
  map: <R>(fn: (moment: Moment, index: number) => R) => R[];Function
}
🖱ī¸ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

🗃ī¸ Properties​

🏷ī¸ all​

Retrieves all observable nodes of the active moment (so the nodes of all moments in the moments collection) with their corresponding bookmark.

Type​

(IObservableNode & { bookmark: IBookmark })[]

🏷ī¸ bookmarks​

Retrieves the bookmarks in the storyline.

Type​

IBookmark[]

🏷ī¸ count​

Retrieves the total number of observable nodes in the storyline.

Type​

number

🏷ī¸ direction​

Retrieves the most recent step direction of the storyline.

Type​

"forward" | "backward"

🏷ī¸ enumerators​

Retrieves the total number of observable nodes that have an enumerator value.

Type​

number

🏷ī¸ hasDataCollected​

Retrieves if the storyline has any data collected.

Type​

boolean

🏷ī¸ isAtFinish​

Retrieves if the present moment is at the finish of the storyline.

Type​

boolean

🏷ī¸ isAtHead​

Retrieves if the present moment is at the head of the storyline.

Type​

boolean

🏷ī¸ isAtStart​

Retrieves if the present moment is at the beginning of the storyline.

Type​

boolean

🏷ī¸ isChanged​

Retrieves if the storyline has changed since the last call of this prop.

Type​

boolean

🏷ī¸ isEmpty​

Retrieves if the storyline is empty (has no observable nodes, basically an empty form).

Type​

boolean

🏷ī¸ isEvaluating​

Retrieves if the storyline is evaluating.

Type​

boolean

🏷ī¸ isFailed​

Retrieves if the validation of the storyline failed.

Type​

boolean

🏷ī¸ isFinishable​

Retrieves if the storyline is finishable using the finish method.

Type​

boolean

🏷ī¸ isFinished​

Retrieves if the storyline is finished.

Type​

boolean

🏷ī¸ isFinishing​

Retrieves if the storyline is finishing.

Type​

boolean

🏷ī¸ isPassed​

Retrieves if the validation of the storyline passed.

Type​

boolean

🏷ī¸ isPaused​

Retrieves if the storyline is paused.

Type​

boolean

🏷ī¸ isPausing​

Retrieves if the storyline is pausing.

Type​

boolean

🏷ī¸ mode​

Retrieves the mode of operation. It can be one of the following values:

  • paginated: Render each section on a separate page (this is the default behavior);
  • continuous: Render all completed (past) sections and the current (present) section on a page;
  • progressive: Render all completed (past), current (present) and future sections on a page till the point where one of the sections fails validation;
  • ahead: Render all completed (past), current (present) and future sections on a page, regardless of the section's validation result.

Type​

"paginated" | "continuous" | "progressive" | "ahead"

🏷ī¸ moments​

Retrieves the moments that are in the storyline. There are three types of moments:

  • Past moments;
  • The present moment;
  • Future moments.
info

The best way to understand these moment types is to visualize a paginated form runner, where the questions (node blocks) are presented on a page. Each section is a page. All pages that are already answered by the respondent are past moments. The current page the respondent is on is the present moment. And all the pages the respondent still needs to answer are future moments.

Type​

Moment[]

🏷ī¸ nodes​

Retrieves the observable nodes of the active moment (so the nodes of all moments in the moments collection).

Type​

IObservableNode[]

🏷ī¸ pages​

Retrieves the collection of pages.

caution

Only available for runners in paginated mode.

Type​

{
  /* Contains the page number. */
  number: number;

  /* Contains if the page is active. */
  active: boolean;

  /* Activates the page. */
  activate: () => void;
}[]

🏷ī¸ percentage​

Retrieves the progress percentage of the storyline.

tip

Can be used to show a progressbar that indicates the progress of the form.

Type​

number

🏷ī¸ presentMoment​

Retrieves the present moment.

Type​

Moment | undefined

🏷ī¸ presentNodes​

Retrieves the observable nodes of the present moment.

Type​

IObservableNode[]

🏷ī¸ presentSection​

Retrieves the section of the present moment.

Type​

Section | undefined

🏷ī¸ slides​

Retrieves the slides in the storyline.

Type​

ISlide[]

â–ļī¸ Functions​

🔧 finish​

Finish the storyline when it is at the end.

caution

You can only finish a form when it is finishable.

Signature​

finish(): Promise<void>

Return value​

Returns a Promise that resolves when the instance was finished. The finish operation can be asynchronous. For example, when the form submits data to an endpoint. During the finish operation you could show a visual indicator to the respondent to indicate the form is submitting. When the promise resolves or rejects, the finish operation ends. When the promise rejects, the form remains active and the respondent should be able to try to finish the form again.

🔧 map​

Maps moments of the storyline to a certain type.

Signature​

map<R>(fn: (moment: Moment, index: number) => R): R[]

Parameters​

NameTypeOptionalDescription
fn(moment: Moment, index: number) => RNoSpecifies the map function.

Return value​

Returns the resulting array of the map operation.

🔧 stepBackward​

Step backward in the storyline.

Signature​

stepBackward(): boolean

Return value​

Returns true if the step succeeded.

🔧 stepForward​

Step forward in the storyline.

Signature​

stepForward(): boolean

Return value​

Returns true if the step succeeded.

🔧 stepToHead​

Step to the head of the storyline.

Signature​

stepToHead(): boolean

Return value​

Returns true if the step succeeded.

🔧 stepToPage​

Steps to a page.

caution

Only available for runners in paginated mode.

Signature​

stepToPage(page: number): boolean

Parameters​

NameTypeOptionalDescription
pagenumberNoSpecifies the page to step to.

Return value​

Returns true if the step succeeded.

🔧 stepToStart​

Step to the start of the storyline.

Signature​

stepToStart(): boolean

Return value​

Returns true if the step succeeded.