kit/README.md

wt.core assets source

Источник: https://bitbucket.org/bellord13/kit/

is a dependency wt.core

Репозиторий wt.core: https://bitbucket.org/andreyleoua/wt.core/

Предназначен для асинхронной работы с ресурсами на веб-проектах.

Установка

В директории [php:wt.core] app()->config()->get('templater.path') . '/kit' (по умолчанию /local/templater.dev/kit) выполнить клонирование проекта

git clone https://bellord@bitbucket.org/bellord13/kit.git ./

Термины и определения в контексте фреймворка

Плагин - сущность включающая в себя модуль, js-, css-файлы, шрифты.

Модуль - составляющая плагина, определяемая как основной файл плагина (его наличие не обязательно в плагине)

PluginManager - класс для работы с плагинами

window.kit - объект, который изолирует все плагины

Базовые принципы

✨ Инициализация

Выдержка из плагина core:

manager = new PluginManager(global);
manager.register('PluginManager', {
   alias: 'pm',
   type: MD_TYPE.HMD,
   handler: function(require, exports, module, global) {
      return module.exports = manager;
   }
});
manager.register('config', {
   type: MD_TYPE.HMD,
   handler: function(require, exports, module, global) {
      global.config = Object.assign({}, defaultConfig, config);
    }
});
manager.install('PluginManager');

Создается экземпляр класса PluginManager и регистрирует сам себя. Переменная global выполняем роль фасада для всех установленных плагинов. В качестве глобальной переменной используется window.kit. В паре с менеджером сразу инициализируется config доступный из window.kit.config.

✨ Основные этапы работы с плагином:

этап	метод
Регистрация	register(pluginId, config) или registerPlugins(object)
Загрузка	load(pluginId, callback)
Установка	install(pluginId, callback)
Запрос	require(pluginId, callback)

Примеры регистрации

Пример регистрации Стандартного плагина (Тип default)

__PluginManager__.register('menu', {
   path: kit.config.assetsPath + '/menu',
   module: '/menu.js',
   type: 'loader',
   css: [
      '/menu.css'
   ],
   deps: ['lib', 'align', 'utils']
});

kit.pm.register('UserCart', {
   path: '/assets/plugins/cart/',
   module: 'main.js',
   js: ['jquery.min.js', ['utils.js', 'api.js']], // jquery -> (utils + api вместе)
   css: ['style.css'],
   autoRequire: true
});

Пример регистрации HMD-плагина

kit.pm.register('Logger', {
   type: 'HMD',
   alias: ['AltLogger'],
   handler: function(require, module, exports, global) {
       var object = {
          log: function(msg) { console.log('[Logger]: ' + msg); }
       };
      // kit.require('Logger') вернет module
      module.exports = object;
      // return задает, что определить в global.Logger и global.AltLogger
      return object.log;
   },
   onInstall: function(p) {
      console.log('Logger готов!');
   }
});

Пример регистрации UMD-плагина

kit.pm.register('MyUmdModule', {
   type: 'UMD',
   path: '/js/plugins/',
   module: 'my-plugin.umd.js', // Файл с UMD-оберткой
   deps: ['jquery'],           // Если плагину нужен jQuery
   autoRequire: true,
   onInstall: function(plugin) {
      console.log('UMD модуль успешно инициализирован');
   }
});

Пример регистрации ES-плагина

kit.pm.register('UserDashboard', {
   type: 'ES',                 // Указываем тип ES (ECMAScript)
   path: '/assets/modules/',   // Базовый путь
   module: 'dashboard.js',     // Файл, содержащий "export default"
   autoRequire: true,          // Начать загрузку сразу
   onInstall: function(plugin) {
      // В plugin.module.exports попадет то, что экспортировано из файла
      console.log('ES-модуль загружен:', plugin.module.exports);
   }
});

Особенности работы с типом ES в твоем скрипте:

• Нативная загрузка: Вместо создания обычного тега <script>, менеджер использует динамический импорт import(url).
• Строгий режим: Все ES-модули по умолчанию работают в use strict.
• CORS: Если модули загружаются с другого домена, сервер обязательно должен отдавать заголовок Access-Control-Allow-Origin, иначе браузер заблокирует загрузку.

Описание параметров конфига для плагина

Параметр	Тип	По умолчанию	Описание
type	string	default	Тип плагина.
handler	callback	—	Используется в связке с типом HMD. Имеет вид function(r, m, e, g){m.e = {}; return {};}.
path	string	""	Базовый префикс пути для модуля, скриптов и стилей.
alias	Array string	[]	Псевдонимы для pluginId, доступные в require() и global.
module	string	—	Прямая ссылка на файл с основным модулем.
deps	Array string	[]	Список ID плагинов-зависимостей, которые должны быть загружены ранее.
css	Array string	[]	Массив путей к стилям. Загружаются параллельно.
js	Array string	[]	Цепочка скриптов. Массив в массиве (напр. [1.js, [2.1, 2.2]]) задает параллельную загрузку.
loadJsAfterModule	bool	false	Если true, то внешние JS-скрипты загрузятся строго после основного модуля.
isSetTimestamp	bool	true	Добавит к загружаемым файлам параметр __pm который позволит установить кеш на 1 час.
onRegister	callback	—	Функция, выполняемая однократно сразу после регистрации плагина.
onLoad	callback	—	Функция, выполняемая однократно после завершения загрузки всех ресурсов.
onInstall	callback	—	Функция, выполняемая однократно после финальной установки (выполнения handler).

Использование

Методы управления модулями

Метод	Аргументы	Вернет	Описание
require	pluginId, callback	*	Вызывает метод callback после установки pluginId. Возвращает модуль, если плагин установлен.
get	pluginId, callback	*	Вызывает метод callback после установки pluginId. Возвращает модуль, если плагин установлен.
define	deps, callback	Promise	Организаует вызов метода в стиле https://requirejs.org/. В качестве аргументов в метод callback будут проброшены экспорты плагинов.
require	deps, callback	Promise	Организаует вызов метода в стиле https://requirejs.org/. В качестве аргументов в метод callback будут проброшены экспорты плагинов.
ready	deps, callback	Promise	Вызывает метод callback после установки зависимостей deps и отработки события document.DOMContentLoaded.
exec	deps, callback, args, context	Promise	Вызывает метод callback после установки зависимостей deps.
loaded	deps, callback	Promise	Вызывает метод callback после установки зависимостей deps и отработки события window.load.

---

Запуск исполняемого кода после установки зависимостей:

kit.exec(deps, callback, argArr, context)

kit.define(['UserAPI', 'Logger'], function(api, log) {
   log.info('Start');
});

kit.ready(['UserAPI', 'Logger'], function() {
   kit.logger.info('Start');
   kit.require('UserAPI').do();
});

kit.exec(['UserAPI', 'Logger'], function() {
   kit.logger.info('Start');
});

kit.require('Product').then(function(){
   kit.Product.make(productId).then(function(product){
      product.setXData('.catalog-page');
      kit.require('alpine');
   })
})

State list

Значение	Состояние	Описание
0	undefined	Начальное состояние, плагин только что создан.
1	registered	Плагин зарегистрирован в системе, конфиг проверен.
3	loading	Идет активная загрузка файлов (JS, CSS, зависимости).
4	loaded	Все внешние ресурсы успешно загружены.
5	installing	Выполняется основной код плагина (handler).
6	installed	Плагин полностью готов к работе, экспорт завершен.

Глобальный конфиг

Параметры определяются в плагине config

Параметры допустимо определять до загрузки PluginManager

name	default	description
assetsPath	/local/templater.dev/kit/assets	Если не указывать, то определится автоматически при инициализации PluginManager
requiredDependencies	['bsCore', 'toolkit']	дополнительно определяет список зависимостей для любого колбека вызванного функциями exec и ready
autoloadPluginList	['tooltip']	Автоматически загрузит ресурсы указанных плагинов. В случае модуля с типом HMD код не будет исполнен сразу после загрузки. Исполнение бдует определятся функций install
debug	false	Расширит список выводимой в консоль информации

Глобальные переменные (window)

переменная kit может быть задана любой, поэтому в некоторых местах корректно будет использовать универсальные глобальные переменные

name	link	description
__pmGlobal__	аналог window.kit
__PluginManager__	аналог window.kit.PluginManager
__pmConfig__	аналог window.kit.config

z-index map

z-index	plugin	selector
100	flex-kit	.flex-card:hover .flex-card__content
1000	bs	dropdown
1020	bs	sticky
1030	bs	fixed
1040	bs	modal-backdrop
1050	bs	offcanvas
1060	bs	modal
1070	bs	popover
1080	bs	tooltip