Build a Widget
Describes the request data identifier and response structure needed to render a widget.
A widget built in the console is delivered under the response's widget node whenever you append the widget property (an array) to any request's data identifier.
Data Identifier
{
"dataID": "GET_POST_LIST",
"board_seq": 301,
"widget": ["top_post"]
}
| Key | Description |
|---|---|
| dataID | Any data identifier - a widget can ride along with any request (e.g. GET_POST_LIST) |
| board_seq | The properties the original request already uses - the widget property is simply appended to them |
| widget | An array whose elements are widget codes created in the console |
HTML
<div class="h-widget">
<h6>{{ output.widget.top_post.widget_name }}</h6>
<ul class="list-group list-group-flush">
<li class="list-group-item" v-for="post in output.widget.top_post.content_list">
<a :href="'/community/detail?post_key=' + post.post_key">
<span class="crop-text-1">{{ post.subject }}</span>
</a>
<small>{{ post.nickname }} · {{ post.create_date }}</small>
</li>
</ul>
</div>
- div
<div class="h-widget"></div>The wrapper element for the widget
- h6
<h6></h6>Widget title area - exposes widget meta such as description
- li
<li class="list-group-item" v-for="post in output.widget.top_post.content_list"></li>Iterates content_list to render each content (post)
- a
<a :href="'/community/detail?post_key=' + post.post_key"></a>Content detail link - builds the detail path from post_key
- small
<small></small>Area for content meta info (created date, etc.)
Response Result
{
"seq": "12",
"widget_name": "Popular posts",
"widget_code": "top_post",
"widget_type": "board_daily_rate",
"description": "Popular posts",
"content_category": "200",
"content_limit": "5",
"content_sort": "desc",
"create_date": "2025-01-01 12:00:13",
"modify_date": "2025-02-01 09:11:00",
"delete_date": null,
"delete_flg": "N",
"widget_key": "B9897JDFUIDYUH23A1B2C3D4E5F6",
"content_list": [
{
"seq": "101",
"post_key": "13E1106F6DBE546EA8A6E8A27C2DF19E",
"parent_post_key": "13E1106F6DBE546EA8A6E8A27C2DF19E",
"board_seq": "200",
"board_name": "Notice",
"member_seq": "3",
"nickname": "admin",
"avatar_url": "/_images/face_icons_circle/face_icons-circle-01.svg",
"subject": "Subject 1",
"status": "published",
"create_date": "2025-01-01 12:00:13",
"modify_date": "2025-01-02 10:00:00",
"read_count": "120",
"read_per_day_rate": "7.40",
"like_cnt": "3",
"child_post_count": "0",
"content": "<p>This is the post content.</p>",
"content_without_html": "This is the post content.",
"content_summary": "This is the post content.",
"files": "/post/2025/01/sample.jpg"
},
{
"seq": "209",
"post_key": "5A2B7C9D1E3F546EA8A6E8A27C2DF201",
"parent_post_key": "5A2B7C9D1E3F546EA8A6E8A27C2DF201",
"board_seq": "200",
"board_name": "Notice",
"member_seq": "3",
"nickname": "admin",
"avatar_url": "/_images/face_icons_circle/face_icons-circle-02.svg",
"subject": "Subject 2",
"status": "published",
"create_date": "2025-01-04 12:00:13",
"modify_date": "2025-01-04 12:00:13",
"read_count": "85",
"read_per_day_rate": "6.10",
"like_cnt": "1",
"child_post_count": "0",
"content": "<p>This is the post content.</p>",
"content_without_html": "This is the post content.",
"content_summary": "This is the post content.",
"files": null
}
]
}
| Key | Description |
|---|---|
| widget | The widget response node returned alongside the request when a widget array is present |
| widget.{widget_code} | Each widget is keyed by the widget code you requested |
| seq | Widget sequence (internal number) |
| widget_name | Widget name |
| widget_code | Widget code |
| widget_type | Widget type (board_daily_rate: by view rate, board_create_date: by created date, like_count: by likes, custom: manually selected posts) |
| description | Widget description |
| content_category | Widget content category (board sequence). null for the custom type, which does not use it |
| content_limit | Number of contents to expose |
| content_sort | Content sort (asc or desc) - applied to the post ordering of board-type widgets |
| create_date | Widget creation date |
| modify_date | Widget modified date |
| delete_date | Widget deleted date (null when not deleted) |
| delete_flg | Delete flag (N: active) |
| widget_key | Widget key (encrypted widget identifier) |
| content_list | Widget content list - board types (board_daily_rate/board_create_date/like_count) return the same response as the post list; for the custom type the post list fields are merged into the fields below |
| content_list[].post_key | Content (post) key - use it for detail requests such as GET_POST and for detail links |
| content_list[].content_seq | custom type only - content (post) sequence (numeric). Items have no seq field |
| content_list[].subject | Content (post) subject - for the custom type this is a snapshot taken when the widget was saved |
| content_list[].position | custom type only - display order assigned in the console |
| content_list[].create_date | For the custom type this is when the content was registered into the widget; for board types it is the post's created date |
| content_list[].post_create_date | custom type only - the post's original created date. Use this field when displaying the publish date |
| content_list[].(post fields) | custom type only - the same fields as the post list response are merged in (board_seq, board_name, nickname, avatar_url, read_count, read_per_day_rate, like_cnt, content, content_summary, files, etc.). Note that subject/create_date keep their widget-registration values and seq is excluded as it duplicates content_seq |
- The widget property is not a separate request; it can be added to any request. Passing multiple widget codes as an array returns each one under the widget node keyed by its code.
- The makeup of content_list depends on the widget type. board_daily_rate/board_create_date/like_count fill it with sorted posts from the target board, while custom fills it with posts chosen directly in the console.
- For board-type widgets, content_list items carry the same fields as the post list response (post_key, subject, create_date, read_per_day_rate, etc.).
- In a custom widget's content_list, create_date is when the content was registered (saved) into the widget, not the post's publish date. Use post_create_date for the post's original created date.
- Items in a custom widget's content_list also carry the merged fields of the post list response (author nickname, board_name, like_cnt, content_summary, etc.). If a post is unpublished or deleted, that item keeps only the base fields.
- custom items carry both a numeric identifier (content_seq) and an encrypted key (post_key). The post_key parameter of GET_POST accepts either, but using post_key (the encrypted key) is recommended since it does not expose internal numbers.
- A custom widget's content_list is always sorted by position in ascending order. content_sort only applies to the post ordering of board-type widgets.
- Numeric values in the response (seq, content_limit, content_seq, position, etc.) are returned as strings. Cast them before numeric comparison or sorting.
Example
Widget 1
- This is the post content.7.40 View/Day
- This is the post content.6.40 View/Day
- This is the post content.5.40 View/Day
- This is the post content.4.40 View/Day
- This is the post content.3.40 View/Day
Widget n
- This is the post content.23.11.07
- This is the post content.23.11.06
- This is the post content.23.11.05
- This is the post content.23.11.04
- This is the post content.23.11.03
<div class="bg-white p-3 rounded-3">
<div>
<h6 class="mb-3">{{ output.widget.top_post.widget_name }}</h6>
<ul class="list-group list-group-flush">
<li class="list-group-item bg-transparent px-1" v-for="post in output.widget.top_post.content_list">
<div class="d-flex justify-content-between align-items-center">
<a :href="'/community/detail?post_key='+post.post_key" class="text-black">
<small class="crop-text-1">{{ post.subject }}</small>
</a>
<small>{{ post.nickname }} · {{ post.create_date }}</small>
</div>
<small class="text-muted crop-text-1">{{ post.content_summary }}</small>
</li>
</ul>
</div>
</div>
<div class="bg-white p-3 rounded-3">
<div>
<h6 class="mb-3"><?=$output['widget']['top_post']['widget_name'];?></h6>
<ul class="list-group list-group-flush">
<? foreach($output['widget']['top_post']['content_list'] as $intKey=>$arrPost){ ?>
<li class="list-group-item bg-transparent px-1">
<div class="d-flex justify-content-between align-items-center">
<a href="/community/detail?post_key=<?=$arrPost['post_key'];?>" class="text-black">
<small class="crop-text-1"><?=$arrPost['subject'];?></small>
</a>
<small><?=$arrPost['nickname'];?> · <?=$arrPost['create_date'];?></small>
</div>
<small class="text-muted crop-text-1"><?=$arrPost['content_summary'];?></small>
</li>
<? } ?>
</ul>
</div>
</div>