Snapshot of main at 9f39a6e1e (2026-11-02)

2026-11-02 10:41:47 +01:00
commit 6ccf1792d7
@@ -0,0 +1,105 @@
+# Theme Logo Files
+
+This directory contains SVG logo files for each theme. These logos are used throughout the application in navigation, authentication pages, and other UI components.
+
+## Files
+
+- `timebank_cc.blade.php` - Default Timebank.cc theme logo
+- `uuro.blade.php` - Uuro theme logo
+- `vegetable.blade.php` - Vegetable theme logo
+- `yellow.blade.php` - Yellow theme logo
+
+## Customization
+
+The files in this directory belong to every installation: a change here is a code change, committed to git.
+
+### A platform's own logo (one installation)
+
+Put it in the installation's platform folder instead (outside git; see `references/MULTI_PLATFORM_INSTANCES.md`,
+section 3). The platform's copy wins over the file here:
+
+```bash
+php artisan platform:override logos.uuro     # copies this file to platform/views/logos/uuro.blade.php
+```
+
+Then replace the SVG in the copy, and run `php artisan view:clear`. A theme of the platform's own (in
+`platform/theme.php`) can have its logo view only there, e.g. `platform/views/logos/mybrand.blade.php` for
+`'svg_inline' => 'logos.mybrand'`.
+
+### Requirements for every logo file
+
+Whether here or in a platform folder, **ensure the SVG includes:**
+   - `class="fill-theme-logo w-full h-full"` for theme-aware coloring and responsive sizing
+   - Dynamic title tag: `<title>{{ $logoTitle ?? config('app.name') . ' ' . __('logo') }}</title>`
+   - The `viewBox` attribute for aspect ratio (no fixed width/height)
+
+### A new theme for every installation
+
+1. **Copy an existing logo file:**
+   ```bash
+   cp timebank_cc.blade.php my_new_theme.blade.php
+   ```
+
+2. **Edit the SVG content** in `my_new_theme.blade.php`
+
+3. **Update theme configuration** in `config/themes.php`:
+   ```php
+   'my_new_theme' => [
+       'name' => 'My New Theme',
+       'logos' => [
+           'svg_inline' => 'logos.my_new_theme',
+           'email_logo' => 'app-images/my_new_theme_mail_logo.png',
+       ],
+       // ... other theme settings
+   ],
+   ```
+
+4. **Add the theme to `config/themes.php.example`** too, so every installation gets it through `config:merge`.
+
+## Important Notes
+
+- **SVG logos** in this directory are tracked in git; a `git pull` replaces them. A platform's own logo therefore
+  belongs in its platform folder (above), which git never touches.
+- **Email/PDF logos** (PNG): `platform/public/mail-logo.png` and `mail-logo-inverted.png` in the platform folder, or the
+  older way, the file named in the theme's `logos.email_logo` in `storage/app/public/app-images/` (gitignored).
+- Use the `theme_logo()` helper function to access logo paths in code; for the email logo
+  `theme_email_logo_url()` (emails) and `theme_email_logo_file()` (PDFs).
+
+## Usage in Code
+
+```php
+// Get SVG inline view name
+$svgView = theme_logo('svg_inline'); // Returns: 'logos.timebank_cc'
+
+// Include in Blade template (uses default tooltip)
+@include(theme_logo('svg_inline'))
+
+// Include with custom tooltip text
+@include(theme_logo('svg_inline'), ['logoTitle' => __('Go to homepage')])
+
+// Include with context-specific tooltip
+@include(theme_logo('svg_inline'), ['logoTitle' => __('Search') . ' - ' . config('app.name')])
+
+// Email logo, platform folder first
+$url = theme_email_logo_url();   // for <img src> in emails
+$file = theme_email_logo_file(); // a file path, for PDFs and inline images
+```
+
+## Dynamic Tooltip Text
+
+All logo files support dynamic tooltip text via the `$logoTitle` variable:
+
+- **Default behavior:** If no `$logoTitle` is provided, the tooltip defaults to `config('app.name') . ' ' . __('logo')`
+- **Custom tooltips:** Pass `['logoTitle' => 'Your custom text']` when including the logo
+- **Context-aware:** Different components can use different tooltips (e.g., "Go to homepage" on login, "Search" on dashboard)
+
+## White-Label Deployment
+
+The logo system is designed to support white-label deployments:
+
+- Each installation sets `TIMEBANK_THEME=your_theme` in `.env`, or has its own theme in `platform/theme.php`
+- Theme-specific logos are automatically loaded; a logo in the platform folder wins over the one here
+- The platform folder and email logos in `storage/` persist through git updates
+- No conflicts when pulling latest code from repository
+
+For more information, see `references/THEME_IMPLEMENTATION.md`.