From 4ba6e66042b41aa8c261adc020858149978dd513 Mon Sep 17 00:00:00 2001 From: Vasil Kolev Date: Wed, 15 Oct 2014 01:13:09 +0300 Subject: [PATCH] docs --- README.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d51d313 --- /dev/null +++ b/README.md @@ -0,0 +1,137 @@ +Документация на сайта на openfest +================================= + + +## Основни моменти + +Сайтът представлява wordpress с тема, писана специално за целта (initfest), която може да се намери в github (https://github.com/initLab/initfest), polylang plugin-а за многоезичност и jetpack за друга функционалност. + +Част от данните в сайта се взимат автоматично от външна система (clarion, достъпна на https://cfp.openfest.org, source има на https://github.com/ignisf/clarion/), която се грижи да събира програмата и да комуникира с лекторите. + +## Кратко overview на модела на wordpress + +(който си е играл по-сериозно, може да прескочи това некадърно обяснение) + +Почти всичко в wordpress е post. Всеки post има следните измерения (т.е. може да има за всяко от тях точно една стойност): +* тип - post, page, custom page и т.н. +* език +* статус - published, draft, trash... +* category - категория, в които попада + +Всеки post има следните задължителни неща (не са всички, само релевантните за нас): +* title - някакво заглавие +* slug - идентификатор, който се ползва в url-тата (не е title) +* author - автор +* content - текст + +И всеки post също така може да има +* custom fields, които да ползваме в логиката с някаква цел (вж. url за sponsors). +* thumbnail/featured image - картинка, която се показва с post-а +* tag-ове (в момента не ги ползваме, но може да ни потрябват) + + +## Многоезичност + +Използваме polylang plugin-а, който превежда всичко, което му падне. + +Интерфейсът му е лесен за ползване, в общи линии за всеки тип post/page и т.н. има език, и вътре в редакцията може да се избере да се иде на версията за другия език (вж. по-долу процедурата за нов спонсор). Има превеждане на отделни string-ове, които са били регистрирани от plugins->polylang->strings. Стринговете в момента са регистрирани във functions.php най-отдолу. + +polylang създава един проблем при автоматичните скриптове, че трябва да се прави wp_query по отделно за двата езика, защото по default дава текущия или default-ния. Ако автоматично се създава post, трябва задължително да се създаде по един за двата езика и после да се свържат. + +Също така, ако например дадена категория името и го няма преведено на другия език, не дава на този език да се слагат неща в тази категория, и не дава никаква грешка. + +Хубаво е да се внимава с избирането на имена на slug-овете на post-овете, понеже два post-а не могат да имат същия slug, за това в момента в сайта има schedule и schedule-3 (едното е български, другото английски). + +По принцип без polylang темата няма да работи, или поне не по очаквания начин. Има една-две wrapper функции, но те са само за няколко редки места, където не е load-нат plugin-а още. + +## Менюта + +В темата има 6 менюта, всяко от които в два варианта, за двата езика. + +* Главно меню - показва се винаги, най-отгоре на сайта +* submenu/about - показва се само на about и свързаните страници, като team, volunteers и т.н., логиката за показването му може да се види в page.php. +* Дънно openfest - като главното меню +* Дънно програма - свързаните с програмата неща +* Дънно други - хотели, пиене и т.н. +* Дънно follow - социални мрежи + +Единственото по-специално е, че link-овете в главното меню за социалните мрежи и т.н. трябва да са без име и да са в специфични css класове, за да се показват както е нужно. + +## Главна страница + +Страницата се различава от останалите по различния си template и начин на работа. Идеята и е, че показва малко текст, нещо като sidebar-а, но не същото (кодът е набит директно вътре) и след това в три колони последните post-ове от категория "news". +todo: не е изравнен размера на sidebar-а и текста (понеже са доста спонсорите) и вероятно нещо трябва да се преподреди. + +## Custom post-ове и полета в тях + +### Спонсори + +Спонсорите са отделен тип post в системата. Имат език, excerpt, featured image (лого на спонсора) и две custom полета: url и partner. + +* url е link към сайта на спонсора +* partner означава, че спонсорът реално е партньор и трябва да се покаже в друга част на sidebar-а. + +Страницата за спонсорите трябва да е от template "Sponsors" (виж page-sponsors.php) за да работи. + +Спонсорите и партньорите са в същия тип post поради това, че са твърде близки по значение и визуализация. + +#### Процедура за добавяне на спонсор + +* От менюто се избира sponsors->add sponsor +* Задава му се име и (ако има) текст на български +* в custom fields му се добавя url със стойност http://..дето трябва +* ако е партньор, в custom fields му се добавя partner със стойност 1 +* отива се на featured image +* upload-ва се (горе има upload tab) +* избира се картинката +* дава се update +* отива се в английската версия ( щрака се на + знака до флагчето, първата кутия в дясно) +* слага се заглавието на английски (за повечето е същото) и текста на английски +дава се update + +### Лектори + +Лекторите са съвсем прост тип post, който има отделен template за визуализация (виж page-speakers.php). Страницата за всички лектори трябва да е от този template, за да работи. + +### Транспорти + +За всеки тип транспорт до мястото на събитието има отделна страница, като всички се сглобяват в една и се показват в sidebar-а или където е нужно. + +## Комуникация с clarion + +Има няколко скрипта, които наливат информацията от clarion в текущия сайт, и един който директно я връща на потребителите. Всички си говорят с clarion през връзка до базада му, създадена от dbconn.php в initfest (в repo-то има dbconn.dist.pp, като пример какво трябва да има във файла). + +/calendar2014.php директно говори с базата данни на clarion и подава на потребителите в ICS формат календар с програмата, който могат да използват в каквито приложения се поддържат. + +Скриптовете в initfest/ темата (сложени там поради липса на по-приятно място) се базират на малко заимстван код за cli wordpress скриптове (може да се види в cli-header.php) и са следните: + +* load-program-old.php - генерира програмата и я зарежда в стария вид (като стария сайт) +* load-program.php - генерира програмата и я зарежда в новия и вид. +* load-speakers.php - изтрива всички съществуващи лектори и ги създава наново, в двата езика и със снимките им. + +Скриптовете, които генерират програмата правят #href link-ове към страницата с лекторите, за да работят линковете. href-овете са наименувани като името на лектора. + +### load-program.php + +В този скрипт има няколко hardcode-нати неща, които в някой момент трябва да се изчистят: + +* map м/у id-тата на потоците и стиловете им в css-а +* преводи на разни string-ове +* id-та на статиите, в които се пише програмата (това може да се реши по-лесно с custom field и да се маркират някъде, а скрипта да ги търси) +* url-тата на страниците с лекторите (това също трябва да има по-чист начин) +* Също така би било хубаво да може да се извади някаква част от template-ите и да се избегне повторението за българския и английския на някакви части от кода + +### load-speakers.php + +В скрипта има hardcode-нато предположение къде се намират снимките на лекторите в clarion-а. + +todo: Скриптът зарежда два пъти снимката на лектора, веднъж за българския, веднъж за английския post, което трябва да може да се избегне. +todo: трябва да се вземат допълнителните полета от clarion (github и т.н.) и да се визуализират с някой стил. + +## functions.php + +Вътре са добавени няколко работни функции, които трябва в някакъв момент да се прегледат: + +* openfest_home_page() - връща дали е главната страница, поради един проблем, създаден от polylang, заради който is_front_page() не работеше. +* of_get_lang(), е_() - wrapper-и около polylang, ако липсва plugin-а. +* pn_get_attachment_id_from_url - отмъкната функция, която намира id на attachment от url, трябва при зареждането на снимките на лекторите.