👷 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 or Markdown 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.");

Image

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

Displays an image block.

• id: Unique ID for your block.
• url: Image URL.
• alt: Alt text for the image.

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

Button

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

button open specified url into a new tab

Displays a button with a URL action.

• id: Unique ID for your block.
• style: Style of the button.
• text: Text for the button.
• url: URL of the button click action.
• target: Target attribute for the link.

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

Link

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

Displays a link with a URL action.

• id: Unique ID for your block.
• style: Style of the link.
• text: Text for the link.
• url: URL of the link click action (href).
• target: Target attribute for the link.

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

File download

File(id: string, text: string, url: string, fileType: Block["fileType"])

Displays a file download block.

• id: Unique ID for your block.
• text: Name of the file.
• url: URL of the file.
• fileType: Type of the file (e.g., pdf, doc).

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

Divider

Divider(id: string)

Displays a horizontal rule (HR) line.

• id: Unique ID for your block.

blocksApi.Divider("uniqueDividerId");

Iframe

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

Displays an iframe.

• id: Unique ID for your block.
• url: URL for the iframe.
• height: Optional height for the iframe.

blocksApi.Iframe("uniqueIframeId", "https://example.com/embedded-content", "400px");

Key/value list

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

Displays a key/value list.

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

blocksApi.Keyvalue(
  "uniqueKeyvalueId",
  [{ key: "Key1", value: "Value1" }, { key: "Key2", value: "Value2" }]
);

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

We have three types of form inputs:

Input Type (text field):

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

{
  "type": "input",
  "name": "studentId",
  "label": "studentId",
  "value": "aesfjfjfrehg",
  "hidden": true
}

• 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": "select",
  "name": "country",
  "label": "Country",
  "placeholder": "Select your country",
  "selectValues": [
    {"name": "France", "value": "fr"},
    {"name": "United States", "value": "us"},
    {"name": "Germany", "value": "de"}
  ],
  "onChanges": "https://example.com/api/country/update"
}

• 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

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);