Skip to Content
Разработка модулейРесурсы и SCSS

Система ресурсов и SCSS

Flute CMS использует TemplateAssets класс для управления SCSS/CSS ресурсами с автоматической компиляцией через ScssPhp, кешированием и поддержкой тем. Система интегрирована с директивой @at() для подключения ресурсов в шаблонах.

Особенности ядра:

  • Контексты main и admin (определяются при инициализации Template/TemplateAssets)
  • Компиляция SCSS → public/assets/css/cache/*, minify зависит от config('assets.minify')
  • Импорт-пути добавляются автоматически для app и активных тем; loadScss()/registerScss() подключает файлы и добавляет путь их каталога
  • Директива @at(path, urlOnly = false) создаёт тег <link>/<script>/<img> или отдаёт URL, если второй параметр true

Структура ресурсов модуля

SCSS архитектура

CSS переменные темы

Flute CMS использует CSS переменные для тем с поддержкой light/dark режимов:

// app/Themes/standard/assets/sass/theme/_variables.scss
 
:root {
    --transition: .2s;
    --shadow-small: 0 0px 10px rgba(0, 0, 0, 0.1);
    --shadow-medium: 0 0px 15px rgba(0, 0, 0, 0.15);
    --shadow-large: 0 0px 25px rgba(0, 0, 0, 0.15);
}
 
:root[data-theme=light] {
    --text: #1d1d1f;
    --background: #ffffff;
    --primary: #1d1d1f;
    --secondary: #f5f5f7;
    --accent: #34c759;
    
    --success: #30d158;
    --error: #ff3b30;
    --warning: #ff9500;
    --info: #5ac8fa;
    
    --text-50: #1d1d1f;
    --text-100: #2c2c2e;
    // ... градация цветов
    --text-950: #f2f2f7;
}
 
:root[data-theme=dark] {
    --text: #f2f2f7;
    --background: #1c1c1e;
    --primary: #f2f2f7;
    --secondary: #2c2c2e;
    --accent: #A5FF75;
    // ... темная тема
}

Структура SCSS файлов

Flute CMS использует модульную архитектуру SCSS с четким разделением:

// app/Themes/standard/assets/sass/app.scss
 
@import 'theme/variables';       // Переменные темы
@import 'utils/animations';      // Утилиты анимаций
 
@import 'base/reset';           // Сброс стилей
@import 'base/typography';      // Типографика
 
@import 'layouts/app';          // Макет приложения
@import 'layouts/header';       // Заголовок
@import 'layouts/footer';       // Подвал
 
@import 'components/card';      // Компоненты
@import 'components/buttons';
@import 'components/modals';
@import 'components/tabs';
 
@import 'partials/loading';     // Частичные блоки
@import 'partials/breadcrumb';
@import 'partials/notifications';
 
@import 'pages/home';          // Страницы
@import 'pages/profile';
@import 'pages/login';
 
@import 'widgets/recent-payments';  // Виджеты
@import 'widgets/users-online';

Компоненты SCSS

Реальные примеры компонентов из темы standard:

// app/Themes/standard/assets/sass/components/_card.scss
 
.card {
    background: var(--background);
    border: 1px solid var(--transp-1);
    border-radius: 8px;
    padding: 16px;
    transition: var(--transition);
 
    &:hover {
        box-shadow: var(--shadow-medium);
    }
}
 
// app/Themes/standard/assets/sass/components/_buttons.scss
 
.btn {
    display: inline-flex;
    align-items: center;
    padding: 8px 16px;
    border-radius: 6px;
    border: none;
    transition: var(--transition);
    cursor: pointer;
 
    &.btn-primary {
        background: var(--accent);
        color: var(--background);
    }
 
    &.btn-secondary {
        background: var(--secondary);
        color: var(--text);
    }
}
 
// app/Themes/standard/assets/sass/components/_modal.scss
 
.modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.5);
    z-index: 1000;
 
    .modal-content {
        background: var(--background);
        border-radius: 8px;
        box-shadow: var(--shadow-large);
        max-width: 500px;
        margin: 50px auto;
    }
}

Регистрация SCSS в модуле

Использование loadScss в провайдере

<?php
namespace Flute\Modules\News\Providers;
 
use Flute\Core\Support\ModuleServiceProvider;
 
class NewsProvider extends ModuleServiceProvider
{
    protected ?string $moduleName = 'News';
 
    public function boot(\DI\Container $container): void
    {
        $this->bootstrapModule();
 
        // Регистрация SCSS файла модуля
        $this->loadScss('Resources/assets/scss/news.scss');
    }
}

Директива @at() в шаблонах

{{-- Подключение SCSS/CSS ресурсов в шаблонах --}}
@at('Themes/standard/assets/sass/app.scss')
@at('Modules/News/Resources/assets/scss/news.scss')
 
{{-- Подключение JavaScript --}}
@at('Themes/standard/assets/scripts/app.js')
@at('assets/js/libs/jquery.js')
 
{{-- Подключение изображений --}}
<img src="@at('Themes/standard/assets/images/logo.png')" alt="Logo">
 
{{-- Только URL без тега --}}
<link rel="preload" href="@at('assets/fonts/montserrat/montserrat.css', true)" as="style">

Очистить кеш стилей/путей можно через template()->getTemplateAssets()->clearStyleCache() (удалит public/assets/css/cache/* и внутренние кеши).

Кеширование и компиляция

TemplateAssets класс

Система автоматически компилирует SCSS через TemplateAssets:

<?php
// Основные методы TemplateAssets
class TemplateAssets
{
    // Добавление SCSS файла для компиляции
    public function addScssFile(string $filePath, string $context = 'main'): void
    
    // Добавление пути для импорта
    public function addImportPath(string $path, string $context = 'main'): void
    
    // Обработка директивы @at()
    public function assetFunction(string $expression, bool $urlOnly = false): string
    
    // Компиляция SCSS в CSS
    private function compileScss(array $scssContents): string
}

Кеширование ресурсов

// Автоматическое кеширование CSS файлов
// Путь: public/assets/css/cache/{hash}.css
 
// Система использует хеши для версионирования:
// - Изменение SCSS файла = новый хеш = обход кеша
// - В production кеш валиден до изменения файлов
// - В development перекомпиляция при каждом запросе

Поддержка тем

theme.json конфигурация

Темы могут переопределять ресурсы через theme.json:

{
    "name": "Standard",
    "version": "1.0.0",
    "asset_replacements": {
        "Modules/News/Resources/assets/scss/news.scss": "Themes/custom/assets/sass/news-override.scss"
    },
    "asset_wildcard_replacements": {
        "Modules/*/Resources/assets/scss/*": "Themes/custom/assets/sass/modules/*"
    }
}

Fallback система

<?php
// Система автоматически ищет файлы в порядке:
// 1. Текущая тема: app/Themes/custom/assets/sass/news.scss
// 2. Стандартная тема: app/Themes/standard/assets/sass/news.scss
// 3. Модуль: app/Modules/News/Resources/assets/scss/news.scss

Лучшие практики

Использование CSS переменных

// app/Modules/News/Resources/assets/scss/news.scss
 
.news-card {
    background: var(--background);
    border: 1px solid var(--transp-1);
    border-radius: 8px;
    color: var(--text);
    
    &:hover {
        box-shadow: var(--shadow-medium);
    }
}
 
.news-title {
    color: var(--accent);
    font-size: 1.25rem;
    font-weight: 600;
}

Модульная организация

  1. Один SCSS файл на модуль — Resources/assets/scss/module-name.scss
  2. Используйте существующие переменные из theme/_variables.scss
  3. Минимальные стили — только уникальные для модуля
  4. Адаптивность — используйте CSS переменные для тем

Производительность

// ✅ Хорошо — используем переменные темы
.my-component {
    background: var(--background);
    color: var(--text);
}
 
// ❌ Плохо — хардкод цветов
.my-component {
    background: #ffffff;
    color: #000000;
}

Отладка

<?php
// Включение режима отладки для SCSS
// В config/assets.php:
'minify' => false,  // Отключить минификацию
'debug' => true,    // Включить отладку
 
// Логи компиляции SCSS доступны в:
// storage/logs/templates.log

Заключение

Система ресурсов Flute CMS обеспечивает:

  • Автоматическую компиляцию SCSS в CSS
  • Кеширование для высокой производительности
  • Поддержку тем с fallback системой
  • CSS переменные для адаптивности
  • Простую интеграцию через loadScss() и @at()

Используйте существующие переменные темы и следуйте модульной архитектуре для создания совместимых и производительных стилей.

HTMX и YoyoUI-компоненты