Skip to main content

Control of Content Items with Grouping and Repetition

In Kuroco, flexible content management is possible by setting grouping and repetition in content definitions. This document explains how the response changes when handling content using grouping and repetition in APIs, and how to send requests in what format when updating.

API Response Structure​

This section describes the response structure when retrieving data using the endpoints Topics::list and Topics::details.

Repetition​

When setting repetition for an item, the set values are responded as an array. If data in the middle of repetition is deleted, it is shifted to the front of the array, and empty data is not included.

    "repeat_texts": [
      "text1",
      "text2",
      "text3"
    ],

Grouping​

When grouping items, the response format varies depending on whether the ext_group parameter is enabled.

When ext_group=true
Grouped items are consolidated into a single object. It is possible to set a slug for the object's item names in the management screen.

   "groups": {
      "choice": {
        "key": "key1",
        "label": "value1"
      },
      "image": {
        "id": "2740_ext_04_0",
        "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_4_0.png",
        "desc": "",
        "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_4_0.png"
      },
      "text": "text"
    },

When ext_group=false
It will be the response of each API, and there will be no difference in the response compared to when not grouped.

    "choice": {
      "key": "key1",
      "label": "value1"
    },
    "image": {
      "id": "2740_ext_04_0",
      "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_4_0.png",
      "desc": "",
      "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_4_0.png"
    },
    "text": "text",

Repetition + Grouping​

When ext_group=true
Grouped objects are responded as an array.

    "groups": [
      {
        "choice": {
          "key": "key1",
          "label": "value1"
        },
        "image": {
          "id": "2740_ext_07_0",
          "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_7_0.png",
          "desc": "",
          "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_7_0.png"
        },
        "text": "text1"
      },
      {
        "choice": {
          "key": "key2",
          "label": "value2"
        },
        "image": {
          "id": "2740_ext_07_1",
          "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_7_1.png",
          "desc": "",
          "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_7_1.png"
        },
        "text": "text2"
      }
    ],

When ext_group=false
The response of each API will be returned as an array. If there are empty data in some of the groups, "" or {} will be included in the array, and the number of data in the array will be the same for each grouped item.

    "choice": [
      {
        "key": "key1",
        "label": "value1"
      },
      {
        "key": "key2",
        "label": "value2"
      }
    ],
    "image": [
      {
        "id": "2740_ext_07_0",
        "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_7_0.png",
        "desc": "",
        "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_7_0.png"
      },
      {
        "id": "2740_ext_07_1",
        "url": "https://xxxxxx.g.kuroco-img.app/v=1747392576/files/topics/2740_ext_7_1.png",
        "desc": "",
        "url_org": "https://xxxxxx.g.kuroco-img.app/files/topics/2740_ext_7_1.png"
      }
    ],
    "text": [
      "",
      "text2"
    ],

Updating via API​

When updating data using the endpoints Topics::update or Topics::bulk_upsert, the request should generally have the same structure as the response obtained from Topics::details. However, there are some points to note when updating grouped or repeated items:

  • All items in the grouped items must be POSTed.
  • For items that are not being changed, please POST the same value as before.
  • For image items, only the id and desc fields should be POSTed. (desc is optional)

Below is an example of updating grouped and repeated items for reference, assuming the use of the Topics::update endpoint with ext_group=true set.

Replacing some data​

If you want to replace some data, retrieve the response from Topics::details, modify the desired items, and POST as follows:

{
  "text_group": [
    {
      "text_1": "text1-1",      //POST the same value as existing data
      "text_2": "New text"      //POST any desired value
    },
    {
      "text_1": "text2-1",      //POST the same value as existing data
      "text_2": "text2-2"       //POST the same value as existing data
    }
  ]
}

Example of NG​

All items within a grouped item must be POSTed. If you exclude some items and there is a difference in the number of items, the order of the data may become incorrect, so please be careful.

{
  "text_group": [
    {
      "text_1": "text1-1",      //POST the same value as existing data
                                //Not including text_2
    },
    {
      "text_1": "text2-1",      //POST the same value as existing data
      "text_2": "text2-2"       //POST the same value as existing data
    }
  ]
}

Replacing some images​

If you want to replace images, upload the file you want to replace to Kuroco's temporary area using the Files::upload endpoint, and add the obtained file_id to the request body:

{
  "groups": [
    {
      "choice": {
        "key": "key1",
        "label": "value1"
      },
      "image": {
        "id": "2740_ext_07_0",
        "desc": "test image1"
      },
      "text": "text1"
    },
    {
      "choice": {
        "key": "key2",
        "label": "value2"
      },
      "image": {
        "id": "2740_ext_07_1",
        "file_id": "files/temp/6217dfe10e096f03dce0dc2a60df8240785d5b13880d72477f18c0ff71597070.png",  //file to replace
        "desc": "test image2"
      },
      "text": "text2"
    }
  ]
}

Example of NG​

If a group contains multiple images, it is not possible to swap only some of them.

Image from Gyazo

An example of a request body for Topics::update would be like the following.

{
  "repeat_multi_image": [
    {
      "image1": {
        "id": "2740_ext_09_1"
      },
      "image2": {
        "id": "2740_ext_10_0"
      }
    },
    {
      "image1": {
        "id": "2740_ext_09_0"
      },
      "image2": {
        "id": "2740_ext_10_1"
      }
    }
  ]
}

It is not possible to have multiple index numbers (_X) within a group, so if you want to swap some images with another group, please replace the images.

Delete part of the repetition​

There are two ways to delete part of the repetition.

Explicitly POST all items as empty​

By POSTing all items within the group as empty values ("" or {}), you can delete the group. Please include all item names without omission.

{
  "groups": [
    {
      "choice": {},
      "image": {},
      "text": ""
    },
    {
      "choice": {
        "key": "key2",
        "label": "value2"
      },
      "image": {
        "id": "2740_ext_07_0",
        "desc": "test image2"
      },
      "text": "text2"
    }
  ]
}
caution

If a group contains boolean values, this method cannot be used as boolean values do not accept updates with "" or null.

POST only the necessary repetition items​

Exclude the group (object) to be deleted and include only the groups to be registered in the request.

{
  "groups": [
    {
      "choice": {
        "key": "key2",
        "label": "value2"
      },
      "image": {
        "id": "2740_ext_07_0",
        "desc": "test image2"
      },
      "text": "text2"
    }
  ]
}

Support

If you have any other questions, please contact us or check out Our Slack Community.

Contact form
Join Kuroco Slack community