` | Текст внутри элемента |
| `"image"` | `![]()
` | Картинку (`src`) — загрузка файла или URL |
| `"link"` | `` | Ссылку (`href`) + текст кнопки |
| `"group"` | `
`, `` | Группу целиком (для скрытия) |
#### 2.2. `data-field` — уникальный ID поля
**Обязателен для всех элементов с `data-editable`.** Должен быть уникальным в пределах шаблона.
```html
```
#### 2.5. `data-text` — для ссылок с раздельным текстом
Если у `` есть `data-editable="link"`, можно указать `data-text="имя-поля"` чтобы текст кнопки и URL редактировались отдельно.
```html
📷 İzlə
```
Если `data-text` НЕ указан — текст кнопки тоже можно редактировать (автоматически).
---
### 3. Как работает редактор для пользователя
```
1. Пользователь открывает страницу в редакторе
2. Видит HTML-дизайн как есть (все стили работают)
3. Наводит на текст → синяя обводка
4. Кликает → всплывает плашка «✏️ Redaktə et»
5. Нажимает → модальное окно с полем ввода
6. Меняет текст → «Tətbiq et» → изменения сразу в превью
7. Для картинок: клик → «🖼 Şəkli dəyiş» → выбор файла
8. Для ссылок: клик → «🔗 Redaktə et» → модалка с URL + текст
9. Кнопка «💾 Saxla» сохраняет всё
```
Визуальные подсказки в редакторе:
- **Синий пунктир** — редактируемый текст или ссылка
- **Оранжевый пунктир** — редактируемая картинка
- **Оранжевый пунктир вокруг блока** — скрытая группа
---
### 4. Требования к HTML
#### 4.1. DOCTYPE и кодировка
```html
Название шаблона
```
**`` используется как название шаблона** при загрузке.
#### 4.2. Стили — внутри `<style>`, не внешние
```html
<!-- ✅ Правильно: стили внутри HTML -->
<style>
body { background: #111; color: #fff; }
.hero { padding: 40px 20px; }
</style>
<!-- ❌ Неправильно: внешние файлы не загрузятся -->
<link rel="stylesheet" href="style.css">
```
#### 4.3. Шрифты — системные
```css
/* ✅ Правильно: системные шрифты */
body { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; }
/* ⚠️ Можно но не гарантировано: Google Fonts через @import */
@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@400;600;700&display=swap');
body { font-family: 'Montserrat', sans-serif; }
/* ❌ Неправильно: <link> может не сработать */
<link href="https://fonts.googleapis.com/..." rel="stylesheet">
```
#### 4.4. Картинки
```html
<!-- ✅ Путь assets/... — сервер заменит на URL -->
<img src="assets/photo.jpg" data-editable="image" data-field="img1">
<!-- ✅ Можно и внешний URL -->
<img src="https://example.com/photo.jpg" data-editable="image" data-field="img1">
<!-- ❌ Локальные пути вне assets/ не обработаются -->
<img src="../photo.jpg">
```
#### 4.5. Размеры
Оптимальная ширина: **480px** (мобильный экран). Но можно любую — iframe растянет.
```css
body {
max-width: 480px;
margin: 0 auto;
}
```
#### 4.6. Чего избегать
| Избегать | Почему |
|----------|--------|
| `<link rel="stylesheet">` | Не загрузится |
| `<script>` | Не выполнится |
| `<form>`, `<input>` | Не нужны |
| CSS `position: fixed` | Внутри iframe ведёт себя странно |
| `@font-face` с локальными путями | Не загрузится |
| `<base href="...">` | Сломает пути |
---
### 5. Полный пример
Файл `docs/template-example-html/index.html` в проекте — рабочий пример тёмного портфолио со всеми типами элементов.
---
### 6. Чеклист перед загрузкой
- [ ] ZIP содержит `index.html` в корне (не в папке)
- [ ] `thumbnail.png` в корне ZIP
- [ ] Все картинки в `assets/`, пути в HTML: `assets/имя.jpg`
- [ ] Все редактируемые элементы имеют `data-editable` + `data-field`
- [ ] `data-field` уникальны в пределах шаблона
- [ ] Стили внутри `<style>`, не внешние файлы
- [ ] Шрифты системные (или Google Fonts через `@import`)
- [ ] Нет `<script>`, `<form>`, `<link rel="stylesheet">`
- [ ] HTML валидный (закрыты все теги)
- [ ] Размер ZIP до 20 МБ
---
## Тип 2: Блоковые шаблоны (blocks)
## Общая концепция (блоки)
Шаблон — это готовый дизайн мини-сайта в формате ZIP-архива. Админ загружает шаблон, пользователь выбирает его, меняет текст/фото под себя и публикует.
Пользователь может только:
- ✏️ Менять текст
- 🖼 Заменять изображения на свои
- 🙈 Скрывать ненужные блоки
Пользователь НЕ может: менять дизайн, шрифты, цвета, порядок блоков, добавлять/удалять блоки.
---
## Структура ZIP-архива
```
мой-шаблон.zip
├── template.json # Главный файл — описание и блоки
├── thumbnail.png # Превью-картинка (обязательно, до 2 МБ)
└── assets/ # Папка с изображениями (опционально)
├── hero-bg.jpg # Фон шапки
├── about-me.jpg # Фото для секции «О себе»
└── product-1.png # Картинка товара
```
---
## template.json — полная структура
```json
{
"name": "Modern Portfolio",
"description": "Чистый и стильный сайт-портфолио для фотографов и дизайнеров",
"category": "Portfolio",
"tags": ["tünd", "minimal", "şəkillər", "portfolio"],
"theme_settings": {
"bg_color": "#111827",
"text_color": "#f9fafb",
"accent_color": "#6366f1",
"font_family": "inter"
},
"blocks": [
...блоки...
]
}
```
### Поля template.json
| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `name` | string | Да | Название шаблона (показывается в галерее) |
| `description` | string | Нет | Краткое описание (под названием в галерее) |
| `category` | string | Нет | Категория для фильтра: `Portfolio`, `Business`, `Restaurant`, `Shop`, `Personal`, `Event`, `Blog` |
| `tags` | array | Нет | Теги для поиска (массив строк) |
| `theme_settings` | object | Нет | Тема страницы (цвета, шрифт) |
| `blocks` | array | Да | Массив блоков — сам контент страницы |
---
## Рекомендуемые категории и теги
### Категории
| Категория | Для каких страниц |
|-----------|-------------------|
| `Portfolio` | Портфолио, резюме, визитки |
| `Business` | Компании, услуги, консалтинг |
| `Restaurant` | Рестораны, кафе, меню |
| `Shop` | Магазины, витрины товаров |
| `Personal` | Личные страницы, блоги |
| `Event` | Свадьбы, мероприятия, анонсы |
| `Blog` | Блоги, статьи, новости |
### Рекомендуемые теги
| Тег | Значение |
|-----|----------|
| `tünd` | Тёмная тема |
| `açıq` | Светлая тема |
| `rəngli` | Яркий, цветной дизайн |
| `minimal` | Минималистичный |
| `şəkillər` | Много картинок |
| `video` | С видео-фоном |
| `portfolio` | Для портфолио |
| `vizitka` | Для визитки |
| `restoran` | Для ресторана |
| `mağaza` | Для магазина |
| `toy` | Для свадьбы |
Можно использовать любые свои теги на азербайджанском — они станут фильтрами в галерее.
---
## Блоки и как отмечать редактируемые поля
### Как работает `_editable`
Внутри `data` каждого блока есть поле `_editable`. В нём перечислены поля, которые пользователь сможет редактировать:
```json
{
"type": "heading",
"data": {
"text": "Mənim Portfolio",
"fontSize": 36,
"align": "center",
"_editable": {
"text": true
}
}
}
```
Здесь `"text": true` значит: пользователь видит поле ввода «Mətn» и может поменять `"Mənim Portfolio"` на свой заголовок.
`fontSize` и `align` НЕ в `_editable` — пользователь их не видит и не меняет.
### Правило
> В `_editable` отмечаем ТОЛЬКО контентные поля. Дизайн-поля (размеры, цвета, шрифты, отступы) НЕ отмечаем — они фиксированы шаблоном.
---
## Типы блоков и их редактируемые поля
### 1. `avatar` — Аватар / Шапка профиля
```json
{
"id": "hero-1",
"type": "avatar",
"order": 0,
"data": {
"style": "2",
"image_url": "assets/hero-bg.jpg",
"title": "Sənin Adın",
"bio": "Fotoqraf | Dizayner",
"bg_color": "#4f46e5",
"_editable": {
"image_url": true,
"title": true,
"bio": true
}
}
}
```
| Поле | Что можно отметить | Тип ввода |
|------|-------------------|-----------|
| `image_url` | Фото профиля | Загрузка файла + URL |
| `title` | Заголовок / Имя | Текст |
| `bio` | Био / Подпись | Многострочный текст |
| `bg_image` | Фоновое изображение (для style 2, 3) | Загрузка файла |
Стили `avatar`:
- `"1"` — круглое фото + заголовок + био (по центру)
- `"2"` — фон-блок + круглое фото поверх + заголовок + био
- `"3"` — фон-блок + фото справа + заголовок/био слева
- `"4"` — широкий блок с фото на весь фон + заголовок/био снизу
---
### 2. `heading` — Заголовок
```json
{
"id": "title-1",
"type": "heading",
"order": 1,
"data": {
"text": "Mənim işlərim",
"fontSize": 28,
"align": "center",
"_editable": { "text": true }
}
}
```
| Поле | Тип ввода |
|------|-----------|
| `text` | Текст (одна строка) |
---
### 3. `text` — Текст
```json
{
"id": "about-1",
"type": "text",
"order": 2,
"data": {
"text": "<p>Burada özün haqqında yaza bilərsən.</p>\n<p>Mətn <strong>HTML</strong> formatında ola bilər.</p>",
"fontSize": 15,
"fontFamily": "Montserrat",
"align": "left",
"color": "#374151",
"_editable": { "text": true }
}
}
```
| Поле | Тип ввода | Примечание |
|------|-----------|------------|
| `text` | Многострочный текст | Можно использовать HTML: `<p>`, `<strong>`, `<em>`, `<br>` |
**Важно:** если указываете `"text"` в `_editable`, используйте ключ `"text"` (не `"html"`). Поле `"html"` тоже поддерживается для обратной совместимости.
---
### 4. `button_link` — Кнопка / Ссылка
```json
{
"id": "btn-1",
"type": "button_link",
"order": 3,
"data": {
"text": "Portfolio",
"url": "https://",
"action": "website",
"icon": "📷",
"descr": "Bütün işlərim",
"titleColor": "#ffffff",
"bgColor": "#6366f1",
"borderRadius": 12,
"shadow": "md",
"animation": "none",
"_editable": {
"text": true,
"url": true,
"descr": true
}
}
}
```
| Поле | Что можно отметить | Тип ввода |
|------|-------------------|-----------|
| `text` | Текст на кнопке | Текст |
| `url` | Ссылка (URL) | Текст (URL) |
| `descr` | Подпись под кнопкой | Текст |
Типы `action`:
- `"website"` — обычная ссылка
- `"call"` — звонок (`tel:`)
- `"whatsapp"` — WhatsApp
- `"email"` — почта (`mailto:`)
---
### 5. `image` — Изображение
```json
{
"id": "img-1",
"type": "image",
"order": 4,
"data": {
"url": "assets/about-me.jpg",
"alt": "Mənim şəkil",
"borderRadius": 12,
"shadow": "lg",
"maxHeight": 400,
"_editable": {
"url": true,
"alt": true
}
}
}
```
| Поле | Тип ввода |
|------|-----------|
| `url` | Загрузка файла + URL |
| `alt` | Текст (описание) |
---
### 6. `video` — Видео (YouTube)
```json
{
"id": "vid-1",
"type": "video",
"order": 5,
"data": {
"url": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
"title": "Mənim videom",
"_editable": {
"url": true,
"title": true
}
}
}
```
| Поле | Тип ввода | Примечание |
|------|-----------|------------|
| `url` | Текст (URL) | Только YouTube |
| `title` | Текст | Заголовок над видео |
---
### 7. `social_links` — Социальные сети
```json
{
"id": "social-1",
"type": "social_links",
"order": 6,
"data": {
"links": [
{ "platform": "instagram", "username": "your.insta" },
{ "platform": "telegram", "username": "your_tg" },
{ "platform": "youtube", "username": "@your_channel" },
{ "platform": "whatsapp", "username": "+994501234567" }
],
"design": "1",
"iconSize": 22,
"borderRadius": 12,
"shadow": "none",
"_editable": {
"links": true
}
}
}
```
| Поле | Тип ввода | Примечание |
|------|-----------|------------|
| `links` | Список username'ов | Пользователь меняет только username, платформы фиксированы |
Дизайны (`design`):
- `"1"` — вертикальные кнопки с иконкой и текстом
- `"2"` — сетка иконок 4 в ряд (на белом фоне)
- `"3"` — сетка иконок 4 в ряд (обводка)
Доступные платформы: `instagram`, `telegram`, `youtube`, `tiktok`, `facebook`, `whatsapp`, `website`, `phone`, `email`
---
### 8. `faq` — Вопрос-ответ
```json
{
"id": "faq-1",
"type": "faq",
"order": 7,
"data": {
"items": [
{ "question": "Qiymət nə qədərdir?", "answer": "Qiymət fərdi olaraq hesablanır." },
{ "question": "Nə vaxt hazır olur?", "answer": "Adətən 3-5 iş günü." },
{ "question": "Ödəniş üsulları?", "answer": "Nağd və kartla ödəniş qəbul edirik." }
],
"iconPos": "right",
"iconType": "plus",
"fontFamily": "Arial",
"textColor": "#111827",
"bgColor": "#f9fafb",
"borderRadius": 12,
"_editable": {
"items": true
}
}
}
```
| Поле | Тип ввода | Примечание |
|------|-----------|------------|
| `items` | Список вопрос-ответ | Каждый элемент: `question` (текст) + `answer` (многострочный) |
---
### 9. `spacer` — Отступ
```json
{
"id": "space-1",
"type": "spacer",
"order": 8,
"data": {
"height": 40
}
}
```
Пустой блок-отступ. `_editable` не нужен (только скрытие).
---
### 10. `divider` — Разделитель
```json
{
"id": "div-1",
"type": "divider",
"order": 9,
"data": {}
}
```
Линия-разделитель. `_editable` не нужен (только скрытие).
---
### 11. `custom_canvas` — Свободная сетка
```json
{
"id": "canvas-1",
"type": "custom_canvas",
"order": 10,
"data": {
"rowHeight": 36,
"cols": 12,
"elements": [
{
"id": "el-1",
"type": "heading",
"x": 0, "y": 0, "w": 12, "h": 2,
"data": { "text": "Qiymətlər", "fontSize": 24, "align": "center", "color": "#111827" }
},
{
"id": "el-2",
"type": "text",
"x": 0, "y": 2, "w": 6, "h": 3,
"data": { "text": "Standart paket\n<b>50 AZN</b>", "fontSize": 14, "align": "center", "color": "#374151" }
},
{
"id": "el-3",
"type": "text",
"x": 6, "y": 2, "w": 6, "h": 3,
"data": { "text": "Premium paket\n<b>100 AZN</b>", "fontSize": 14, "align": "center", "color": "#374151" }
},
{
"id": "el-4",
"type": "image",
"x": 0, "y": 5, "w": 12, "h": 4,
"data": { "url": "assets/product-1.png", "borderRadius": 8 }
}
],
"_editable": {
"elements": true
}
}
}
```
| Поле | Тип ввода | Примечание |
|------|-----------|------------|
| `elements` | Текст каждого элемента | Для каждого элемента: `text` (heading/text) и `url` (image) |
---
## Сквозные возможности
### Скрытие блока
Каждый блок можно скрыть. Пользователь видит переключатель «Bloku gizlət» в боковой панели. Это работает для всех типов блоков без всяких настроек в `_editable`.
### Общие настройки блоков (НЕ редактируются пользователем)
Эти поля можно задать в `data` блока, но они не входят в `_editable`:
| Поле | Описание |
|------|----------|
| `_hidden` | По умолчанию скрыт (`true`/`false`) |
| `_bgColor` | Цвет фона блока |
| `_pt` | Отступ сверху (px) |
| `_pb` | Отступ снизу (px) |
| `_label` | Имя блока (для админа) |
| `_scheduleStart` / `_scheduleEnd` | Показ по расписанию |
| `_daysOfWeek` | Показ по дням недели |
---
## Как использовать изображения
### Из assets/ папки
Положите картинки в `assets/` внутри ZIP и ссылайтесь на них по относительному пути:
```json
"image_url": "assets/hero-bg.jpg"
```
При загрузке сервер скопирует файлы в `/photo/templates/` и заменит пути на абсолютные URL.
### Внешние URL
Можно сразу указать внешнюю ссылку:
```json
"image_url": "https://example.com/photo.jpg"
```
---
## Полный пример template.json
```json
{
"name": "Fotoqraf Portfolio",
"description": "Tünd dizaynlı portfolio şablonu. Fotoqraflar və dizaynerlər üçün idealdır.",
"category": "Portfolio",
"tags": ["tünd", "şəkillər", "minimal", "portfolio"],
"theme_settings": {
"bg_color": "#0f172a",
"text_color": "#e2e8f0",
"accent_color": "#f59e0b",
"font_family": "inter"
},
"blocks": [
{
"id": "hero",
"type": "avatar",
"order": 0,
"data": {
"style": "1",
"image_url": "assets/profile.jpg",
"title": "Sənin Adın",
"bio": "Fotoqraf | Kreativ rejissor",
"_editable": { "image_url": true, "title": true, "bio": true }
}
},
{
"id": "about-title",
"type": "heading",
"order": 1,
"data": {
"text": "Haqqımda",
"fontSize": 24,
"align": "center",
"_editable": { "text": true }
}
},
{
"id": "about-text",
"type": "text",
"order": 2,
"data": {
"text": "<p>Burada özün haqqında məlumat yaza bilərsən.</p>",
"fontSize": 15,
"fontFamily": "Montserrat",
"align": "center",
"color": "#94a3b8",
"_editable": { "text": true }
}
},
{
"id": "works-title",
"type": "heading",
"order": 3,
"data": {
"text": "İşlərim",
"fontSize": 24,
"align": "center",
"_editable": { "text": true }
}
},
{
"id": "work-1",
"type": "image",
"order": 4,
"data": {
"url": "assets/work-sample.jpg",
"alt": "İş nümunəsi",
"borderRadius": 16,
"shadow": "lg",
"maxHeight": 500,
"_editable": { "url": true, "alt": true }
}
},
{
"id": "work-2",
"type": "image",
"order": 5,
"data": {
"url": "assets/work-sample-2.jpg",
"alt": "İş nümunəsi 2",
"borderRadius": 16,
"shadow": "lg",
"maxHeight": 500,
"_editable": { "url": true, "alt": true }
}
},
{
"id": "contact-title",
"type": "heading",
"order": 6,
"data": {
"text": "Əlaqə",
"fontSize": 24,
"align": "center",
"_editable": { "text": true }
}
},
{
"id": "contact-btn",
"type": "button_link",
"order": 7,
"data": {
"text": "Əlaqə saxla",
"url": "https://wa.me/994501234567",
"action": "whatsapp",
"icon": "💬",
"descr": "WhatsApp-da yazın",
"titleColor": "#ffffff",
"bgColor": "#f59e0b",
"borderRadius": 14,
"shadow": "md",
"animation": "none",
"_editable": { "text": true, "url": true, "descr": true }
}
},
{
"id": "social",
"type": "social_links",
"order": 8,
"data": {
"links": [
{ "platform": "instagram", "username": "your.login" },
{ "platform": "telegram", "username": "your_channel" },
{ "platform": "youtube", "username": "@your" }
],
"design": "2",
"iconSize": 28,
"borderRadius": 16,
"shadow": "none",
"_editable": { "links": true }
}
}
]
}
```
---
## Чеклист перед загрузкой
- [ ] ZIP содержит `template.json` в корне
- [ ] `template.json` — валидный JSON (без запятых в конце массивов)
- [ ] Есть `thumbnail.png` (или .jpg/.webp) в корне ZIP
- [ ] Все картинки из `assets/` реально используются в блоках
- [ ] У каждого блока есть `id` и `type` и `order`
- [ ] `_editable` содержит только допустимые поля для данного типа блока
- [ ] Категория и теги заполнены (для фильтров в галерее)
- [ ] Размер ZIP не превышает 20 МБ
Başlıq
Təsvir
...
...
``` Именуй понятно: `hero-title`, `about-text`, `gallery-img-1`, `btn-whatsapp`. #### 2.3. `data-label` — название в интерфейсе Показывается в тултипе и модальном окне при редактировании. ```html