Skip to main content

Storyline class

📖 Description​

The Storyline class helps to render runners by supplying all the required properties and methods for rendering the form.

🗃️ Fields​

🏷️ 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 })[]

🏷️ activePage​

Retrieves the active page.

caution

Only available for runners in paginated mode.

Type​

{
  /* Contains the page number. */
  number: number;
} | undefined

🏷️ bookmarks​

Retrieves the bookmarks in the storyline.

Type​

IBookmark[]

🏷️ checksum​

Retrieves the checksum of the storyline.

Type​

string | undefined

🏷️ 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

🏷️ epilogue​

Retrieves the optional epilogue for the form. This epilogue can be used by runners (that support it) to show a closing message when the form is completed.

Type​

IEpilogue

🏷️ hasDataCollected​

Retrieves if the storyline has any data collected.

Type​

boolean

🏷️ immutable​

Retrieves an immutable representation of the storyline.

Type​

IStoryline

🏷️ instance​

Retrieves the instance of the storyline.

Type​

Instance

🏷️ 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 moments (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

🏷️ prologue​

Retrieves the optional prologue for the form. This prologue can be used by runners (that support it) to show a welcome message before starting the actual form.

Type​

IPrologue

🏷️ slides​

Retrieves the slides in the storyline.

Type​

ISlide[]

▶️ Methods​

🔧 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.

🔧 getKeyByNodeId​

Find the node that belongs to the supplied node identifier.

Signature​

getKeyByNodeId(id: string): IObservableNode | undefined

Parameters​

NameTypeOptionalDescription
idstringNoSpecifies the node identifier.

Return value​

Returns the IObservableNode object or undefined if the node was not found.

🔧 getNodeByKey​

Find the node that belongs to the supplied key.

Signature​

getNodeByKey(key: string): IObservableNode | undefined

Parameters​

NameTypeOptionalDescription
keystringNoSpecifies the node key.

Return value​

Returns the IObservableNode object or undefined if the node was not found.

🔧 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.