generated from theradcoza/Laravel-Docker-Dev-Template
Initial commit
This commit is contained in:
286
docs/site-settings.md
Normal file
286
docs/site-settings.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Site Settings
|
||||
|
||||
Manage your site's appearance (logo, favicon, colors) from the admin panel.
|
||||
|
||||
## Overview
|
||||
|
||||
Site settings are stored in the database using [spatie/laravel-settings](https://github.com/spatie/laravel-settings) and managed via Filament.
|
||||
|
||||
**Admin Location:** `/admin` → Settings → Appearance
|
||||
|
||||
## Available Settings
|
||||
|
||||
| Setting | Type | Description |
|
||||
|---------|------|-------------|
|
||||
| `site_name` | String | Site name (used in title, emails) |
|
||||
| `logo` | Image | Header logo |
|
||||
| `favicon` | Image | Browser favicon (32x32) |
|
||||
| `primary_color` | Color | Primary brand color |
|
||||
| `secondary_color` | Color | Secondary/accent color |
|
||||
| `dark_mode` | Boolean | Enable dark mode toggle |
|
||||
| `footer_text` | Text | Footer copyright text |
|
||||
|
||||
## Usage in Blade Templates
|
||||
|
||||
### Helper Functions
|
||||
|
||||
```blade
|
||||
{{-- Site name --}}
|
||||
<h1>{{ site_name() }}</h1>
|
||||
|
||||
{{-- Logo with fallback --}}
|
||||
@if(site_logo())
|
||||
<img src="{{ site_logo() }}" alt="{{ site_name() }}">
|
||||
@else
|
||||
<span>{{ site_name() }}</span>
|
||||
@endif
|
||||
|
||||
{{-- Favicon --}}
|
||||
<link rel="icon" href="{{ site_favicon() }}">
|
||||
|
||||
{{-- Colors --}}
|
||||
<div style="background: {{ primary_color() }}">Primary</div>
|
||||
<div style="background: {{ secondary_color() }}">Secondary</div>
|
||||
|
||||
{{-- Get any setting --}}
|
||||
{{ site_settings('footer_text') }}
|
||||
{{ site_settings('dark_mode') ? 'Dark' : 'Light' }}
|
||||
```
|
||||
|
||||
### Site Head Component
|
||||
|
||||
Include in your layout's `<head>`:
|
||||
|
||||
```blade
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
|
||||
{{-- This adds title, favicon, and CSS variables --}}
|
||||
<x-site-head :title="$title ?? null" />
|
||||
|
||||
@vite(['resources/css/app.css', 'resources/js/app.js'])
|
||||
</head>
|
||||
```
|
||||
|
||||
The component automatically:
|
||||
- Sets the page title with site name
|
||||
- Adds favicon link
|
||||
- Creates CSS custom properties for colors
|
||||
|
||||
### CSS Custom Properties
|
||||
|
||||
After including `<x-site-head />`, these CSS variables are available:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--primary-color: #3b82f6;
|
||||
--secondary-color: #64748b;
|
||||
}
|
||||
```
|
||||
|
||||
Use in your CSS:
|
||||
|
||||
```css
|
||||
.button {
|
||||
background-color: var(--primary-color);
|
||||
}
|
||||
|
||||
.text-accent {
|
||||
color: var(--secondary-color);
|
||||
}
|
||||
```
|
||||
|
||||
Or with Tailwind arbitrary values:
|
||||
|
||||
```html
|
||||
<button class="bg-[var(--primary-color)] text-white">
|
||||
Click Me
|
||||
</button>
|
||||
```
|
||||
|
||||
### Utility Classes
|
||||
|
||||
The component also creates utility classes:
|
||||
|
||||
```html
|
||||
<div class="bg-primary text-white">Primary background</div>
|
||||
<div class="text-primary">Primary text</div>
|
||||
<div class="border-primary">Primary border</div>
|
||||
|
||||
<div class="bg-secondary">Secondary background</div>
|
||||
<button class="btn-primary">Styled Button</button>
|
||||
```
|
||||
|
||||
## Usage in PHP
|
||||
|
||||
```php
|
||||
use App\Settings\SiteSettings;
|
||||
|
||||
// Via dependency injection
|
||||
public function __construct(private SiteSettings $settings)
|
||||
{
|
||||
$name = $this->settings->site_name;
|
||||
}
|
||||
|
||||
// Via helper
|
||||
$name = site_settings('site_name');
|
||||
$logo = site_logo();
|
||||
|
||||
// Via app container
|
||||
$settings = app(SiteSettings::class);
|
||||
$color = $settings->primary_color;
|
||||
```
|
||||
|
||||
## Customizing the Settings Page
|
||||
|
||||
Edit `app/Filament/Pages/ManageSiteSettings.php`:
|
||||
|
||||
### Add New Settings
|
||||
|
||||
1. Add property to `app/Settings/SiteSettings.php`:
|
||||
|
||||
```php
|
||||
class SiteSettings extends Settings
|
||||
{
|
||||
// ... existing properties
|
||||
public ?string $contact_email;
|
||||
public ?string $phone_number;
|
||||
}
|
||||
```
|
||||
|
||||
2. Create migration in `database/settings/`:
|
||||
|
||||
```php
|
||||
return new class extends SettingsMigration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
$this->migrator->add('site.contact_email', null);
|
||||
$this->migrator->add('site.phone_number', null);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
3. Add to form in `ManageSiteSettings.php`:
|
||||
|
||||
```php
|
||||
Forms\Components\Section::make('Contact')
|
||||
->schema([
|
||||
Forms\Components\TextInput::make('contact_email')
|
||||
->email(),
|
||||
Forms\Components\TextInput::make('phone_number')
|
||||
->tel(),
|
||||
]),
|
||||
```
|
||||
|
||||
4. Run migration: `php artisan migrate`
|
||||
|
||||
### Add Social Links
|
||||
|
||||
```php
|
||||
// In SiteSettings.php
|
||||
public ?array $social_links;
|
||||
|
||||
// In migration
|
||||
$this->migrator->add('site.social_links', []);
|
||||
|
||||
// In form
|
||||
Forms\Components\Repeater::make('social_links')
|
||||
->schema([
|
||||
Forms\Components\Select::make('platform')
|
||||
->options([
|
||||
'facebook' => 'Facebook',
|
||||
'twitter' => 'Twitter/X',
|
||||
'instagram' => 'Instagram',
|
||||
'linkedin' => 'LinkedIn',
|
||||
]),
|
||||
Forms\Components\TextInput::make('url')
|
||||
->url(),
|
||||
])
|
||||
->columns(2),
|
||||
```
|
||||
|
||||
## Caching
|
||||
|
||||
Settings are cached automatically. Clear cache after direct database changes:
|
||||
|
||||
```bash
|
||||
php artisan cache:clear
|
||||
```
|
||||
|
||||
Or in code:
|
||||
|
||||
```php
|
||||
app(SiteSettings::class)->refresh();
|
||||
```
|
||||
|
||||
## File Storage
|
||||
|
||||
Logo and favicon are stored in `storage/app/public/site/`.
|
||||
|
||||
Make sure the storage link exists:
|
||||
|
||||
```bash
|
||||
php artisan storage:link
|
||||
```
|
||||
|
||||
## Example: Complete Layout
|
||||
|
||||
```blade
|
||||
<!DOCTYPE html>
|
||||
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="csrf-token" content="{{ csrf_token() }}">
|
||||
|
||||
<x-site-head :title="$title ?? null" />
|
||||
|
||||
<link rel="preconnect" href="https://fonts.bunny.net">
|
||||
<link href="https://fonts.bunny.net/css?family=figtree:400,500,600&display=swap" rel="stylesheet" />
|
||||
|
||||
@vite(['resources/css/app.css', 'resources/js/app.js'])
|
||||
</head>
|
||||
<body class="font-sans antialiased">
|
||||
<div class="min-h-screen bg-gray-100">
|
||||
{{-- Header with logo --}}
|
||||
<header class="bg-white shadow">
|
||||
<div class="max-w-7xl mx-auto px-4 py-4">
|
||||
@if(site_logo())
|
||||
<img src="{{ site_logo() }}" alt="{{ site_name() }}" class="h-10">
|
||||
@else
|
||||
<span class="text-xl font-bold text-primary">{{ site_name() }}</span>
|
||||
@endif
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{{-- Content --}}
|
||||
<main>
|
||||
{{ $slot }}
|
||||
</main>
|
||||
|
||||
{{-- Footer --}}
|
||||
<footer class="bg-gray-800 text-white py-8">
|
||||
<div class="max-w-7xl mx-auto px-4 text-center">
|
||||
{!! site_settings('footer_text') ?? '© ' . date('Y') . ' ' . site_name() !!}
|
||||
</div>
|
||||
</footer>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Settings not updating
|
||||
1. Clear cache: `php artisan cache:clear`
|
||||
2. Check file permissions on storage directory
|
||||
|
||||
### Logo not showing
|
||||
1. Run `php artisan storage:link`
|
||||
2. Check logo exists in `storage/app/public/site/`
|
||||
|
||||
### Colors not applying
|
||||
1. Make sure `<x-site-head />` is in your layout's `<head>`
|
||||
2. Check browser dev tools for CSS variable values
|
||||
Reference in New Issue
Block a user