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", "new_arrivals", "best_sellers", "picked_products"]
}
| Key | Description |
|---|---|
| dataID | Any data identifier. Widgets ride along with any request (e.g. GET_POST_LIST) |
| board_seq | The original request's properties. Append widget to them |
| widget | Array of widget codes made 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 class="h-widget">
<h6>{{ output.widget.new_arrivals.widget_name }}</h6>
<div class="col-6" v-for="p in output.widget.new_arrivals.content_list">
<a :href="'/shop/product?product_key=' + p.product_key">{{ p.name }}</a>
<div v-if="p.list_price"><del>{{ p.list_price }}</del> {{ p.discount_rate }}%</div>
<div>{{ p.price }} {{ p.currency }}</div>
<span v-if="p.sold_out">Sold out</span>
</div>
</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.)
- div
<div class="h-widget"></div>The wrapper element for a product widget
- div
<div class="col-6" v-for="p in output.widget.new_arrivals.content_list"></div>Iterates content_list to render product cards
- a
<a :href="'/shop/product?product_key=' + p.product_key"></a>Product detail link - built from product_key
- div
<div v-if="p.list_price"></div>Struck-through regular price and discount - only when list_price is set
- div
<div></div>Selling price and currency
- span
<span v-if="p.sold_out"></span>Sold-out badge - when sold_out is true
Response Result
{
"widget": {
"top_post": {
"seq": 12,
"widget_code": "top_post",
"widget_name": "Popular posts",
"widget_type": "board_daily_rate",
"description": "Most read posts per day",
"content_category": 200,
"content_limit": 5,
"content_sort": "desc",
"options": null,
"create_date": "2025-01-01 12:00:13",
"modify_date": "2025-02-01 09:11:00",
"delete_date": null,
"delete_flg": "N",
"widget_key": "B98970DF01D4A23A1B2C3D4E5F607182",
"content_kind": "post",
"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": "Getting started with H:Dev+",
"status": "published",
"create_date": "2025-01-01 12:00:13",
"modify_date": "2025-01-01 12:00:13",
"read_count": 120,
"read_per_day_rate": 7.4,
"like_cnt": 3,
"child_post_count": 0,
"content": "<p>Set up your first project.</p>",
"content_without_html": "Set up your first project.",
"content_summary": "Set up your first project.",
"files": null,
"post_create_date": "2025-01-01 12:00:13"
},
{
"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-01.svg",
"subject": "Release notes 1.0.36",
"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.1,
"like_cnt": 1,
"child_post_count": 0,
"content": "<p>Product widgets are now available.</p>",
"content_without_html": "Product widgets are now available.",
"content_summary": "Product widgets are now available.",
"files": null
}
]
},
"new_arrivals": {
"seq": 22,
"widget_code": "new_arrivals",
"widget_name": "New arrivals",
"widget_type": "product_recent",
"description": "Newest T-shirts",
"content_category": 2,
"content_limit": 4,
"content_sort": "desc",
"options": {
"soldout": "hide"
},
"create_date": "2026-10-01 10:00:00",
"modify_date": null,
"delete_date": null,
"delete_flg": "N",
"widget_key": "D4E5F60718293A4B5C6D7E8F90A1B2C3",
"content_kind": "product",
"content_list": [
{
"position": 1,
"product_key": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
"name": "Cotton T-Shirt",
"product_code": "TS-TS01",
"image_url": "/upload/product/ts-ts01.jpg",
"price": 19000,
"list_price": 25000,
"discount_rate": 24,
"currency": "KRW",
"sold_out": false
}
]
},
"best_sellers": {
"seq": 23,
"widget_code": "best_sellers",
"widget_name": "Best sellers",
"widget_type": "product_best",
"description": "Top sellers, last 7 days",
"content_category": null,
"content_limit": 4,
"content_sort": "desc",
"options": {
"soldout": "show",
"rank_days": 7
},
"create_date": "2026-10-01 10:00:00",
"modify_date": null,
"delete_date": null,
"delete_flg": "N",
"widget_key": "E5F60718293A4B5C6D7E8F90A1B2C3D4",
"content_kind": "product",
"content_list": [
{
"position": 1,
"product_key": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
"name": "Cotton T-Shirt",
"product_code": "TS-TS01",
"image_url": "/upload/product/ts-ts01.jpg",
"price": 19000,
"list_price": 25000,
"discount_rate": 24,
"currency": "KRW",
"sold_out": false,
"sold_quantity": 2
}
]
},
"picked_products": {
"seq": 21,
"widget_code": "picked_products",
"widget_name": "Picked for you",
"widget_type": "product",
"description": "Hand-picked products",
"content_category": null,
"content_limit": 4,
"content_sort": "asc",
"options": {
"soldout": "show"
},
"create_date": "2026-10-01 10:00:00",
"modify_date": null,
"delete_date": null,
"delete_flg": "N",
"widget_key": "C3D4E5F60718293A4B5C6D7E8F90A1B2",
"content_kind": "product",
"content_list": [
{
"position": 1,
"product_key": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
"name": "Cotton T-Shirt",
"product_code": "TS-TS01",
"image_url": "/upload/product/ts-ts01.jpg",
"price": 19000,
"list_price": 25000,
"discount_rate": 24,
"currency": "KRW",
"sold_out": false
},
{
"position": 2,
"product_key": "B2C3D4E5F60718293A4B5C6D7E8F90A1",
"name": "Ceramic Mug",
"product_code": "TS-SO",
"image_url": "/upload/product/ts-so.jpg",
"price": 12000,
"list_price": null,
"discount_rate": null,
"currency": "KRW",
"sold_out": true
}
]
}
}
}
| Key | Description |
|---|---|
| widget | Widget response node |
| widget.{widget_code} | Keyed by the requested widget code |
| seq | Widget number (number) |
| widget_name | Widget name |
| widget_code | Widget code |
| widget_type | 4 post types · 3 product types (see below) |
| description | Widget description |
| content_category | Board number or product category number |
| content_limit | Items to show (number) |
| content_sort | Board-type sort asc / desc |
| options | Product widget settings. null for posts |
| options.soldout | Sold-out products show (default) / hide |
| options.rank_days | product_best period 7 / 30 / 90 |
| content_kind | Item kind post / product |
| widget_key | Widget key (encrypted identifier) |
| create_date | Widget created at |
| modify_date | Widget modified at |
| delete_date | Widget deleted at (null if not) |
| delete_flg | Deleted flag (N active) |
| content_list | Widget items |
| content_list[].post_key | [post] Post key (for detail links) |
| content_list[].subject | [post] Post subject |
| content_list[].content_seq | [post] custom only. Post number |
| content_list[].create_date | [post] Created (custom: added to widget) |
| content_list[].post_create_date | [post] Post created at. Present for every post widget type (for board types it equals create_date) |
| content_list[].(post fields) | [post] Same fields as the post list |
| content_list[].position | Display order (from 1) |
| content_list[].product_key | [product] Product key (for detail links) |
| content_list[].name | [product] Product name |
| content_list[].product_code | [product] Product code |
| content_list[].image_url | [product] Main image. null if none |
| content_list[].price | [product] Selling price (number) |
| content_list[].list_price | [product] Regular price. null if no discount |
| content_list[].discount_rate | [product] Discount %. null if no discount |
| content_list[].currency | [product] Currency code |
| content_list[].sold_out | [product] Sold out true / false |
| content_list[].sold_quantity | [product] product_best only. Units sold |
- The widget property is not a separate request; add it to any request. Pass several widget codes as an array and each comes back under the widget node keyed by its code.
- Widget types — posts: board_daily_rate (views per day), board_create_date (newest), like_count (most liked), custom (posts picked in the console). Products: product (picked in the console), product_recent (new arrivals), product_best (best sellers).
- Use content_kind to tell item shapes apart. post items carry post fields; product items carry position, product_key, name, product_code, image_url, price, list_price, discount_rate, currency and sold_out (product_best adds sold_quantity). Only product widgets have an options object; post widgets have null.
- Product widgets — product follows the console order (position); product_recent shows the newest products in content_category and its sub-categories (all products if empty); product_best ranks by units sold in paid orders (PAID, PARTIALLY_REFUNDED) within the last rank_days days. Only ACTIVE, non-deleted products appear. content_limit is 1 to 50.
- Prices — list_price and discount_rate have values only when the regular price is above the selling price; otherwise null. When set, strike through the regular price and show the discount rate.
- Sold out — sold_out is true when the product has stock-tracked rows and none has available stock (on hand − reserved). Products without stock tracking are never sold out. With options.soldout = hide, sold-out products are left out.
- For post 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, create_date is when the content was added to the widget, not the post's publish date. Use post_create_date for the post's original date. Board-type widgets also return post_create_date, so one key shows the date even if you change the widget type.
- Use the encrypted keys in detail links instead of internal numbers: post_key for posts, product_key for products.
- custom and product widgets list content in ascending position. content_sort applies only to the post order of board-type widgets.
- Numbers (seq, content_category, content_limit, position, price, etc.) come as JSON numbers. No string conversion is needed.
- An unknown or deleted widget code is simply missing from the widget node. The main request (dataID) result and errors are unaffected by widgets.
Example
Popular posts
- Getting started with H:Dev+admin · 2025-01-01 12:00:13
- Release notes 1.0.36admin · 2025-01-04 12:00:13
<script setup>
// Add the widget codes to any request. Each widget comes back under output.widget[code].
const { output } = await useNuxtApp().$connector({
dataID: 'GET_POST_LIST', board_seq: 301,
widget: ['top_post', 'new_arrivals']
})
const posts = output.widget.top_post
const products = output.widget.new_arrivals
const money = (v, c) => new Intl.NumberFormat('ko-KR', { style: 'currency', currency: c }).format(v)
</script>
<template>
<div class="row g-3">
<!-- Post widget (content_kind: post) -->
<div class="col-12 col-lg-5">
<div class="bg-white p-3 rounded-3">
<h6 class="mb-3">{{ posts.widget_name }}</h6>
<ul class="list-group list-group-flush">
<li class="list-group-item bg-transparent px-1" v-for="post in posts.content_list" :key="post.post_key">
<NuxtLink :to="`/community/detail?post_key=${post.post_key}`" class="text-black">{{ post.subject }}</NuxtLink>
<div class="small text-secondary">{{ post.nickname }} · {{ post.create_date }}</div>
</li>
</ul>
</div>
</div>
<!-- Product widget (content_kind: product) -->
<div class="col-12 col-lg-7">
<div class="bg-white p-3 rounded-3">
<h6 class="mb-3">{{ products.widget_name }}</h6>
<div class="row g-2">
<div class="col-6" v-for="p in products.content_list" :key="p.product_key">
<NuxtLink :to="`/shop/product?product_key=${p.product_key}`" class="d-block text-black">
<img v-if="p.image_url" :src="p.image_url" :alt="p.name" class="img-fluid rounded-2 mb-1">
<div>{{ p.name }}</div>
<div v-if="p.list_price" class="small text-secondary">
<del>{{ money(p.list_price, p.currency) }}</del> <span class="text-danger">{{ p.discount_rate }}%</span>
</div>
<div class="fw-bold">{{ money(p.price, p.currency) }}</div>
<span v-if="p.sold_out" class="badge bg-secondary">Sold out</span>
<span v-if="p.sold_quantity" class="small text-secondary">{{ p.sold_quantity }} sold</span>
</NuxtLink>
</div>
</div>
</div>
</div>
</div>
</template>
<?php
$output = $connector->request(['dataID' => 'GET_POST_LIST', 'board_seq' => 301, 'widget' => ['top_post', 'new_arrivals']]);
$posts = $output['widget']['top_post'];
$products = $output['widget']['new_arrivals'];
?>
<div class="bg-white p-3 rounded-3">
<h6 class="mb-3"><?= htmlspecialchars($posts['widget_name']) ?></h6>
<ul class="list-group list-group-flush">
<?php foreach ($posts['content_list'] as $post) { ?>
<li class="list-group-item bg-transparent px-1">
<a href="/community/detail?post_key=<?= $post['post_key'] ?>" class="text-black"><?= htmlspecialchars($post['subject']) ?></a>
<div class="small text-secondary"><?= htmlspecialchars($post['nickname']) ?> · <?= $post['create_date'] ?></div>
</li>
<?php } ?>
</ul>
</div>
<div class="bg-white p-3 rounded-3">
<h6 class="mb-3"><?= htmlspecialchars($products['widget_name']) ?></h6>
<div class="row g-2">
<?php foreach ($products['content_list'] as $p) { ?>
<div class="col-6">
<a href="/shop/product?product_key=<?= $p['product_key'] ?>" class="d-block text-black">
<div><?= htmlspecialchars($p['name']) ?></div>
<?php if ($p['list_price'] !== null) { ?>
<div class="small text-secondary"><del><?= number_format($p['list_price']) ?></del> <span class="text-danger"><?= $p['discount_rate'] ?>%</span></div>
<?php } ?>
<div class="fw-bold"><?= number_format($p['price']) ?> <?= $p['currency'] ?></div>
<?php if ($p['sold_out']) { ?><span class="badge bg-secondary">Sold out</span><?php } ?>
</a>
</div>
<?php } ?>
</div>
</div>