Теми

Вступ

Тема дозволяє повністю налаштувати зовнішній вигляд сайту за допомогою Azuriom.

Щоб встановити тему, просто помістіть її в папку resources/themes/ в корені вашого сайту.

Коли Azuriom встановлюється локально для розробки теми, настійно рекомендується включити налагодження для спрощення розробки. Це можна зробити, просто відредагувавши ці 2 рядки в файлі .env:

APP_ENV=local
APP_DEBUG=true

Створення теми

Для швидкого створення теми можна скористатися наступною командою, яка автоматично згенерує каталог теми і файл theme.json:

php artisan theme:create <theme name>

Для створення тем з більш просунутою настройкою з webpack для компіляції SASS-файлів і оптимізації JavaScript-файлів, можна скористатися цим неофіційний шаблон (Також необхідно встановити Node.js з NPM)

Структура

themes/ <-- Папка з усіма встановленими темами
| example/ <-- Ідентифікатор вашої теми
| | theme.json <-- Основний файл вашої теми, що містить різноманітну інформацію
| |  assets/  <-- Папка, що містить ресурси вашої теми (css, js, images, svg і т.д.)
| | views/ <-- Папка, в якій містяться перегляди Вашої теми.
| | config/
| | | config.blade.php
| | | rules.php
| | config.json

Файл theme.json

Всі теми повинні мати в своєму корені файл theme.json, тобто єдиний обов’язковий елемент для теми, і виглядає він ось так:

{
    "id": "example",
    "name": "Example",
    "version": "1.0.0",
    "description": "A great theme.",
    "url": "https://azuriom.com",
    "authors": [
        "Azuriom"
    ],
    "azuriom_api": "1.0.0"
}

Ідентифікатор теми

Кожна тема повинна мати ідентифікатор, який повинен бути унікальним і містити тільки цифри, малі літери та тире. Рекомендується використовувати назву як основу для створення ідентифікатора, наприклад, якщо назва теми Hello World, то ідентифікатор може бути hello-world. Також каталог теми повинен мати таку ж назву, як і її id.

Погляди

Подання - це серце теми, вони являють собою HTML-файли вмісту теми теми для різних частин веб-сайту.

Azuriom за допомогою Laravel, перегляди можна зробити за допомогою шаблону Blade. Якщо ви не володієте Blade, настійно рекомендується прочитати його документацію, тим більше, що вона досить коротка.

Настійно рекомендується НЕ використовувати синтаксис PHP. при роботі з Blade, тому що Blade не принесе вам традиційних ніяких переваг, а тільки недоліки.

З боку CSS рекомендується використовувати фреймворк cms за замовчуванням, яким є Bootstrap 5, це полегшить реалізацію теми і буде сумісним з новими плагінами. Так що вам не доведеться робити постійні оновлення. Але при бажанні ви можете використовувати інший CSS фреймворк.

У Javascript необхідна лише одна залежність Axios.

Якщо вид відсутній в темі, але є в CMS або в плагіні, воно буде використано автоматично.

Макет

Макет - це структура всіх сторінок теми. Він містить власне мета-дані, активи теми, верхній, нижній колонтитули тощо…

Для виведення вмісту поточної сторінки можна використовувати @yield('content'), а для виведення заголовка поточної сторінки можна використовувати @yield('title').

Ви також можете інтегрувати різні елементи за допомогою @include('<name.of.the.view>'), наприклад @include('element.navbar') для включення навігаційної панелі.

Щоб визначити макет сторінки, подання повинно розширити подання, що містить макет, можна або використовувати макет за замовчуванням за допомогою @extends('layouts.app'), або створити власний макет і розширити його.

Види плагінів

Щоб змінити вигляд плагіна, просто створіть каталог plugins в папці views теми і створіть папку для кожного плагіна (використовуючи ідентифікатор плагіна, а не назву плагіна), а потім додайте подання плагіна.

Наприклад, для плагіна голосування це дасть views/plugins/vote/index.blade.php.

Методи

Ресурси

Для того, щоб мати посилання на ресурс в темі, ви можете скористатися функцією theme_asset:

<link rel="stylesheet" href="{{ theme_asset('css/style.css') }}">

Поточний користувач

Поточного користувача можна отримати за допомогою функції auth()->user(). Більш детально про аутентифікацію можна прочитати в документації Laravel.

Функції

Ви можете отримати певну кількість параметрів з сайту за допомогою спеціальних функцій:

Відображення гравців, підключених до сервера

Для відображення підключених гравців досить перевірити, що змінна $server не дорівнює null, і сервер онлайн, і якщо це так, використовуйте $server->getOnlinePlayers() для отримати кількість гравців онлайн.

@if($server && $server->isOnline())
    {{ trans_choice('messages.server.online', $server->getOnlinePlayers()) }}
@else
    {{ trans('messages.server.offline') }}
@endif

Переклади

Тема може, якщо їй це потрібно, завантажувати переклади.

Для цього достатньо створити файл messages.php в каталозі lang/<language> (наприклад: lang/en). Якщо ви переклали повідомлення теми, ви можете виводити переклад за допомогою функції trans: {{ trans('theme::messages.hello') }} або за допомогою директиви @lang: @lang('theme::messages.hello'). Також можна використовувати trans_choice для перекладу з числами, і trans_bool для перекладу булевого (поверне англійською Yes). /No.

Більш детально з перекладами можна ознайомитися в Документація Laravel.

Конфігурація

Ви можете додати конфігурацію в тему, для цього потрібно лише створити в корені теми:

• Подання config/config.blade.php, що містить форму для конфігурації.
• Файл config/rules.php, що містить різні правила перевірки для конфігурації теми.
• Файл config.json, в якому буде зберігатися конфігурація теми, і який містить значення за замовчуванням.

Приклад

config.blade.php

<form action="{{ route('admin.themes.update', $theme) }}" method="POST">
    @csrf

    <div class="form-group">
        <label for="discordInput">{{ trans('theme::carbon.config.discord') }}</label>
        <input type="text" class="form-control @error('discord-id') is-invalid @enderror" id="discordInput" name="discord-id" required value="{{ old('discord-id', config('theme.discord-id')) }}">

        @error('discord-id')
        <span class="invalid-feedback" role="alert"><strong>{{ $message }}</strong></span>
        @enderror
    </div>

    <button type="submit" class="btn btn-primary">
        <i class="bi bi-save"></i> {{ trans('messages.actions.save') }}
    </button>
</form>

config.json

{
    "discord-id": "625774284823986183."
}