README.txt файл

11:55:31 часа на 28 юли 2017 Visited: 12744, Today: 0

Система за управление на съдържанието VanyoG CMS
================================================

Автор: Ваньо Георгиев http://vanyog.com.
Започната през декември 2010 г.
Хранилище с програмен код https://github.com/vanyog/mycms

Този README-bg.txt файл съдържа кратко общо описание на системата и е съществена част от документация по нея.
По-практични указания за ползване на системата ще намерите на адрес https://github.com/vanyog/mycms/wiki и във файл USEAGE.txt.

ИДЕИ ЗА ГЛАВНИТЕ ВЪЗМОЖНОСТИ НА СИСТЕМАТА

- минимализъм - постигане на много възможности с малък размер на системата (към момента 2.3 МБ заемано място от диска), но стремежът към минимализам означава още и, че всяка част на системата се зарежда само при нейното използване
- бързина, която се постига чрез кеширане на страниците и избягване на излишни действия
- насоченост към SEO
- позволява инсталиране на работещ сайт заедно с друга система и постепенно пренасяне на съдържанието му в тази система
- позволява поддържане на многоезични сайтове, добавянето на нов език се извършва с лесна настройка
- лесно добавяне на страници и структуриране на сайт (групиране на страниците в менюта и подменюта и местене от едно меню в друго)
- редактирането на всички файлове и данни на сайта може да се извършва и само през браузър; редакторът, който се използва за тази цел, редактира HTML (или друг програмен) код, но има възможност да се ползва и WYSIWYG редактор (CKEditor - https://ckeditor.com)
- дава пълна свобода за съставяне на съдържанието на страниците, системата е отворена и позволява добавяне на PHP скриптове за генериране на произволно сложно специализирано съдържание
- модулен характер - състои се от главна библиотека в директория lib и независими модули, всеки в собствена директория, в поддиректория mod или избрана от потребителя друга директория (по подразбиране _mod)
- независимост на модулите и функциите - желанието е всеки модул да може да се използва и "без цялата системата", само с include() да се декларира съответния файл и да се ползват дефинираните в този файл функции
- кои HTML и CSS стандарти се спазват е избор на разработчика и не се налагат от самата система, но старанието е да се ползват най-новите стандарти
- системата е ориентирана повече към улесняване работата на програмисти, създаващи сайтове, но и с намерение да се направи лесна за използване и от собственици на сайтове, желаещи сами да поддържат съдържанието им
- позволява лесно преминаване на всяка страница от локално копие на сайта към работещото онлайн копие и обратно, както и бързо прехвърляне на съдържание от едното към другото копие

ИЗИСКВАНИЯ ЗА СЪРВЪРА

Създаването на системата е стартирано при следните версии сървърен софтуер:

Apache 2.2.12
MySQL 5.1.37
PHP 5.3.0

но системата се поддържа така, че да е съвместима с последните версии сървърен софтуер, предлаган в абонаментните планове за споделен хостинг. Иначе, съвместимостта с различни сървърни конфигурации не се следи стриктно и не се регистрира с кои версии възникват проблеми. При установяване на проблем веднага се правят промени в най-новата версия на системата, които да го отстранят.

Промени, подобрения и допълнения към системата се правят при всяко възникване на необходимост от такива на сайтовете на които тя се използва.

КРАТКО ОПИСАНИЕ

Разбирането на структурата и начина на функциониране на системата е съществено за нейното успешно използване!

Общата концепция е следната:

Съдържанието на всички страници се съхранява в базата данни и се генерира с помощта на шаблони и PHP скриптове генериращи html код.

Настройки

Настройките, с изключение на данните за достъп до базата данни, се съхраняват в таблица $tn_prefix.'options' и съответно се четат и записват с функциите stored_value($n) и store_value($n,$v), дефинирани във файл lib/f_stored_value.php. ($tn_prefix е представка към имената на таблиците в базата данни, задава се във файл conf_database.php.)

Шаблони

Шаблоните се съхраняват в таблицата от базата данни $tn_prefix.'templates'.

Шаблонът представлява html код с вмъкнати в него елементи от вида: , където XXXX са различни имена с добавени към тях и параметри, когато е необходимо. Тези елементи при генериране на страница се заместват с друг html код. Замяната се извършва от скрипта index.php чрез извикване на функцията parse_template() (от файл lib/f_parse_template.php), която от своя страна извиква parse_content() от файл lib/f_parse_content.php.

Един шаблон може да бъде наследник на друг шаблон, т.е. да се вмъква в друг шаблон. В кой друг шаблон трябва да се вмъкне даден шаблон се посочва в полето parent на записа му в таблица $tn_prefix.'templates'. Ако това поле е нула, шаблонът не се вмъква в друг шаблон, т.е. такъв шаблон е стеблото на дърво от шаблони наследници. Мястото в което се вмъква шаблон наследник се означава в родителския шаблон с .

Вмъкването на шаблоните един в друг се извършва от функцията parse_template(), която първо вмъква шаблона на текущата страница в неговия родител, после вмъква получения нов шаблон в родителя на родителя и т.н. до шаблон без родител. Така се получава целия шаблон на текущата страница, който се подава на функция parse_content(), за да се извърши генериране на отбелязаните с  елементи на html кода на страницата, чрез зареждане и извикване на съответстващите им модули.

Елементите  се заместват в ред отзад-напред, първо се замества последния, после предпоследния, и т.н. до първия.

Страници

Страниците от сайта се описват в таблица $tn_prefix.'pages', където в записа за всяка страница се посочва: нейния номер; името на стринга, съдържащ заглавието; името на стринга съдържащ основния HTML код на страницата; номерът на шаблона за генериране на цялата страницата и др. (Повече вижте в описанието на полетата на тази таблица по-долу.) Всяка страница се отваря на адрес:
http://ДомейнНаСайта/ПапкаНаСистемата/index.php?pid=IDнаСтраницата.
(Някои модули може да допълват адресите на страниците с необходими за тях параметри.)

По желание, приемливи за SEO адреси, не съдържащи символи ?, & и =, се постигат чрез RewriteEngine на Apache сървъра с добавяне на следните редове:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([a-zA-Z0-9\-]+)(/?)$ /index.php?pid=$1 [QSA]

във файл .htaccess. Ако се направи това, трябва в таблица $tn_prefix.'options' да се зададе опция с име 'RewriteEngine' и стойност 'on'. При наличие на тази опция, страница с адрес, например: /index.php?pid=20, може да се отвори и с адрес: /20/. Модулите, които генерират адреси, например: SITEMAP, OUTERLINKS и др., следва да генерират такива SEO адреси. Тази идея още не е ползвана по-широко на работещи сайтове и е още в процес на разработване.

Работи се по система за използване на адреси от вида: zaglavie-na-stranica, вместо номера. За да се използват такива адреси се съставя таблица на базата данни $tn_prefix.'seo_names'. Попълването на таблицата се извършва със скрипта: manage/make_seo_names.php, който трябва да се изпълни еднократно от администратора. За да започне да се използва тази възможност, трябва да се зададе опция с име 'SEO_names' и стойност 'on'.

За да се избегне това една страница да се отваря едновременно на три различни адреса, например:
/index.php?pid=20
/20/ или
/zaglavie-na-stranica/
се задава опция с име 'redir_pids' и стойрост 'on', което пренасочва само към адрес от вида /zaglavie-na-stranica/.

Текстове

Всички показвани на страниците надписи и текстове се съхраняват в таблицата $tn_prefix.'content' и могат да бъдат на различни езици. Езиците, на които се показват текстове на сайта се задават в настройката 'languages'. Всеки текст или надпис се идентифицира с име, което е еднакво за преводите на този текст на всички езици. Надпис се показва с функцията translate($n) (дефинирана във файл f_translate.php), в която $n е името на надписа. Вижте повече в коментарите във файл f_translate.php.

Менюта

Структурирането на сайта се осъществява чрез групиране на страниците в дървовидна схема от раздели, подраздели, под-подраздели и т.н. Всички страници от конкретен раздел (група) от тази йерархия имат еднакъв номер на полето `menu_group` в таблица $tn_prefix.'pages'. За да бъде една група страници подгрупа в друга група, се създава запис в таблица $tn_prefix.'menu_tree', който означава, че групата с номер стойността на полето `group` е подгрупа на групата с номер стойността на полето `parent`. Същият запис посочва със стойността на полето `index_page`, кой е номерът на главната страница на групата. Стойност на полето `parent`=0 означава коренова група - група от която започва разклоняването на сайта на раздели.

Няма пречка на един сайт да има няколко коренови групи. Няма пречка и графът от връзки между страниците да не е дърво.

Нормално е в шаблона на всяка страница да се вмъкне елемент , което предизвиква показване на мястото на този елемент на меню - хипервръзки към страниците от същата група.

Елементи за генериране на съдържание

В текстовете, също както и в шаблоните, може да има  елементи, които се заместват с друг HTML код, генериран от модули и скриптове. Заместването на тези елементи се извършва от функцията parse_content(), дефинирана във файл f_parse_content.php, а самата тя се извиква от функцията translate() след извличане на даден превод на текст от таблицата $tn_prefix.'content'.

Модули

Частта означена с XXXX в елементите от вида  има формат ИмеНаМодул или ИмеНаМодул_Параметри. Дали да се използва формат без параметри или формат с параметри зависи от конкретния модул или скрипт. Някои модули не изискват параметри, други изискват параметри във вид на стринг, съставен по специфични за модула правила. (За изискванията на всеки модул има информация в README.txt файла в директорията на модула, или ако няма такъв файл - в коментарите в програмния код на модула.)

Имената на модулите в елементите  е прието да се изписват само с главни букви. Във файловата система модулите са директории с имена изписани с малки букви. (Името на модул не може да съдържа символ _ (долно тире)!) В директорията на модула трябва да има файл с име f_xxxx.php, в който да е дефинирана функция с име xxxx(), приемаща, ако е необходимо, само един стрингов параметър.

В директория mod се съхраняват стандартни (предлагани заедно със системата) модули, но по желание на разработчика на сайта, създадени от него модули може да се сложат в друга директория, която се указва с настройката 'mod_path' в таблица $tn_prefix.'options'. По подразбиране това е поддиректория _mod. В тази директория може да се сложат и копия на стандартни модули, които да се модифицират според нуждите на конкретния сайт. parse_content() проверява за наличие на модул с дадено име първо в тази директория, а ако не намери - и в директория mod.

В директориите на модули, използващи специфични таблици в базата данни, трябва да има файл tables.sql, съдържащ SQL заявки за създаване и зареждане на тези таблици с минимален, задължително необходим за работата на модула набор от записи.

Модули, предназначени да се управляват от удостоверени потребители, след влизане с потребителско име и парола, могат да дефинират потребителско меню с действия, които потребителят може да извършва. Html кодът на това меню се генерира от функция xxxx_menu_items(), дефинирана във файл f_menu_items.php, на директорията на модула.

Стилизиране с CSS

В последните версии на системата (след 2023 г.) се лансира идеята всички CSS правила да се вмъкват в таговете <head> ... <style></style></head> на HTML кода на страниците. Ако има външен файл, който се ползва с таг <link rel="stylesheet" href="пътДоCSSфайл">, за да се вмъкне съдържанието на файла в HTML кода, този таг в шаблона за страници се заменя с

<style>
< !--$$_RAWFILE__styleR.css_$$-->
< !--$$_VARIABLE_added_styles_$$-->
</style>

При това се използват модулите: RAWFILE, който чете и вмъква съдържанието на външния файл и VARIABLE, който показва съдържанието на глобална променлива $added_styles.

Идията за променлива $added_styles е тя да се използва за колекциониране на всички CSS правила, които се добавят от други модули и функции, само ако в дадена страница се използват тези модули. Добавянето на CSS правила се извършва от функция add_style(имеНаСтил) от файл lib/f_add_style.php. Тази функция добавя към променлива $added_styles, правилата формулирани в опция с име 'css_имеНаСтил'. Списък на тези опции и възможност за редактирането им дава файл manage/edit_styles.php.

По-стара идея, която напоследък се изоставя, е във файл с име _style.css в директорията на модул да се сложат CSS дефиниции, с цел визуално форматиране на HTML елементите, генерирани от модула. Използването на файла _style.css може да се отмени в някои от страниците, ако името на модула, изписано с малки букви, се добави, заградено със запетаи, в глобална стрингова променлива $no_style. Добавянето може да се извърши посредством модул ADDTOVARIABLE, ката елемент за извикването му се поставя непосредствено преди таг </body>, така че да се изпълни преди всички останали модули.

Скриптове

Скриптовете представляват програмен код, написан на PHP, който се съхранява в таблица $tn_prefix.'scripts'. Скриптове се извличат и изпълняват от функция parse_content(), когато тази функция открие името на скрипт в някой елемент от вида .

Филтри

Филтрите са функции, дефинирани във файловете от директория filter. Тези функции автоматично променят или допълват някои срещащи се в текстовете фрагменти. (Например: филтърът email превръща всеки срещащ се в текста имейл адрес в хипервръзка, която да отвари програма за писане на имейли.) Кои филтри да се приложат към даден текст се посочва в таблица $tn_prefix.'filters'.

КЕШИРАНЕ

С цел постигане на бързодействие пълният html код на страниците се съхранява в таблица $tn_prefix.'page_cache'. Интервалът време, през който се опресняват записите в тази таблица се задава в минути с настройката с име 'chache_time'. Ако тази настройка не е зададена или е 0, не се извършва кеширане, а ако е -1 кешът е “вечен” и се опреснява само след извършване на промени в страницата.
Не се извършва кеширане: при отваряне на страниците от администратори; на страниците със стойност 1 на полето `donotcache`; както и на страници, които получават данни с POST метод или ако масив $_SESSION не е празен.
Ако не са налице изброените обстоятелства, страници със стойност -1 на полето `donotcache` задължително се кешират, независимо от глобалната настройка 'chache_time'.

УГОВОРКИ

Директорията $adm_pth, зададена във файл conf_paths.php, съдържа скриптове за администриране на системата. За повишаване сигурността на системата скриптът manage/_secure.php съставя ново име на тази директория, представляващо случайна поредица от букви и цифри и запазва новото име в настройките на системата. Наред с това, преименуваната директория следва да бъде и защитена с парола.

Имената на модулите в елементите , подлежащи на заместване в шаблоните и в текстовете на страниците, се изписват само с главни букви.

Имената на надписите, функциите и настройките, използвани в модули трябва да започват с ИмеНаМодул_. Това улеснява тяхното отделяне от същите елементи на други модули, например, при съставяне на tables.sql файла на модула, при превеждане на неговите надписи или при деинсталиране на модула.

ПРЕФИКСИ В ИМЕНАТА НА ФАЙЛОВЕТЕ:

conf_ - файлове съдържащи настройки
f_ - файлове дефиниращи функции
f_db_ - файлове дефиниращи функции за извличане/записване на информация в базата данни
f_stat_ - функции за статистически изчисления
o_ - файлове дефиниращи PHP обекти

ПРОСЛЕДЯВАНЕ НА ИЗПЪЛНЕНИЕТО

При добавяне на параметър debug=1 в началото на страницата се показва информация за процеса на генериране на страницата:
- Последователността на вмъкване на шаблони се описва с редове от вида: Template(X) A/B C/D,
- последователността на извикване на модули във вида: Module XXX(P) A/B C/D,
- последователността на извикване на скриптове във вида: Script XXX(P) A/B C/D,
където X е номерът на шаблон, ХXX - името на модул или скрипт, P параметър, предаван на модула или скрипта,
A - броят на изпълнените от модула, а B - общият брой на изпълнените до момента заявки към базата данни,
C - времето в милисекунди за изпълнение на модула, D - общото време в милисекунди за изпълнение на страницата до момента.

ГЛАВНИ ТАБЛИЦИ В БАЗАТА ДАННИ

Във всички таблици има поле с име ID и опции primary index и auto_increment, затова това поле няма да се споменава в описанието на таблиците. Полето представлява автоматично поставян, уникален номер на записа в таблицата.

$tn_prefix.'templates' - съхранява шаблоните за генериране на страници
----------------------
Полета:
parent - родител на шаблона. Използва се, когато шаблонът трябва да се вмъкне в друг шаблон, за да оформи страница.
template - html код на шаблона.
comment - описание на шаблона.

$tn_prefix.'content' - съхранява текстове, преведени на различни езици.
--------------------
Полета:
name - име на текста
nolink - флаг, който ако е 1 не позволява в режим на редактиране след надписа да се показва линк *. Използва се, когато този линк би нарушил валидността на html кода.
date_time_1 - дата и час на първото му въвеждане
date_time_2 - дата и час на последната му редакция
language - двубуквено означение на езика, например: 'bg','en' и т.н.
text - текст в html формат, съдържащ евентуално и  елементи.

$tn_prefix.'pages' - съхранява информация как да се генерира всяка страница
------------------
Полета:
menu_group - номер на групата хипервръзки, които се показват като меню заедно със страницата
title - име на заглавието на страницата, което се взема от таблица $tn_prefix.'content'
content - име на съдържанието на страницата, взема се от таблица $tn_prefix.'content'
template_id - номер на шаблона, по който се съставя страницата, взема се от таблица $tn_prefix.'templates'
hidden - логическо поле, което ако е 1 означава, че страницата не трябва да се показва в навигацията на сайта
options - поле, което съдържа флагове, използвани за предаване на информация към различни функции за генериране на съдържание, например, размери на google реклами
dcount - брой показвания на страницата през денонощието
tcount - общ брой показвания на страницата от момента на пускането й

$tn_prefix.'scripts' - съхранява скриптове, които се извличат и се изпълняват с eval(), за да генерират html код за заместване на  елементите
-----------------------
Полета:
name - име, което съвпада с XXXX името
script - php код
coment - текстово описание на скрипта (нещо като help)

$tn_prefix.'menu_items' - съхранява информация за съставяне на менюта от хипервръзки
-----------------------
Полета:
place - числа, задаващи реда на подреждане на хипервръзките в менюто
group - номер на менюто, към което принадлежи хипервръзката
name - име на текста, с който се показва хипервръзката
link - url, към който сочи хипервръзката. Обикновено и число - номер на страница от сайта, но може да е и друг url.

$tn_prefix.'menu_trees'. Предвидено е менютата да образуват дървовидна структура и някои менюта да са "деца" на други менюта. Тази таблица се посочва родителското меню на всяко меню "дете".
-----------------------
Полета:
group - номер на менюто (групата хипервръзки)
parent - номер на родителя на менюто
index_page - номер (ID) на страница от таблица $tn_prefix.'pages', която се явява главна страница на менюто

$tn_prefix.'visit_history' - съхранява броя на посещенията на всяка страница по дни
--------------------------
page_id - номер на страницата
date - дата на записване на информацията. Броят на посещенията се отнася за предишното на тази дата денонощие.
count - брой посещения на страницата през предишното денонощие

$tn_prefix.'content_history' - отразява динамиката на изменение на обема на сайта
---------------------------
date - дата, на която е записан обема на сайта
size - обем на сайта, измерен в брой битове на поле `text` на записите от таблица $tn_prefix.'content'

$tn_prefix.'options' - за съхраняване на настройки и други стойности
--------------------
name - име на настройката или стойността
value - стойност. Може да бъде и php код, който с eval() да създаде и присвои стойност на променлива.

$tn_prefix.'filters' - посочва кои филтри да се приложат към текстовете от таблица $tn_prefix.'content'
--------------------
name - име на текста. Ако е '*' списъкът от филтри се прилага върху всечки стринговете, представляващи съдържание на страници.
filters - списък от разделени със запетаи имена на филтри, които да се прилагат върху текста с име name

$tn_prefix.'page_cache' - съхранява пълният html код на страниците с цел кеширане и постигане на бързодействие
-----------------------
page_ID - номер (ID) на страницата
language - език на страницата
date_time_1 - дата и час на последното записване на html кода в тази таблица
text - пълен html код на страницата
referer - адрес, от който е дошъл посетителя в момента на запазване в кеша

$tn_prefix.'page_cache' - SEO адреси на страниците
-----------------------
ID - номер на страница
seo_name - SEO адрес на страница

Модулите, при своето инсталиране, създават собствени таблици, които са описани в README.txt файловете в директориите на модулите.

Инструкции за използване на системата на български ще намерите във файл USAGE.txt.

ЗА ПОВЕЧЕ ИНФОРМАЦИЯ разгледайте коментарите в php файловете.

За контакт с автора посетете сайта vanyog.com.

Системата може да изтеглите от адрес: https://github.com/vanyog/mycms