👷 Edusign Application Blocks Tool

Description

This npm module, @_edusign/api, provides a convenient API for creating and managing blocks for educational applications.

It allows you to easily generate complex structures for educational content, such as text, images, buttons, forms, and more.

Installation

To use this module in your project, install it using npm:

npm install @_edusign/api

Usage

import edusign from "@_edusign/api";

// Instantiate the Blocks class
const blocksApi = new edusign.Blocks();

Methods

Title

Title(id: string, text: string)

Displays a title text block.

id: Unique ID for your block.
text: Text content.

blocksApi.Title("uniqueTitleId", "Important Title");

Text

Text(id: string, text: string)

Displays a text block.

id: Unique ID for your block.
text: Text or Markdown content.

blocksApi.Text("uniqueTextId", "Hello, this is a text block.");

TextCounter

TextCounter(id: string, text: string, counter: { value: string | number; preset: BlockCounterPresetEnum })

Displays a text block with a counter badge.

id: Unique ID for your block.
text: Text content.
counter: Object with a value and visual preset.

blocksApi.TextCounter("uniqueTextCounterId", "2 tasks remaining", {
  value: 2,
  preset: "outline"
});

Divider

Divider(id: string)

Displays a horizontal rule (HR) line.

id: Unique ID for your block.

blocksApi.Divider("uniqueDividerId");

Image

Image(id: string, url: string, alt?: string)

Displays an image block.

id: Unique ID for your block.
url: Image URL.
alt: Optional alt text for accessibility.

blocksApi.Image("uniqueImageId", "https://example.com/image.jpg", "Image Alt Text");

Button

Button(id: string, style: BlockStyle, text: string, url: string, target: BlockTarget)

Displays a button that redirects to a URL.

id: Unique ID for your block.
style: Button style.
text: Button label.
url: Link destination.
target: Where to open the link (e.g., _blank).

blocksApi.Button("uniqueButtonId", "primary", "Click Me", "https://example.com", "_blank");

Buttons

Buttons(id: string, buttons: ButtonBlock[])

Displays a horizontal group of buttons.

id: Unique ID for your block.
buttons: Array of button objects.

blocksApi.Buttons("exampleButtonsBlock", [
  {
    id: "btn1",
    label: "Save",
    style: "primary",
    url: "https://example.com",
    buttonIcon: {
      icon: "fa-solid fa-floppy-disk",
      iconOnly: false,
      iconPos: "left"
    }
  },
  {
    id: "btn2",
    label: "Delete",
    style: "danger",
    action: {
      name: "deleteAction",
      data: {}
    }
  }
]);

Link

Link(id: string, style: BlockStyle, text: string, url: string, target: BlockTarget)

Displays a hyperlink block.

id: Unique ID for your block.
style: Visual style.
text: Link text.
url: Link destination.
target: Where to open the link.

blocksApi.Link("uniqueLinkId", "secondary", "Visit our website", "https://example.com", "_blank");

File

File(id: string, text: string, url: string, fileType: BlockFileTypeEnum)

Displays a downloadable file block.

id: Unique ID for your block.
text: File name or label.
url: File URL.
fileType: Type of file (e.g., pdf, img).

blocksApi.File("uniqueFileId", "Download Document", "https://example.com/file.pdf", "pdf");

Iframe

Iframe(id: string, url: string, height?: string)

Embeds an iframe.

id: Unique ID for your block.
url: Content URL.
height: Optional height (500px, 80vh, etc.).

blocksApi.Iframe("iframeId", "https://example.com", "500px");

Keyvalue

Keyvalue(id: string, keyvalues: { key: string; value: string }[])

Displays a list of key-value pairs.

id: Unique ID for your block.
keyvalues: Array of key/value objects.

blocksApi.Keyvalue("keyvalueId", [
  { key: "Name", value: "**John**" },
  { key: "Age", value: "30" }
]);

RadioButtons

RadioButtons(id: string, radio: RadioGroup, url?: string, action?: BlockVisualizerAction)

Displays a group of radio buttons.

blocksApi.RadioButtons("radioBlockId", {
  value: "opt1",
  options: [
    { label: "Option 1", value: "opt1" },
    { label: "Option 2", value: "opt2" }
  ],
  disabled: false
});

Switch

Switch(id: string, text: string, checked: boolean, action?: BlockVisualizerAction, url?: string, target?: BlockTarget)

Displays a toggle switch.

blocksApi.Switch("switchId", "Enable notifications", true, {
  name: "toggleSwitch",
  data: { enabled: true }
}, "https://api.example.com/toggle", "_self");

Card

Card(id: string, text: string, card: CardConfig, action?: BlockVisualizerAction, url?: string, target?: BlockTarget)

Displays a card block with optional interaction.

blocksApi.Card("cardId", "**New course available!**", {
  type: "default",
  border: "small",
  padding: "medium",
  isDisabled: false
}, {
  name: "cardClick",
  data: { id: 123 }
});

Ratings

Ratings(id: string, ratings: RatingConfig, action?: BlockVisualizerAction, url?: string, target?: BlockTarget)

Displays a star rating component.

blocksApi.Ratings("ratingsBlockId", {
  rating: 4,
  displayRating: true,
  readonly: false,
  size: "regular"
}, {
  name: "submitRating",
  data: { itemId: "abc123" }
});

Breadcrumb

Breadcrumb(id: string, breadcrumb: BreadcrumbConfig, action?: BlockVisualizerAction, target?: BlockTarget)

Displays breadcrumb navigation.

blocksApi.Breadcrumb("breadcrumbId", {
  items: [
    { label: "Home", url: "/home" },
    { label: "Dashboard", url: "/dashboard" }
  ],
  separator: ">"
});

Wrapper

Wrapper(id: string, items: { label: string; value: string }[], selected: string, action: BlockVisualizerAction, url?: string)

Displays a selection wrapper component.

blocksApi.Wrapper("wrapperId", [
  { label: "Module 1", value: "mod1" },
  { label: "Module 2", value: "mod2" }
], "mod1", {
  name: "moduleSelected",
  data: {}
});

Selects

Selects(id: string, selects: SelectDropdown[])

Displays one or more dropdowns.

blocksApi.Selects("selectsBlockId", [
  {
    value: "opt1",
    placeholder: "Choose an option",
    hasFilter: true,
    selectValues: [
      { name: "Option 1", value: "opt1" },
      { name: "Option 2", value: "opt2" }
    ]
  }
]);

Banner

Banner(id: string, text: string, bannerType: BlockBannerEnum)

Displays a banner notification.

blocksApi.Banner("bannerBlockId", "This is a warning message", "warning");

Error

Error(id: string, text: string)

Displays an error block.

blocksApi.Error("errorBlockId", "Error: Something went wrong.");

Form

Form(id: string, inputs: FormInput[], actionButton: FormActionButton, url: string)

Creates a form with an action button.

id: Unique ID for the form.
inputs: Array of form input configurations.
actionButton: Configuration for the form's action button.
url: URL to send a POST request with the form input values.

const formInputs = [
  { type: BlockFormInputTypeEnum.input, label: "Name", name: "name" },
  { type: BlockFormInputTypeEnum.checkbox, label: "Agree to Terms", name: "agree_terms" },
  // Add more input configurations as needed
];

const formActionButton = {
  name: "submit",
  label: "Submit Form",
  style: "primary",
};

blocksApi.Form("uniqueFormId", formInputs, formActionButton, "https://example.com/submit-form");

👩‍💻
actionButton is the form submit, send a body to the specified url
it's contain the blockId of the form and the form inputs values

Form Inputs

Input Type (text field):

{
  "type": "input",
  "name": "email",
  "label": "Email",
  "placeholder": "Enter your email address"
}

type: Literal string specifying the input type. It must be equal to "input".
name: String representing the name of the input. Required with a minimum length of 1 character.
label: String representing the label of the input. Required with a minimum length of 1 character.
placeholder: Optional string serving as placeholder text in the input.
value: Optional string representing the default value of the input.
hidden: Optional boolean indicating whether the input form is hidden or not - useful to transfert contextual values.
onChanges: Optional string representing the URL to call when a change is detected in the input, the url call need to return valid new app blocks - useful to create conditional and dynamic form.

👩‍💻
onChanges call send a body to the specified url
it's contain the blockId of the form, the input name and the value

Checkbox Type:

{
  "type": "checkbox",
  "name": "subscribe",
  "label": "Subscribe to newsletter",
  "value": false,
  "onChanges": "https://example.com/api/subscribe"
}

type: Literal string specifying the input type. It must be equal to "checkbox".
name: String representing the name of the checkbox. Required with a minimum length of 1 character.
label: String representing the label of the checkbox. Required with a minimum length of 1 character.
value: Optional boolean representing the default state of the checkbox.
onChanges: Optional string representing the URL to call when a change is detected in the checkbox, the url call need to return valid new app blocks - useful to create conditional and dynamic form

👩‍💻
onChanges call send a body to the specified url
it's contain the blockId of the form, the input name and the value

Select Type:

{
  "type": "select",
  "name": "country",
  "label": "Country",
  "placeholder": "Select your country",
  "selectValues": [
    {"name": "France", "value": "fr"},
    {"name": "United States", "value": "us"},
    {"name": "Germany", "value": "de"}
  ]
}

type: Literal string specifying the input type. It must be equal to "select".
name: String representing the name of the checkbox. Required with a minimum length of 1 character.
label: String representing the label of the checkbox. Required with a minimum length of 1 character.
placeholder: Optional string serving as placeholder text in the select.
selectValues: Array of objects representing the options of the select. Each object has two fields:
- name: String representing the name of the option. Required with a minimum length of 1 character.
- value: String representing the value of the option. Required with a minimum length of 1 character.
value: Optional string representing the default value of the select input.
onChanges: Optional string representing the URL to call when a change is detected in the checkbox, the url call need to return valid new app blocks - useful to create conditional and dynamic form

👩‍💻
onChanges call send a body to the specified url
it's contain the blockId of the form, the input name and the value

TreeSelect Type:

{
  "type": "treeSelect",
  "name": "topic",
  "label": "Choose topic",
  "placeholder": "Select a topic",
  "treeSelectValues": [
    {
      "label": "Frontend",
      "data": "frontend",
      "key": "key1",
      "children": [
        { "label": "Angular", "data": "angular", "key": "key2" },
        { "label": "React", "data": "react", "key": "key3" }
      ]
    },
    {
      "label": "Backend",
      "data": "backend",
      "key": "key4"
    }
  ]
}

type: Must be equal to "treeSelect"
name: Unique name for the input field.
label: Label displayed above the field.
placeholder: Optional string shown when no item is selected.
treeSelectValues: Array of options, possibly recursive with children.

Textarea Type:

{
  "type": "textarea",
  "name": "feedback",
  "label": "Your feedback",
  "placeholder": "Enter your message here",
  "value": "",
  "rows": 5
}

type: Must be equal to "textarea"
name: Unique name for the input field.
label: Label displayed above the textarea.
placeholder: Optional placeholder text.
value: Default text content.
rows: Number of visible lines (optional).

Datepicker Type:

{
  "type": "datepicker",
  "name": "birthdate",
  "label": "Date of Birth",
  "value": "1990-01-01T00:00:00.000Z"
}

type: Must be equal to "datepicker"
name: Unique name for the input field.
label: Label displayed above the datepicker.
value: Default ISO date string.

Signature Type:

{
  "type": "signature",
  "name": "consent",
  "label": "Sign below",
  "placeholder": "Sign here...",
  "showClear": true,
  "clearButtonTxt": "Clear"
}

type: Must be equal to "signature"
name: Unique name for the input field.
label: Label displayed above the pad.
placeholder: Optional guidance text.
showClear: Whether a clear button is shown.
clearButtonTxt: Text inside the clear button.

Utils Method

Block to JSON

toJson(space: number = 0)

Used to convert the configured blocks to a JSON string.

space: Optional parameter to prettify JSON.

const jsonString = blocksApi.toJson(2);

JSON to block

fromJSON(json: string): Block[]

Used to convert a JSON string to a Blocks object.

json: JSON string to parse.

const blocksArray = blocksApi.fromJSON(jsonString);

JSON validator

validator(jsonBlocks: string | Block[])

Useful to verify if a JSON blocks string is correct or not before sending the response back to Edusign.

jsonBlocks: JSON parsed or stringified.

blocksApi.validator(jsonString);

Description

Installation

Usage

Methods

Title

Text

TextCounter

Divider

Image

Button

Buttons

Link

File

Iframe

Keyvalue

RadioButtons

Switch

Card

Ratings

Breadcrumb

Wrapper

Selects

Banner

Error

Form

👩‍💻actionButton is the form submit, send a body to the specified url

Form Inputs

Input Type (text field):

👩‍💻onChanges call send a body to the specified url

Checkbox Type:

👩‍💻onChanges call send a body to the specified url

Select Type:

👩‍💻onChanges call send a body to the specified url

TreeSelect Type:

Textarea Type:

Datepicker Type:

Signature Type:

Utils Method

Block to JSON

JSON to block

JSON validator

👩‍💻
actionButton is the form submit, send a body to the specified url

👩‍💻
onChanges call send a body to the specified url

👩‍💻
onChanges call send a body to the specified url

👩‍💻
onChanges call send a body to the specified url