> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Дизайни

> Завантажте власний HTML-сайт як дизайн і підключіть його до товарів, кошика та оформлення замовлення за допомогою Liquid, атрибутів data-ps або JavaScript SDK.

Дизайн це ваш власний вебсайт, завантажений як ZIP-архів, який PapelShip віддає як вашу вітрину. Ви зберігаєте повний контроль над розміткою й додаєте комерційні функції трьома способами:

1. **Сторінки Liquid**: `pages/*.liquid` рендеряться на сервері з даними вашого магазину.
2. **Атрибути `data-ps`**: звичайний HTML, який PapelShip заповнює даними товарів на сервері.
3. **SDK**: `window.PapelShip` для товарів, кошика та оформлення замовлення в браузері.

## Пакет

| Шлях | Містить |
| - | - |
| `pages/*.html`, `pages/*.liquid` | Сторінки. Сторінки `.html` статичні; сторінки `.liquid` рендеряться з даними магазину. |
| `partials/`, `snippets/` | Спільна розмітка |
| `assets/`, `media/` | CSS, JavaScript, зображення та шрифти |
| `config/design.json` | Список сторінок із шляхами та SEO, а також ваші налаштування |
| `seo/robots.txt`, `seo/sitemap-extra.txt` | Необов'язкові SEO-файли |

Кожна сторінка, вказана в `config/design.json`, отримує шлях у вашому магазині.

**Шаблони.** `pages/product.liquid` (або `.html`) є вашою сторінкою товару, а `pages/shop.liquid` вашим переліком товарів. Без них PapelShip показує нейтральну сторінку товару або магазину всередині вашого дизайну.

**Не знайдено.** Додайте `pages/404.html` (або `.liquid`), щоб мати власну сторінку «не знайдено». Вона показується для невідомих адрес і невідомих товарів.

## Сканування та перевірка

Кожне завантаження сканується, перш ніж воно зможе стати активним. Код, що атакує клієнтів або платформу, блокується: поля для даних картки, приховані перенаправлення, форми, що надсилають дані на інші сайти, запити до API PapelShip або інших магазинів, а також шкідливі скрипти. Незвичний код спочатку перевіряє PapelShip. Виправте вказані файли та завантажте їх знову.

Зміни зберігаються як чернетки; ваш магазин залишається на опублікованій версії. **Publish** сканує саме ті файли, які публікує: заблокований код скасовує публікацію, а знахідки, що потребують перевірки, чекають на перевірку PapelShip, поки магазин працює на поточній версії, і публікуються після схвалення.

## Атрибути data-ps

Позначте елементи, і PapelShip заповнить їх даними товарів на сервері:

```html theme={"system"}
<div data-ps-product="current">
  <img data-ps="image" alt="">
  <h1 data-ps="title"></h1>
  <p><span data-ps="price"></span> <s data-ps="compare-price" data-ps-if="on-sale"></s></p>
  <div data-ps="variants"></div>
  <button data-ps="add" data-ps-if="in-stock">Add to cart</button>
  <span data-ps-if="sold-out">Sold out</span>
</div>
```

### Значення

| `data-ps` | Заповнює |
| - | - |
| `title` | Назва товару |
| `price` | Поточна ціна |
| `compare-price` | Ціна для порівняння |
| `stock` | Позначка наявності |
| `rating` | Середній рейтинг |
| `badge` | Значок розпродажу або акції |
| `description` | Опис у вигляді звичайного тексту |
| `image` | На `<img>`: зображення товару |
| `url` | На `<a>`: посилання на сторінку товару |
| `buy` | Кнопка «Купити зараз», переходить до оформлення замовлення |
| `add` | Кнопка «Додати в кошик» |
| `variants` | На `<div>`: вибір варіанта. Кнопки додавання, купівлі та ціна поруч враховують вибір. |

### Умови

| `data-ps-if` | Залишає елемент лише тоді, коли |
| - | - |
| `on-sale` | Товар продається зі знижкою |
| `in-stock` | Товар є в наявності |
| `sold-out` | Товар розпродано |

### Контейнери

| Атрибут | Що робить |
| - | - |
| `data-ps-products="8"` | Повторює перший дочірній `<template>` для N товарів (максимум 48) |
| `data-ps-collection` | Обмежує список handle колекції |
| `data-ps-sort` | `featured`, `newest`, `price-asc`, `price-desc`, `best-selling` |
| `data-ps-ids` | ID товарів для відображення через кому |
| `data-ps-product` | Один товар: id, хеш або `current` у шаблоні товару |

```html theme={"system"}
<div data-ps-products="8" data-ps-sort="newest">
  <template>
    <a data-ps="url"><img data-ps="image" alt=""><span data-ps="title"></span></a>
    <span data-ps="price"></span>
    <button data-ps="add" data-ps-if="in-stock">Add to cart</button>
  </template>
</div>
```

## Сторінки Liquid

Сторінки `.liquid` використовують ті самі об'єкти, фільтри та теги, що й теми Liquid, зокрема `{% app_block %}`. Див. [Теми та Liquid](https://developers.papelship.com/uk/themes/liquid.md). Статичні експорти, що використовують `{{ }}` для інших шаблонізаторів, залишаються безпечними: рендеряться лише сторінки `.liquid`.

## SDK

> [!NOTE]
>
> SDK завантажується лише на сторінках дизайну, які містять прив'язку `data-ps` або заповнювач `data-app-block`. Викликайте його з обробника `DOMContentLoaded`. Див. [Комерція та оформлення замовлення](https://developers.papelship.com/uk/themes/commerce.md).

На цих сторінках SDK доступний як `window.PapelShip`.

| Метод | Що робить |
| - | - |
| `products.list({ limit, ids, collection, sort })` | Promise із товарами |
| `products.get(id)` | Promise із одним товаром |
| `cart.items`, `cart.count`, `cart.subtotal` | Стан кошика |
| `cart.add(id, { variantId, quantity })` | Додає позицію, повертає promise |
| `cart.remove`, `cart.update(index, quantity)`, `cart.clear` | Змінює кошик |
| `cart.open`, `cart.close` | Відкриває або закриває бічну панель кошика |
| `cart.on`, `cart.off` | Події `change` і `add` (`papelship:cart-change`, `papelship:cart-add`) |
| `price` | Рядки цін із застосованими акціями |
| `checkout({ products?, mode: 'page' \| 'embed', onPaid? })` | `page` (за замовчуванням) переходить на сторінку оформлення платформи; `embed` відкриває спливне вікно оформлення поверх вашої сторінки |
| `checkoutInvoice` | Відкриває наявний рахунок |
| `formatMoney(cents, currency)` | Форматує ціну |
| `bind` | Повторно сканує сторінку після додавання розмітки |
| `on`, `off` | Події `papelship:*` |

```js theme={"system"}
PapelShip.products.list({ limit: 8, sort: 'newest' }).then(function (items) {
  var grid = document.getElementById('grid')
  items.forEach(function (p) {
    var a = document.createElement('a')
    a.href = p.url
    a.textContent = p.title + ' ' + PapelShip.formatMoney(p.price_cents, p.currency)
    grid.appendChild(a)
  })
})
```

## Компоненти

Меню **Insert component** редактора коду вставляє готовий код, який можна редагувати: сітка товарів, картка товару, сторінка товару, ціна, кнопка купівлі, додавання в кошик, лічильник кошика, бічна панель кошика, вбудоване оформлення замовлення та список колекцій. Натисніть на компонент у попередньому перегляді, щоб знову змінити його налаштування.

## Сторінки магазину

Оформлення замовлення, кошик, вхід, обліковий запис і відстеження замовлень рендеряться всередині вашого дизайну з макетом, який ви обираєте в панелі. Щоб оформити їх самостійно, додайте `pages/checkout.liquid`, `pages/cart.liquid`, `pages/login.liquid`, `pages/account.liquid` або `pages/track.liquid` (або `.html`) рівно з одним заблокованим блоком, наприклад `<div data-app-block="checkout_form"></div>`. Блоки перелічено в розділі [Сторінки платформи](https://developers.papelship.com/uk/themes/liquid.md#сторінки-платформи).

> [!NOTE]
>
> Клієнти завжди оплачують на сторінці оформлення PapelShip або в її вбудованому спливному вікні. Дизайни не можуть замінити оформлення замовлення або збирати дані картки.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.