VueTools 1.2.0: единая тема PrimeVue для компонентов MODX 3

В VueTools появилась централизованная настройка темы PrimeVue. Теперь компоненты, которые используют VueTools и поддерживают новый API, можно переключать между стандартной Aura и темой, стилизованной под менеджер MODX Revolution 3, без пересборки самих компонентов.

Зачем это понадобилось

Раньше каждый Vue-компонент сам выбирал тему PrimeVue:

app.use(PrimeVue, { theme: { preset: Aura } })

Для одного компонента это нормально. Но когда VueTools становится общей зависимостью для большого количества extras, получается не очень удобная схема: если хочется изменить оформление всех компонентов, приходится менять каждый extra отдельно и пересобирать его.

Теперь выбор темы вынесен в сам VueTools.

Одна настройка для всех компонентов

В системных настройках MODX появилась настройка: vuetools.theme

Доступны два значения:

aura — стандартная тема PrimeVue, используется по умолчанию;
modx — тема, визуально ориентированная на менеджер MODX Revolution 3.

После изменения настройки компоненты, которые используют централизованный API VueTools, получают выбранную тему автоматически.

Пересобирать компоненты при этом не требуется.

Что нужно изменить разработчику компонента

Вместо жёстко заданной темы компонент использует getActiveTheme():

import { PrimeVue } from 'primevue'
import { getActiveTheme } from '@vuetools/useTheme'
app.use(PrimeVue, getActiveTheme())

Если нужна ещё и локализация PrimeVue:

import { PrimeVue } from 'primevue'
import { getActiveTheme } from '@vuetools/useTheme'
import { getPrimeVueLocale } from '@vuetools/usePrimeVueLocale'

app.use(PrimeVue, { ...getActiveTheme(), locale: getPrimeVueLocale() })

Сам getActiveTheme() читает значение из window.VueTools.theme и возвращает нужный PrimeVue preset. Если значение неизвестно или указано некорректно, используется Aura.

Что происходит внутри VueTools

VueCoreManager при рендеринге страницы добавляет в <head> Import Map и информацию об активной теме:

window.VueTools = { theme: 'modx' }

Компоненту не нужно самостоятельно искать системную настройку или делать PHP-запрос. Он просто вызывает getActiveTheme().

Для нового API также добавлен Import Map ключ: @vuetools/useTheme

А vuetools/theme можно использовать как признак того, что установленная версия VueTools поддерживает централизованную темизацию.

Новая тема Modx

Вместе с централизованным переключением появился полноценный PrimeVue preset Modx.

Он построен на базе Nora и повторяет визуальные особенности менеджера MODX 3:

компактные элементы интерфейса;
радиус элементов — 3px;
базовый размер текста — 13px;
плотные таблицы и tab strip;
основной цвет MODX — #234368;
отдельное оформление кнопок действий менеджера.

Для кнопок также определены ожидаемые варианты:

success — действия вроде Save / Create;
secondary — Toolbar / Cancel;
основной navy-цвет — focus, selected, tabs и checkbox.

При этом стандартная Aura никуда не исчезла. Она остаётся обычным экспортом PrimeVue.

Можно использовать и напрямую

Для специальных случаев preset также доступен напрямую:

import { PrimeVue, Modx, ModxManagerTheme } from 'primevue'

Для менеджера предусмотрен ModxManagerTheme, а для обычных приложений можно использовать ModxTheme.

Но для обычных extras предпочтительный вариант — именно getActiveTheme(). Тогда компонент автоматически подхватывает глобальную настройку VueTools.

А что будет со старыми компонентами?

Здесь специально сохранена обратная совместимость.

Если существующий extra продолжает делать:

app.use(PrimeVue, { theme: { preset: Aura } })

он продолжит работать как раньше.

Он просто не будет реагировать на переключение vuetools.theme, пока его не переведут на getActiveTheme().

Это также означает, что простое обновление VueTools не изменит внешний вид существующих компонентов: значение aura используется по умолчанию.

Свою тему тоже можно сделать

При необходимости не обязательно копировать весь preset. PrimeVue позволяет расширить существующую тему:

import { definePreset, Modx } from 'primevue'
const MyExtra = definePreset(Modx, { semantic: { primary: { 500: '#1a3a5c' } } })

Таким образом, можно взять базовую тему MODX и переопределить только необходимые токены.

Обновилась и документация

Заодно была полностью актуализирована документация VueTools под текущую версию пакета.

В частности, исправлены примеры и API для:

useLexicon;
useModx;
usePermission;
useApi;
usePrimeVueLocale;
useTheme.

Также обновлены сведения о PrimeVue, Import Map, подключении composables и добавлена отдельная страница про темы.

Документация: VueTools

Что это даёт в итоге

Идея достаточно простая: тема больше не должна быть ответственностью каждого отдельного extra.

VueTools становится общей точкой, где можно определить внешний вид Vue-компонентов, а сами extras используют единый API:

app.use(PrimeVue, getActiveTheme())

Сегодня доступны Aura и Modx. При необходимости новые темы можно добавлять в реестр VueTools, не меняя API компонентов.

Таким образом, постепенно можно привести разные Vue-компоненты в MODX к единому визуальному стилю, при этом не ломая уже существующие extras.

VueTools 1.2.0 — это ещё один шаг к тому, чтобы Vue-компоненты в MODX 3 использовали общий стек и общие правила, а не собирали каждый свою небольшую экосистему.

Если хотите поддержать эту работу:

Спасибо всем, кто использует, тестирует, создаёт issues, отправляет pull request'ы, пишет документацию и поддерживает проекты финансово.

Open Source существует благодаря людям, которые не только используют проекты, но и помогают им становиться лучше.