iwgt 2.3.0

package/dist/data/references/collections-menu-patterns.json

@@ -0,0 +1,306 @@
+{
+    "title": "Collections Menu Patterns Reference",
+    "description": "Паттерны для генерации меню категорий в виджетах InSales",
+    "version": "1.0.0",
+    "patterns": [
+        {
+            "id": "two_level_hierarchical",
+            "name": "Двухуровневое иерархическое меню",
+            "description": "Меню с двумя уровнями: основные категории и подкатегории",
+            "useCase": "Идеально для шапок сайта, где нужно показать основные категории с их подкатегориями",
+            "structure": "root_category.subcollections -> subcollections",
+            "cacheKeyPattern": "cache_menu_key_{{ widget_drop.list_item_id }}_{{ collections.last_updated_at }}_{{ language.locale }}_{{ custom_params }}",
+            "requiredSettings": [
+                {
+                    "handle": "subcollections-items-limit",
+                    "type": "to_integer",
+                    "default": 10,
+                    "description": "Ограничение количества подкатегорий для отображения"
+                },
+                {
+                    "handle": "hide-menu-photo",
+                    "type": "checkbox",
+                    "default": false,
+                    "description": "Скрыть фотографии категорий"
+                },
+                {
+                    "handle": "hide-counts",
+                    "type": "checkbox",
+                    "default": false,
+                    "description": "Скрыть счетчики товаров"
+                }
+            ],
+            "liquidCode": "{% assign subcollections_items_limit = widget_settings.subcollections-items-limit | to_integer %}\n{% capture cache_menu_key %}cache_menu_key_{{ collections.last_updated_at }}_{{ language.locale }}_{{ widget_settings.hide-menu-photo }}_{{ widget_settings.subcollections-items-limit }}{% endcapture %}\n\n<ul class=\"menu\" data-navigation data-subcollections-items-limit={{subcollections_items_limit}}>\n  {% cache cache_menu_key %}\n  {% assign level_1 = collections.root_category.subcollections %}\n  {% for level_1_item in level_1 %}\n    {% assign level_2 = level_1_item.subcollections %}\n    \n    <li class=\"menu__item is-level-1\" data-navigation-item>\n      <div class=\"menu__controls\">\n        <a href=\"{{ level_1_item.url }}\" class=\"menu__link\" data-navigation-link=\"{{ level_1_item.url }}\">\n          {{ level_1_item.title }}\n        </a>\n        \n        {% if level_2.size > 0 %}\n          <button class=\"menu__show-submenu-btn\" type=\"button\">\n            <i class=\"icon icon-angle-down\"></i>\n          </button>\n        {% endif %}\n      </div>\n      \n      {% if level_2.size > 0 %}\n        <ul class=\"menu__submenu\" data-navigation-submenu>\n          {% for level_2_item in level_2 %}\n            <li class=\"menu__item {%if forloop.index > subcollections_items_limit %}is-hide{% endif%}\" data-navigation-item>\n              <div class=\"menu__controls\">\n                <a href=\"{{ level_2_item.url }}\" class=\"menu__link\" data-navigation-link=\"{{ level_2_item.url }}\">\n                  {{ level_2_item.title }}\n                  {% if editor_mode? or widget_settings.hide-counts != true %}\n                    {% if level_2_item.products_count > 0 %}\n                      <span class=\"menu__item-count\">{{ level_2_item.products_count }}</span>\n                    {% endif %}\n                  {% endif %}\n                </a>\n              </div>\n            </li>\n          {% endfor %}\n        </ul>\n      {% endif %}\n    </li>\n  {% endfor %}\n  {% endcache %}\n</ul>",
+            "features": [
+                "Кеширование меню",
+                "Поддержка фотографий категорий с fallback",
+                "Ограничение количества подкатегорий",
+                "Счетчики товаров",
+                "Data-атрибуты для JavaScript навигации"
+            ]
+        },
+        {
+            "id": "multi_level_flatten",
+            "name": "Многоуровневое меню через flatten_branch",
+            "description": "Меню с поддержкой произвольной глубины вложенности через flatten_branch",
+            "useCase": "Для сайдбаров, мобильных меню, где нужна глубокая иерархия",
+            "structure": "root_category.flatten_branch с контролем уровней",
+            "cacheKeyPattern": "cache_menu_key_{{ widget_drop.list_item_id }}_{{ collections.last_updated_at }}_{{ language.locale }}_{{ level_limit }}",
+            "requiredSettings": [
+                {
+                    "handle": "level-limit",
+                    "type": "to_integer",
+                    "default": 3,
+                    "description": "Максимальная глубина вложенности меню"
+                }
+            ],
+            "liquidCode": "{% assign level_limit = widget_settings.level-limit | default: 3 | to_integer %}\n{% capture cache_menu_key %}cache_menu_key_{{ collections.last_updated_at }}_{{ language.locale }}_{{ level_limit }}{% endcapture %}\n{% assign prev_link_level = 1 %}\n\n<ul class=\"menu\" data-navigation>\n  {% cache cache_menu_key %}\n  {% assign root_level = collections.root_category.level %}\n  {% for link in collections.root_category.flatten_branch %}\n    {% assign node_level = link.level | minus: root_level %}\n    {% assign _in_limit = level_limit | minus: node_level %}\n    {% assign _next_level_in_limit = _in_limit | minus: 1 %}\n    \n    {% assign show_level = false %}\n    {% if _in_limit >= 0 %}\n      {% assign show_level = true %}\n    {% endif %}\n    \n    {% assign show_next_level = false %}\n    {% if link.subcollections.size > 0 and _next_level_in_limit >= 0 %}\n      {% assign show_next_level = true %}\n    {% endif %}\n    \n    {% if show_level %}\n      {% assign level_difference = prev_link_level | minus: link.level | plus: root_level %}\n      \n      {% if level_difference > 0 %}\n        {% for i in (1..level_difference) %}\n          {% unless forloop.first %}</li>{% endunless %}\n          </ul>\n        {% endfor %}\n        </li>\n      {% endif %}\n      \n      <li class=\"menu__item\" data-navigation-item>\n        <div class=\"menu__controls {% if show_next_level %}with-submenu{% endif %}\">\n          <a href=\"{{ link.url }}\" class=\"menu__link\" data-navigation-link=\"{{ link.url }}\">\n            {{ link.title }}\n          </a>\n          \n          {% if show_next_level %}\n            <button class=\"menu__show-submenu-btn\" type=\"button\">\n              <i class=\"icon icon-angle-down\"></i>\n            </button>\n          {% endif %}\n        </div>\n        \n        {% if show_next_level %}\n          <ul class=\"menu__submenu\" data-navigation-submenu>\n        {% endif %}\n        \n        {% assign prev_link_level = node_level %}\n        \n        {% unless show_next_level %}\n          </li>\n        {% endunless %}\n        \n        {% if forloop.last %}\n          {% assign prev_link_level = node_level | minus: 1 %}\n          {% for i in (1..prev_link_level) %}\n            </ul>\n          {% endfor %}\n        {% endif %}\n    {% endif %}\n  {% endfor %}\n  {% endcache %}\n</ul>",
+            "features": [
+                "Произвольная глубина вложенности",
+                "Контроль отображаемых уровней",
+                "Автоматическое построение дерева",
+                "Оптимальное для больших каталогов"
+            ]
+        },
+        {
+            "id": "simple_subcollections",
+            "name": "Простое меню подкатегорий",
+            "description": "Одноуровневый список подкатегорий выбранной категории",
+            "useCase": "Для страниц категорий, навигационных блоков в контенте",
+            "structure": "collections[handle].subcollections",
+            "cacheKeyPattern": "cache_menu_key_{{ widget_drop.list_item_id }}_{{ collections.last_updated_at }}_{{ language.locale }}_{{ collection_handle }}",
+            "requiredSettings": [
+                {
+                    "handle": "collection-handle",
+                    "type": "string",
+                    "default": "",
+                    "description": "Handle категории (по умолчанию root_category)"
+                }
+            ],
+            "liquidCode": "{% capture cache_menu_key %}cache_menu_key_{{ collections.last_updated_at }}_{{ language.locale }}_{{ widget_settings.collection-handle }}{% endcapture %}\n{% cache cache_menu_key %}\n  {% assign source_handle = widget_settings.collection-handle | default: collections.root_category.handle %}\n  {% assign collection_list = collections[source_handle].subcollections %}\n  {% if collection_list.size > 0 %}\n    <div class=\"menu-wrapper\">\n      <ul class=\"menu\" data-navigation>\n        {% for collection_item in collection_list %}\n          <li class=\"menu__item\" data-navigation-item>\n            <div class=\"menu__controls\">\n              <a href=\"{{ collection_item.url }}\" class=\"menu__link\" data-navigation-link=\"{{ collection_item.url }}\">\n                {{ collection_item.title }}\n              </a>\n            </div>\n          </li>\n        {% endfor %}\n      </ul>\n    </div>\n  {% endif %}\n{% endcache %}",
+            "features": [
+                "Простая структура",
+                "Выбор родительской категории",
+                "Минимальный код",
+                "Быстрое отображение"
+            ]
+        },
+        {
+            "id": "flat_collections_list",
+            "name": "Плоский список всех категорий",
+            "description": "Простой список всех категорий магазина",
+            "useCase": "Для простых каталогов, лендингов",
+            "structure": "collections (все категории)",
+            "cacheKeyPattern": "cache_menu_key_{{ widget_drop.list_item_id }}_{{ collections.last_updated_at }}_{{ language.locale }}",
+            "requiredSettings": [],
+            "liquidCode": "{% capture cache_menu_key %}cache_menu_key_{{ collections.last_updated_at }}_{{ language.locale }}{% endcapture %}\n{% cache cache_menu_key %}\n  {% if collections.root_category.subcollections.size > 0 %}\n    <div class=\"menu-wrapper\" data-navigation>\n      {% for collection in collections %}\n        {% if collection.products_count > 0 %}\n          <div class=\"menu__item\" data-navigation-item>\n            <a class=\"menu__link\" href=\"{{ collection.url }}\" data-navigation-link=\"{{ collection.url }}\">\n              <span class=\"menu__title\">{{ collection.title }}</span>\n            </a>\n          </div>\n        {% endif %}\n      {% endfor %}\n    </div>\n  {% endif %}\n{% endcache %}",
+            "features": [
+                "Максимально простая структура",
+                "Только категории с товарами",
+                "Без иерархии",
+                "Легкий в стилизации"
+            ]
+        },
+        {
+            "id": "tree_structure_flatten",
+            "name": "Древовидная структура через collections.flatten",
+            "description": "Полное дерево категорий с автоматическим построением через collections.flatten",
+            "useCase": "Для полных каталогов, карт сайта",
+            "structure": "collections.flatten с level_difference",
+            "cacheKeyPattern": "cache_menu_key_{{ widget_drop.list_item_id }}_{{ collections.last_updated_at }}_{{ language.locale }}",
+            "requiredSettings": [],
+            "liquidCode": "{% capture cache_menu_key %}cache_menu_key_{{ collections.last_updated_at }}_{{ language.locale }}{% endcapture %}\n{% cache cache_menu_key %}\n  {% for collection in collections.flatten %}\n    {% if collection.first? %}<ul class=\"menu\" data-navigation>{% endif %}\n    {% if collection.show? %}\n      <li class=\"menu__item\" data-navigation-item>\n        <a href=\"{{ collection.url }}\" class=\"menu__link\" data-navigation-link=\"{{ collection.url }}\">\n          {{ collection.title }}\n        </a>\n      </li>\n    {% endif %}\n    {% if collection.last? %}\n      {% for i in (1..collection.level_difference) %}</ul>{% endfor %}\n    {% endif %}\n  {% endfor %}\n{% endcache %}",
+            "features": [
+                "Полное автоматическое дерево",
+                "Работа с level_difference",
+                "Методы first? и last?",
+                "Подходит для полных каталогов"
+            ]
+        }
+    ],
+    "commonPatterns": {
+        "cacheKey": {
+            "description": "Формирование ключа кеша для меню",
+            "template": "{% capture cache_menu_key %}cache_menu_key_{{ prefix }}_{{ collections.last_updated_at }}_{{ language.locale }}_{{ custom_params }}{% endcapture %}",
+            "requiredVariables": [
+                "collections.last_updated_at",
+                "language.locale"
+            ],
+            "explanation": "collections.last_updated_at автоматически обновит кеш при изменении категорий, language.locale обеспечит корректное кеширование для разных языков"
+        },
+        "imageFallback": {
+            "description": "Fallback для изображений категорий",
+            "code": "{% if collection.image.original_url contains 'no_image' %}\n  {% if collection.products_count > 0 %}\n    {% assign collection_first_product = collection.products | first %}\n    {% if collection_first_product.images.size > 0 %}\n      {% assign collection_photo = collection_first_product.first_image %}\n    {% else %}\n      {% assign collection_photo = collection.image %}\n    {% endif %}\n  {% else %}\n    {% assign collection_photo = collection.image %}\n  {% endif%}\n{% else %}\n  {% assign collection_photo = collection.image %}\n{% endif %}",
+            "explanation": "Использует первое изображение товара, если у категории нет собственного изображения"
+        },
+        "levelControl": {
+            "description": "Контроль глубины отображения меню",
+            "code": "{% assign level_limit = 3 %}\n{% assign _in_limit = level_limit | minus: node_level %}\n{% if _in_limit >= 0 %}\n  <!-- show item -->\n{% endif %}",
+            "explanation": "Ограничивает глубину отображения, предотвращая слишком глубокую вложенность"
+        },
+        "subcollectionsLimit": {
+            "description": "Ограничение количества подкатегорий",
+            "code": "{% assign subcollections_items_limit = widget_settings.subcollections-items-limit | to_integer %}\n{% for level_2_item in level_2 %}\n  <li class=\"menu__item {%if forloop.index > subcollections_items_limit %}is-hide{% endif%}\">\n    <!-- item -->\n  </li>\n{% endfor %}",
+            "explanation": "Скрывает подкатегории сверх лимита через CSS класс is-hide"
+        },
+        "productsCount": {
+            "description": "Отображение счетчика товаров",
+            "code": "{% if editor_mode? or widget_settings.hide-counts != true %}\n  {% if collection.products_count > 0 %}\n    <span class=\"menu__item-count\">{{ collection.products_count }}</span>\n  {% endif %}\n{% endif %}",
+            "explanation": "Показывает количество товаров с учетом настроек и режима редактирования"
+        }
+    },
+    "collectionMethods": {
+        "description": "Методы и свойства категорий для использования в меню",
+        "methods": [
+            {
+                "name": "level",
+                "description": "Уровень вложенности категории",
+                "example": "{{ collection.level }}",
+                "usage": "Для определения глубины и построения иерархии"
+            },
+            {
+                "name": "handle",
+                "description": "Уникальный идентификатор категории",
+                "example": "{{ collection.handle }}",
+                "usage": "Для ссылок и идентификации"
+            },
+            {
+                "name": "title",
+                "description": "Название категории",
+                "example": "{{ collection.title }}",
+                "usage": "Отображение в меню"
+            },
+            {
+                "name": "id",
+                "description": "ID категории",
+                "example": "{{ collection.id }}",
+                "usage": "Для data-атрибутов"
+            },
+            {
+                "name": "url",
+                "description": "URL категории",
+                "example": "{{ collection.url }}",
+                "usage": "Ссылки в меню"
+            },
+            {
+                "name": "image",
+                "description": "Изображение категории",
+                "example": "{{ collection.image }}",
+                "usage": "Отображение картинок в меню"
+            },
+            {
+                "name": "products_count",
+                "description": "Количество товаров в категории",
+                "example": "{{ collection.products_count }}",
+                "usage": "Показ счетчиков товаров"
+            },
+            {
+                "name": "subcollections",
+                "description": "Подкатегории",
+                "example": "{{ collection.subcollections }}",
+                "usage": "Построение иерархии"
+            },
+            {
+                "name": "flatten_branch",
+                "description": "Плоский список всех подкатегорий",
+                "example": "{{ collection.flatten_branch }}",
+                "usage": "Для многоуровневых меню"
+            },
+            {
+                "name": "first?",
+                "description": "Первая ли категория среди подкатегорий",
+                "example": "{% if collection.first? %}<ul>{% endif %}",
+                "usage": "Для построения дерева (collections.flatten)"
+            },
+            {
+                "name": "last?",
+                "description": "Последняя ли категория среди подкатегорий",
+                "example": "{% if collection.last? %}</ul>{% endif %}",
+                "usage": "Для построения дерева (collections.flatten)"
+            },
+            {
+                "name": "level_difference",
+                "description": "Разница уровней между текущей и предыдущей категорией",
+                "example": "{% for i in (1..collection.level_difference) %}</ul>{% endfor %}",
+                "usage": "Определение количества закрывающих тегов"
+            },
+            {
+                "name": "show?",
+                "description": "Показывать ли категорию",
+                "example": "{% if collection.show? %}<!-- show item -->{% endif %}",
+                "usage": "Условное отображение"
+            }
+        ]
+    },
+    "dataAttributes": {
+        "description": "Data-атрибуты для навигации",
+        "attributes": [
+            {
+                "name": "data-navigation",
+                "usage": "На ul или div контейнере меню",
+                "description": "Основной контейнер навигации"
+            },
+            {
+                "name": "data-navigation-item",
+                "usage": "На li элементах меню",
+                "description": "Элемент навигации"
+            },
+            {
+                "name": "data-navigation-link",
+                "usage": "На a элементах с URL",
+                "description": "Ссылка навигации",
+                "example": "data-navigation-link=\"{{ collection.url }}\""
+            },
+            {
+                "name": "data-navigation-submenu",
+                "usage": "На ul подменю",
+                "description": "Подменю"
+            },
+            {
+                "name": "data-menu-handle",
+                "usage": "На контейнере меню",
+                "description": "Handle меню для связи с настройками"
+            },
+            {
+                "name": "data-menu-item-id",
+                "usage": "На элементах меню",
+                "description": "Уникальный идентификатор элемента"
+            },
+            {
+                "name": "data-subcollections-items-limit",
+                "usage": "На контейнере меню",
+                "description": "Лимит подкатегорий для JavaScript обработки"
+            }
+        ]
+    },
+    "bestPractices": [
+        {
+            "title": "Всегда используйте кеширование",
+            "description": "Меню категорий редко изменяются, кеширование значительно ускоряет загрузку"
+        },
+        {
+            "title": "Включайте collections.last_updated_at в ключ кеша",
+            "description": "Обеспечивает автоматическое обновление кеша при изменении структуры категорий"
+        },
+        {
+            "title": "Включайте language.locale в ключ кеша",
+            "description": "Обеспечивает корректное кеширование для многоязычных сайтов"
+        },
+        {
+            "title": "Используйте data-navigation атрибуты",
+            "description": "Обеспечивает корректную работу JavaScript навигации из библиотеки my-layout"
+        },
+        {
+            "title": "Ограничивайте количество подкатегорий",
+            "description": "Предотвращает перегрузку интерфейса и улучшает UX"
+        },
+        {
+            "title": "Предусматривайте fallback для изображений",
+            "description": "Обеспечивает корректное отображение даже при отсутствии изображений категорий"
+        },
+        {
+            "title": "Контролируйте глубину отображения",
+            "description": "Предотвращает слишком глубокую вложенность и улучшает навигацию"
+        }
+    ]
+}