Custom API Blocks

The Custom API Block allows you to load categorized data from an API endpoint and map it to customizable attributes that you can style and use inside templates. This documentation provides a detailed guide on how to structure your API endpoints and style the data within your templates.

Overview

The Custom API Block is designed to integrate data from external APIs into your templates dynamically. It fetches categorized data, allowing you to style and manipulate this data to create dynamic content blocks.

API Endpoint Structure

To use the Custom API Block, your API should expose two main endpoints:

• Feeds Endpoint: Provides a list of categories or feeds.
• Items Endpoint: Provides detailed items for each feed.

Feed Response

The feed response returns a list of available feeds or categories. Each feed has an id and a name. The response structure is as follows:

Expected Response for the feed endpoint

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Feed 1"
    },
    {
      "id": 2,
      "name": "Feed 2"
    },
    {
      "id": 3,
      "name": "Feed 3"
    },
    {
      "id": 4,
      "name": "Feed 4"
    }
  ],
  "total_records": 4
}

Item Response

The item response returns detailed data for each feed. The response structure is as follows:

Expected Response for the Item

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Block 1",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/warsaw.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 1",
      "my-text-2": "My text 2 in block 1",
      "my-text-3": "My text 3 in block 1",
      "feed_id": 1
    },
    {
      "id": 2,
      "name": "Block 2",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/prague.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 2",
      "my-text-2": "My text 2 in block 2",
      "my-text-3": "My text 3 in block 2",
      "feed_id": 1
    },
    {
      "id": 3,
      "name": "Block 3",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/bridge.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 3",
      "my-text-2": "My text 2 in block 3",
      "my-text-3": "My text 3 in block 3",
      "feed_id": 1
    }
  ],
  "total_records": 3
}

Block Configuration

The configuration for a Custom API Block defines how the data is mapped and styled within your template. Below is a detailed example configuration.

Example block

  apiBlocks: {
      testBlock: {
        itemsURL: "https://example.test/my-block",
        feedsURL:
          "https://example.test/my-block-feeds",
        name: "Test Block",
        pluralName: "Test Blocks",
        icon: "",
        blockStructure: {
          image: {
            defaultValue:
              "https://s3-eu-west-1.amazonaws.com/ecomail-assets/editor/pp1.png",
            label: "Image",
            width: 250,
            align: "center",
          },
          href: {
            defaultValue: "*|MY_HREF|*",
          },
          "my-text-1": {
            defaultValue: "*|MY_TEXT_1|*",
            label: "My Text 1",
            "font-size": "16px",
            color: "#123456",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "bold",
          },
          "my-text-2": {
            defaultValue: "*|MY_TEXT_2|*",
            label: "My Text 2",
            "font-size": "14px",
            color: "#654321",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "normal",
          },
          "my-text-3": {
            defaultValue: "*|MY_TEXT_3|*",
            label: "My Text 3",
            "font-size": "12px",
            color: "#000000",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "normal",
            "font-style": "italic",
          },
          button: {
            defaultValue: "Click me",
            label: "Button",
            align: "center",
            "background-color": "#123456",
            color: "#ffffff",
            "font-size": "16px",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "bold",
            "font-style": "italic",
            "text-transform": "uppercase",
            "text-decoration": "none",
            "border-radius": "3px",
            padding: "10px 20px 10px 20px",
          },
        },
      },
    },

Styling Attributes

The block configuration includes several customizable styling attributes for different elements within the block.

Image

• defaultValue Default image URL.
• label Descriptive label for the image.
• width Image width (in pixels).
• align Alignment of the image (e.g., center, left, right).

Hyperlink (href)

• defaultValue Default URL or placeholder for the hyperlink.

Text Fields

Each text field can be customized with various styling attributes:

• defaultValue Default text or placeholder.
• label Descriptive label for the text field.
• font-size Font size (e.g., 16px).
• color Text color (e.g., #123456).
• font-family Font family (e.g., Helvetica, Arial, sans-serif).
• font-weight Font weight (e.g., bold, normal).
• font-style Font style (e.g., italic).

Button

• defaultValue Default button text.
• label Descriptive label for the button.
• align Button alignment (e.g., center).
• background-color Background color of the button.
• color Text color.
• font-size Font size.
• font-family Font family.
• font-weight Font weight.
• font-style Font style.
• text-transform Text transformation (e.g., uppercase).
• text-decoration Text decoration (e.g., none).
• border-radius Border radius (in pixels).
• padding Padding around the button (e.g., 10px 20px 10px 20px).