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

1. Структура на сайта

„София през обектива“ е фотографско портфолио с 19 кадъра от София, разделени в четири теми. Всеки кадър е отделна статия в Joomla със снимка, описание и потребителски полета.

• Начало /: голяма снимка (hero), избрани кадри, четирите теми, статистика и блок „За проекта“
  • Галерия /galeriya: всички кадри, филтър по тема, изглед „решетка“ или „карта“
    • Страница на кадър /galeriya/<кадър>: 19 страници със снимка, описание, данни, мини карта и автор
  • Карта /galeriya#karta: картата на всички кадри
  • За проекта /za-proekta: цел, реализирани функции и технологии
  • Документация /dokumentatsiya: тази страница
  • Контакт /kontakt: форма за връзка
  • Грешка 404: собствена страница за несъществуващ адрес

1.1. Организация на съдържанието

Елемент в Joomla	Използване
Категория „Галерия“	19 статии, по една за всеки кадър
Категория „Страници“	„За проекта“ и „Документация“
Тагове (теми)	Архитектура (6), Природа (5), Улици (3), Нощ (5)
Потребителски полета (Custom Fields)	Място, Година, Географска ширина, Географска дължина, Автор на снимката, Лиценз, Адрес на лиценза, Източник
Избрани статии (Featured)	6 кадъра, показани на началната страница
Контакт (Contacts)	„Иван Букарев“ с форма за изпращане на имейл
Медия	images/sofia/medium (960 px за решетката) и images/sofia/large (1920 px за lightbox и страницата на кадъра)

2. Процес на създаване на сайта

2.1. Етапи на работа

1. Подготовка на средата. Joomla 6.2 и MariaDB 11.8 работят в Docker контейнери, описани в compose.yaml. Инсталацията на Joomla е автоматична, чрез променливи на средата.
2. Основни настройки. Име и описание на сайта, официален български езиков пакет (проверен с контролна сума SHA-256), чисти адреси (SEF URL) чрез mod_rewrite.
3. Структура на съдържанието. Създадени са категориите, четирите тага и осемте потребителски полета.
4. Съдържание. Подбрани са 19 снимки със свободен лиценз от Wikimedia Commons и са подготвени в два размера. За всяка е създадена статия с описание, тема, място, година, координати, автор и лиценз.
5. Собствен шаблон. Шаблонът sofialens е написан от нулата: оформление, template overrides, CSS, JavaScript и карта.
6. Навигация и модули. Главно меню, модул на началната страница, изключване на ненужните стандартни модули.
7. Контактна форма. Компонентът Contacts; локално писмата се хващат от Mailpit.
8. Тестване и подготовка за публикуване. Проверка на всички страници и функции, скриптове за backup, restore и преместване на сървър с HTTPS (Caddy).
9. Публикуване. Сайтът е преместен от локалната среда на VPS сървър (Ubuntu 24.04, nginx) на адрес fotoblog.blueero.com: DNS запис, PHP 8.3-FPM и MariaDB, отделен виртуален хост в nginx и безплатен HTTPS сертификат от Let's Encrypt.

2.2. Навигация

• Главно меню (модул Menu, позиция menu в горната лента): Начало, Галерия, Карта, За проекта, Документация, Контакт. На мобилни устройства менюто се отваря с бутон.
• Типове пунктове в менюто: Featured Articles (Начало), Category Blog (Галерия), URL (Карта, към /galeriya#karta), Single Article (За проекта, Документация), Single Contact (Контакт).
• Навигация в галерията: филтър по тема без презареждане (темата се записва в адреса, например /galeriya#nosht), превключване между решетка и карта, преглед на снимките в lightbox със стрелки, клавиатура и плъзгане.
• Между кадрите: бутони „Предишна“ и „Следваща“ (плъгин Page Navigation), линк „Обратно към галерията“ и линкове към темите.
• От началната страница: бутони „Разгледай галерията“ и „Карта на кадрите“, карти на темите, които отварят галерията с избран филтър.
• Достъпност: линк „Към съдържанието“ за клавиатура, видим фокус, описания (alt) на всички снимки.

2.3. Тема (шаблон)

Използван е собствен шаблон sofialens, създаден специално за проекта. Изходният код е в папка template/sofialens на проекта.

Част	Предназначение
index.php	Основно оформление: горна лента с меню, hero на началната страница, съдържание, долна лента
error.php, component.php	Страница за грешка (404) и страница без оформление
html/com_content/featured	Override на началната страница: избрани кадри, теми, статистика
html/com_content/category/blog.php	Override на галерията: решетка, филтър и карта
html/com_content/article	Override на страницата на кадър и на текстовите страници
html/com_contact/contact	Override на страницата за контакт
joomla.asset.json	Регистрация на CSS и JavaScript чрез Web Asset Manager
media/	CSS, JavaScript, шрифтове Inter и Playfair Display (лиценз OFL) и библиотеката Leaflet 1.9.4 (лиценз BSD)

Снимката и текстовете в началото на сайта са параметри на шаблона и се сменят от администрацията (Система → Стилове на шаблони). Картата използва данни от OpenStreetMap.

2.4. Модули

Модул	Тип	Позиция	Предназначение
Main Menu	Menu (mod_menu)	menu	Главна навигация
За проекта (начало)	Custom (mod_custom)	home-sections	Блок за проекта на началната страница
Login Form	mod_login	—	Изключен, не е нужен на посетителите
Breadcrumbs	mod_breadcrumbs	—	Изключен, структурата е плитка

2.5. Плъгини и разширения

Плъгин / разширение	Предназначение
System – Fields и Fields – Text, URL	Потребителските полета на кадрите
Content – Page Navigation	Бутони „Предишна“ и „Следваща“ между кадрите
Content – Email Cloaking	Скриване на имейл адресите от спам ботове
System – SEF	Чисти адреси без index.php
Smart Search	Индекс за търсене в съдържанието
Web Services и API Authentication – Basic	Използвани временно за въвеждане на съдържанието през REST API на Joomla, след това изключени
Езиков пакет bg-BG 6.0.3.1	Български интерфейс на сайта и на администрацията

Използвани компоненти: Content (статии и категории), Contacts, Tags, Fields, Media и Languages. Не са използвани разширения от трети страни.

2.6. Срещнати проблеми и начин на преодоляване

Проблем	Причина	Решение
CSS и JavaScript на шаблона не се зареждаха	Шаблонът беше обявен като ненаследяем и Joomla търсеше файловете на стария адрес	Шаблонът е обявен като наследяем (inheritable), а скриптът за инсталация го задава и в базата
Картата показваше „API KEY REQUIRED“	Доставчикът на тъмни карти (CARTO) вече изисква ключ	Преминаване към OpenStreetMap и затъмняване на картата с CSS филтър
Грешка 500 на страница „За проекта“	Команди на Joomla CLI, пуснати като root, създадоха файлове в кеша, които уеб сървърът не може да променя	Поправени права на файловете; всички команди се пускат като потребителя на уеб сървъра (www-data)
Нова парола в .env не работеше в администрацията	Паролата от .env се използва само при първата инсталация	Смяна на паролата през Joomla CLI (user:reset-password)
Грешки при запис през REST API	API изисква полета, които администрацията попълва сама (описание, категория на меню и др.)	Изпращане на всички задължителни полета; текстът на „За проекта“ е обновен директно в базата
Координатите на някои снимки сочеха встрани от обекта	В Wikimedia Commons се пази мястото, откъдето е снимано	За забележителностите са използвани координатите на самата сграда
Wikimedia Commons отказваше заявки (HTTP 429)	Твърде много заявки за кратко време	Пауза и повторен опит
Зад HTTPS прокси линковете излизаха с http	Joomla не знае, че работи зад прокси	Скрипт, който включва настройката behind_loadbalancer
Сървърът за публикуване има само 1 GB RAM, споделена с други сайтове	Docker с отделни контейнери би заел 400–600 MB	PHP-FPM и MariaDB са инсталирани директно и настроени за малко памет: PHP процесите се стартират само при заявка, а буферът на MariaDB е 32 MB
Различни версии на базата (локално MariaDB 11.8, на сървъра 10.11)	По-новите версии имат подредби (collations), които старите не познават	Проверка на базата преди импорта: използвани са само utf8mb4_unicode_ci и utf8mb4_bin, които се поддържат

3. Тестване на сайта

3.1. Кой и как е тествал

Сайтът е тестван по време на разработката с помощта на AI асистента Claude Code. Той управлява браузъра, отваря страниците, кликва и попълва формите, и пуска автоматизирани проверки на всички адреси. Тестването е проведено локално, на адрес http://localhost:8080, и след публикуването, на адрес https://fotoblog.blueero.com.

3.2. Компютърна конфигурация

Компютър	MacBook Pro, Apple M3 Max, 14 ядра, 36 GB RAM
Операционна система	macOS 27.0.1
Дисплей	3024 × 1964 (Retina)
Сървър	Docker 29.5.2 чрез Colima 0.10.3 (виртуална машина с 4 ядра и 8 GB RAM)
Софтуер на сайта (локално)	Joomla 6.2.0, PHP 8.4.27, Apache 2.4.69, MariaDB 11.8.9
Публичен сървър	VPS при Vultr, Ubuntu 24.04, 1 vCPU, 1 GB RAM; nginx, PHP 8.3.6 (FPM), MariaDB 10.11.14

3.3. Браузъри

Браузър	Версия	Екран	Резултат
Chromium (вграденият браузър на Claude)	152.0.7977.167	1440 × 900, настолен	Успешно
Chromium, емулация на телефон	152.0.7977.167	375 × 812, мобилен	Успешно
Google Chrome	__________	__________	за попълване
Safari	__________	__________	за попълване

3.4. Резултати от тестването

Проверка	Резултат
Всички страници и ресурси (автоматично обхождане)	23 страници и 51 файла (CSS, JavaScript, шрифтове, снимки), 0 счупени линка; средно време за отговор 18 ms
Несъществуващ адрес	Код 404 и собствена страница за грешка
Начална страница	Hero, 6 избрани кадъра, 4 теми и статистика се показват правилно
Филтър по тема	„Нощ“ показва точно 5 кадъра, адресът става /galeriya#nosht
Карта на кадрите	19 маркера; при избрана тема се показват само нейните
Lightbox	Отваря се, стрелката води към следващия кадър, Escape затваря; показва автора и лиценза
Страница на кадър	Снимка, данни, мини карта, бутони „Предишна/Следваща“ и Open Graph метаданни
Контактна форма	Тестово съобщение е изпратено и получено в Mailpit с правилен получател и адрес за отговор
Мобилен изглед (375 px)	Менюто се отваря с бутон, няма хоризонтално превъртане
Администрация	Входът работи, интерфейсът е на български
Backup и възстановяване	След пълно изтриване на данните сайтът е възстановен, включително в режим с HTTPS
Публикуваният сайт (https://fotoblog.blueero.com)	24 страници и 51 файла, 0 счупени линка; средно време за отговор 0,27 s; валиден сертификат от Let's Encrypt; http се пренасочва към https; няма смесено съдържание; картата зарежда 19 маркера
Защита на сървъра	configuration.php връща 403 (забранен), несъществуващ адрес връща 404

Грешките, открити при тестването, са описани в раздел 2.6 и са отстранени. Ограничение: на публичния сървър контактната форма не изпраща писма, докато не се настрои SMTP сървър.