Skip to main content

HeadlessBlock class

📖 Description​

The HeadlessBlock class is used to implement a headless Node block. Headless blocks are a special kind of blocks that can perform actions. Those blocks are invisible and not rendered to the UI. For example, there is a calculator block to perform advanced calculations. But you could also develop a headless block to communicate with external services such as APIs.

tip

You can create custom headless blocks for Tripetto.

🎀 Applicable decorators​

The following decorators can be applied in this class:

Class decorators ℹī¸â€‹

Method decorators ℹī¸â€‹

🗃ī¸ Fields​

🏷ī¸ context​

Reference to the context of the block.

Type​

Context

🏷ī¸ isFailed​

Retrieves if the validation of the block failed.

Type​

boolean

🏷ī¸ isPassed​

Retrieves if the validation of the block passed.

Type​

boolean

🏷ī¸ node​

Retrieves the node props from the form definition.

Type​

INode

🏷ī¸ props​

Retrieves the block properties from the form definition.

Type​

{
  /* Contains the node block type identifier. */
  type: string;

  /* Contains the version of the block. */
  version: string;
}
info

Besides the listed properties, node blocks may store additional properties in the props object.

🏷ī¸ type​

Retrieves the block type object.

Type​

{
  /* Contains the block type identifier. */
  identifier: string;
}

🏷ī¸ validation​

Retrieves the validation state of the block. It can be one of the following values:

  • unknown: There is no validation state available yet;
  • pass: Validation succeeded;
  • fail: Validation failed.

Type​

"unknown" | "pass" | "fail"

🏷ī¸ view​

Retrieves the current view mode of the runner. It can be one of the following values:

  • live: Normal run mode of the form;
  • test: Runs the form like a real one without being able to submit data;
  • preview: Shows all elements in the form by skipping all logic.

Type​

"live" | "test" | "preview"

â–ļī¸ Methods​

🔧 clear​

Clears all data values of a block.

Signature​

clear(): void

🔧 do​

Abstract method

This method is abstract and needs implementation in the headless block implementation.

Implements the operation for the block. This function is invoked when the headless block should perform its work. This work can be executed synchronously or asynchronously. To implement asynchronous behavior, simply return the await parameter as return value of the method. Then call await.done when the asynchronous operation is done (see example below).

Signature​

do(await: Await): Await | void

Parameters​

NameTypeOptionalDescription
awaitAwaitYesSpecifies the Await instance for the asynchronous operation.

Return value​

Returns nothing for synchronous operations (void) or the await parameter to indicate asynchronous operation.

Example​

import { tripetto, Await, HeadlessBlock } from "@tripetto/runner";

// Synchronous operation example
@tripetto({
  type: "headless",
  identifier: "example-sync",
})
class ExampleSync extends HeadlessBlock {
  do(): void {
    // Let's do something here
  }
}

// Asynchronous operation example
@tripetto({
  type: "headless",
  identifier: "example-async",
})
class ExampleAsync extends HeadlessBlock {
  do(await: Await): Await {
    // Let's do something asynchronous here
    setTimeout(() => {
      await.done();
    }, 1000);

    return await;
  }
}

🔧 immutableValueOf​

Retrieves the immutable (write-protected) value for the supplied slot instance or identifier.

Signature​

immutableValueOf(slot: Slot | string): ImmutableValue | undefined

Parameters​

NameTypeOptionalDescription
slotSlot | stringNoSpecifies the slot of the value.

Return value​

Returns the ImmutableValue instance for the slot or undefined if the supplied slot is invalid.

🔧 key​

Retrieves a unique key for the block within the current context for the specified label (the key is prefixed with an underscore).

tip

Use this function if you need stable unique keys (for example to use as element IDs).

Signature​

key(label?: string): string

Parameters​

NameTypeOptionalDescription
labelstringYesOptional label for the key (if omitted the default key will be returned).

Return value​

Returns the key.

🔧 lock​

Locks the data values of a block (makes the whole block write-protected).

Signature​

lock(): void

🔧 mutableValueOf​

Retrieves the mutable value for the supplied slot instance or identifier.

Signature​

mutableValueOf(slot: Slot | string): Value | undefined

Parameters​

NameTypeOptionalDescription
slotSlot | stringNoSpecifies the slot of the value.

Return value​

Returns the Value instance for the slot or undefined if the supplied slot is invalid.

🔧 parseVariables​

Parses the supplied markdown string, replacing all variables with their current values.

info

This method is used to parse markdown to plain text.

Signature​

parseVariables(markdown: string, placeholder?: string, lineBreaks?: boolean): string

Parameters​

NameTypeOptionalDescription
markdownstringNoSpecifies the markdown string to parse.
placeholderstringYesSpecifies a string for empty variables (defaults to "").
lineBreaksbooleanYesSpecifies if line breaks are supported (defaults to false).

Return value​

Returns the parsed string.

🔧 slotOf​

Retrieves the slot with the specified reference.

Signature​

slotOf(reference: string, kind?: "static" | "dynamic" | "feature" | "meta"): Slot | undefined

Parameters​

NameTypeOptionalDescription
referencestringNoSpecifies the slot reference.
kind"static" | "dynamic" | "feature" | "meta"YesOptional kind to narrow the scope of the slot select operation.

Return value​

Returns the Slot instance or undefined if no slot is found.

🔧 unlock​

Unlocks the data values of a block (removes the write-protected flag from the whole block).

Signature​

unlock(): void

🔧 valueOf​

Retrieves a mutable value of a slot. Use this method to set/retrieve the values of slots that belong to the block.

info

You can only retrieve mutable values for the slots managed by the block. If you want values from other nodes, use the immutableValueOf method.

Signature​

valueOf(
  reference: string,
  kind?: "static" | "dynamic" | "feature" | "meta",
  options?: {
    confirm?: boolean;
    prefill?: {
      value: any;
      reference?: string;
    };
    modifier?: (value: Value) => {
      value: any;
      reference?: string;
    } | undefined;
    onChange?: (value: Value) => void;
    onContext?: (value: Value, context: Context) => void;
  }
): Value | undefined

Parameters​

NameTypeOptionalDescription
referencestringNoSpecifies the slot reference.
kind"static" | "dynamic" | "feature" | "meta"YesOptional kind to narrow the scope of the slot select operation.
optionsobjectYesSpecifies additional options. Supports the following options:
- confirm: Specifies if the slot always has a confirmed value;
- prefill: Specifies a prefill value for the slot;
- modifier: Specifies a modifier function that is invoked when the value of the slot changes and can be used to modify the value;
- onChange: Specifies a function that is invoked when the value of the slot changes;
- onContext: Specifies a function that is invoked when the value is used within another context.

Return value​

Returns the Value instance for the slot or undefined if the supplied slot is invalid.

🔧 variableFor​

Retrieves the variable for the supplied slot instance or (pipe) identifier. A variable is an immutable representation of a slot value. This method allows to retrieve any slot value in the form within the right context. It can be used to retrieve values from other blocks as well. For example, the calculator block uses this method to retrieve input values from other blocks for the calculator.

Signature​

variableFor(slot: Slot | { slot: Slot } | string): IVariable | undefined

Parameters​

NameTypeOptionalDescription
slotSlot | { slot: Slot } | stringNoSpecifies the slot of the variable.

Return value​

Returns the IVariable instance for the slot or undefined if the supplied slot is invalid.