MaxSite CMS
(c) http://max-3000.com/


Версия файла 1/12/2011
-----------------------

Также см.:

	* Новый default-шаблон MaxSite CMS
	  http://maxsite.org/page/novyj-default-shablon-maxsite-cms

	* Использование CSS-стилей в шаблоне Default 
	  http://maxsite.org/page/ispolzovanie-css-stilej-v-shablone-default
	
	* Компоненты в шаблоне Default
	  http://maxsite.org/page/components-default-template

	* Дополнительные возможности шаблона Default 
	  http://maxsite.org/page/default-custom

	* Пример создания компонента для шаблона MaxSite CMS
	  http://maxsite.org/page/primer-sozdanija-komponenta-dlja-shablona-maxsite-cms
	

ПРЕАМБУЛА
---------
Default - лишь один из вариантов создания шаблона на MaxSite CMS. Вебмастер вправе использовать свой алгоритм и свои
наработки. Данный вариант не накладывает никаких ограничений на работу других шаблонов.


ВВЕДЕНИЕ
--------
Новый Default шаблон позволяет делать шаблоны двух видов:
	- в рамках default - в этом случае используется каталог default, в котором размещаются свои дополнительные файлы. 
	  Этот вариант удобно использовать, если основная правка и изменения лежат в css-стилях. Устройство шаблона таково,
	  что при обновлении MaxSite CMS измененные файлы не будут затёрты, а блогер получит новые возможности обновленного 
	  шаблона. Естественно, при таком варианте следует придерживаться установленных правил (об этом ниже).
	  
	- Отдельный каталог шаблона. В этом случае шаблон создаётся путем копирования default шаблона и все изменения производятся
	  уже в отдельном каталоге. Default-шаблон устроен так, чтобы после копирования полностью сохранить работоспособность
	  и функциональность. Однако следует учитывать, что существует определённые правила при копировании исходного default-шаблона,
	  которых желательно придерживаться. Например в default-шаблоне лучше всего оставить некоторые функции, и часть сложного
	  php-кода. В этом случае в новом шаблоне просто подключаются функции default-шаблона, что гарантирует совместимость 
	  с будущими версиями MaxSite CMS и при этом не требуется заботиться об обновлении своего шаблона. 


Перед началом работ следует ознакомиться с основными понятиями.


КОМПОНЕНТЫ
----------
Компоненты находятся в каталоге шаблона components представляют из себя обычные php-файлы. Функционально компонент является
отдельным самостоятельным блоком, который выводится в шаблоне.

	- Компонент подключается в main.php и представляет собой исполняемый php-файл
	- Компонент должен обладать собственными css-классами. Использование ID не приветствуется.
	- Компонент может использовать свой js. Файлы js следует размещать в каталоге components/js.
	- Компонент может подключать свои css-стили. Css-файл компонента располагается в components/css. Имя файла должно 
	  совпадать с именем компонента.
	- Компонент может создавать свои опции (ini-файл), который следует разместить в components/options. Если ini-файл 
	  использует PHP_START...PHP_END, то функцию опции следует разместить в php-файле в этом же каталоге. Имя файла 
	  совпадает именем компонента. См. пример компонента image-select.

Смысл компонента в том, чтобы разделить модульную сетку шаблона от его наполнения. В main.php задаётся html-структура 
шаблона, не заботясь о его функциональном наполнении. В шаблоне лишь прописывается несложный php-код, который отвечает 
за подключение компонентов. Какой именно это будет компонент зависит от выбора пользователя: компоненты произвольно
выбираются в Настройке шаблона. Именно поэтому для компонентов важно обеспечить коректное отображение в любом месте 
шаблона. Делается это за счет обрамляющих div-блоков и стилей, не зависимых от расположения компоненты в модульной сетке
шаблона.



ПРОФИЛИ CSS
-----------
Профиль CSS представляют собой обычные css-файлы, которые располагаются в каталоге шаблона css/profiles. Код профилей
выводится в html-секции HEAD шаблона после подключения основных css-файлов, что позволяет в профилях переопределять 
некоторые стили. Например в файле font-segoe.css переопределяется основной шрифт сайта, а в dark-theme.css переопределены 
некоторые цвета шаблона.

Таким образом вебмастер с помощью профиля может произвольно менять стиль оформления, не заботясь о сложном и громоздком 
style-all.css, содержащему все стили для всех элементов шаблона, плагинов, хелперов и т.п.



ПРАВИЛА ИМЕНОВАНИЯ ФАЙЛОВ
-------------------------
Для того, чтобы избежать замен изменённых файлов, следует избегать совпадения имён с default-шаблоном. Вместо этого 
лучше использовать предусмотренные расширения. Обратите внимание, что в шаблоне находятся заготовки файлов, которые 
начинаются с символа подчеркивания «_». Шаблон никак не использует эти файлы и они служат лишь заготовкой. Чтобы шаблон 
стал их использовать следует удалит ведущий «_». Это правило распространяется на все файлы шаблона.

Каталог /custom/:
	my_meta.ini - свои мета
	my_options.ini - свои опции
	my_options.php - свои функции для опций (options.php)
	my_functions.php - свои функции
	
	main-out-start.php - подключается перед выводом основного блока (перед $MAIN_OUT)
	main_out.php - подключается, если используется свой код вывода
	main-out-end.php - подключается в конце вывода основного блока (после $MAIN_OUT)
	sidebars.php - подключается, если используется свой код вывода сайдбаров
	
	header-start.php - в начале шапки
	header-end.php - в конце шапки
	content-start.php - в начале основного блока
	footer-start.php - в начале подвала
	footer-end.php - в конце подвала
	
	head-section.php - выделенный в отдельный файл секция HEAD.
	head.php - подключается в секции HEAD
	
	- подключаются в соответствующих частях. По возможности лучше использовать обычные компоненты, вместо этих файлов. 
	Использовать можно для сложных вариантов, когда файл должен подключаться всегда, не зависимо от выбора компонентов 
	пользователя системы.

При создании нового шаблона вне каталога default желательно также использовать файлы каталога custom. Это позволяет 
полностью отделить свои изменения от дефолтных и несколько удобней в плане редактирования: все изменения будут в одном месте.


ИСПОЛЬЗОВАНИЕ УШЕК. ОБЩАЯ СТРУКТУРА ШАБЛОНА (main.php)
------------------------------------------------------
В main.php предопределено несколько ушек, которые позволяют разместить произвольный HTML/PHP-код в шаблоне,
без использования custom-файлов. По сути ушки выполняют роль дополнительных компонентов, содержимое которых
доступно в админ-панели, что делает их редактирование более гибким и удобным. Там, где используется вывод
самостоятельных блоков, рекомендуется использование именно ушек, а не custom-файлов. Примеры: баннеры, рекламные
тексты, вставка php-кода бирж ссылок (например sape), счетчики и т.п.

Общая схема подключения компонентов и ушек в HTML-структуре шаблона (main.php).


	****************************************************************************
	секция HEAD (функция mso_default_head_section или файл custom/head-section.php)
	
	div.all
		div.all-wrap
			div.section header-main
			
				ushka('header-pre')
				
				div.header
					div.header-wrap
						custom/header-start.php
						ushka('header-start')
						
						компоненты шапки
						
						ushka('header-end')
						custom/header-end.php 
					/div.header-wrap
				/div.header
				
				ushka('header-out')
				
				div.section article main
					div.main-wrap
						custom/content-start.php
						ushka('content-start')
						
						div.content
							div.content-wrap
								ushka('main-out-start')
								custom/main-out-start.php
								custom/main-out.php или вывод содержимого
								ushka('main-out-end')
								custom/main-out-end.php
							/div.content-wrap
						/div.content

						custom/sidebars.php или вывод сайдбара

						div.clearfix/
					/div.main-wrap
				/div.section article main
			/div.section header-main

			div.footer-do-separation/
			
			ushka('footer-pre')
			div.footer
				div.footer-wrap
					custom/footer-start.php
					ushka('footer-start')
					
					компоненты подвала
					
					ushka('footer-end')
					custom/footer-end.php'
				/div.footer-wrap
			/div.footer
		/div.all-wrap
	/div.all

	ushka('google_analytics') 
	ushka('body_end')
	****************************************************************************



ПОДКЛЮЧЕНИЕ CSS
---------------
В секции HEAD подключение css-стилей производится по следующим правилам:

	1. Каталог шаблона /css/.
	2. Если присутствует файл css.php, то подключается он.
		- Если нет, то подключается my_style.css.
			- Если и его нет, то style-all-mini.css.
				- Если и его нет, то style-all.css.
					- Если и его нет, то default/css/style-all-mini.css.
	3. После этого подключаются стили компонентов (components/css)
	4. Подключаются выбранные css-профили (css/profiles)/
	5. В завершении подключается css/add_style.css, если есть.

При создании нового шаблона вне каталога default оптимальней всего использовать add_style.css. Если 
не использовать style-all-mini.css и style-all.css своего шаблона (его можно скопировать из default),
то базовые css-стили будут автоматически загружаться из default-шаблона.

Файл style-all-mini.css представляет собой сжатую версию style-all.css. Для сжатия css-кода можно
воспользоваться различными утилитами, например http://www.cssdrive.com/index.php/main/csscompressor/
или http://csstidy.sourceforge.net/index.php


ОПИСАНИЕ ФАЙЛОВ ШАБЛОНА
-----------------------
* info.php - содержит информацию о шаблоне: автор, версия и т.п.

* index.php - т.н. диспетчер типов данных. Как правило этот файл не требуется изменять. В нём заключена логика подключения
  type-файлов.

* main-start.php - файл в котором включается буферизация вывода перед работой type-файла.

* main-end.php - файл в котором результат буферизации сохраняется в php-переменной. После этого идет подкючение main.php

* main.php - основной файл html-разметки шаблона. В нём, помимо html-кода выполняется подключение компонентов.

* options.php - файл, обслуживающий опции шаблона. В нём происходит подключение нужных ini-файлов.

* options.ini - опции шаблона. Здесь описаны опции шаблона в виде секций стандартного ini-файла. Как правило в других 
  шаблонах происходит подключение options.ini из default-шаблона. Сделано это из соображений исключения дублирования. 
  
* options-template.ini - опции текущего шаблона. Разделение опций на два файла позволяет сторонним шаблонам использовать
  default/options.ini без необходимости удалять неиспользуемые опции.
  
* meta.ini - метаполя записей. Подключение и обработка метаполей осуществляется на уровне системы.

* functions.php - специальный файл, который автоматически подключается при инициальзации системы. Поэтому здесь 
  располагаются функции, которые используются как шаблоном, так и админ-панелью (или другими частями системы). Здесь 
  осуществляется регистрация сайдбара, переопределение некоторых переменных.
  
* functions-template.php - содержит функции шаблона. Файл подключается в functions.php. Вынесение функций в отдельный 
  файл сделано с целью упростить читабельность functions.php, а также предоставить возможность другим шаблонам 
  использовать функции из default.
  
* screenshot.jpg - скриншот шаблона. Всегда должен быть размером 250x200px. 



ПОРЯДОК СОЗДАНИЯ НОВОГО ШАБЛОНА ВНЕ КАТАЛОГА DEFAULT
----------------------------------------------------
1. Создаём новый каталог для своего шаблона.

2. Копируем в него все файлы из default, КРОМЕ (описание см. ниже):
	- каталога type
	- каталога _type_foreach
	- файла functions-template.php
	- файла options.ini
	- файла readme.txt
	- файлов css/style-all-mini.css и css/style-all.css, если будут использованы базовые default-стили

3. Копируем в свой каталог собственные компоненты, профили и т.п.

* Каталог type - получение данных типа. Подробнее см. http://maxsite.org/

* Каталог _type_foreach - заготовки type_foreach-файлов. Подробнее см. http://maxsite.org/

* Файл default/functions-template.php содержит функции для работы с шаблоном. Файл подключается в functions.php. 
  Следовательно в свой шаблон не нужно копировать functions-template.php, а подключать его прямо из default-каталога.
  
* Файл options.ini в default-каталоге содержит опции, которые являются дефолтными для всех шаблонов (как правило). Поэтому
  его использовать не желательно. Вместо него лучше использовать options-template.ini, который содержит опции относящиеся
  только к текущему шаблону. Следует отметить, что файлы опций подключаются в шаблонном options.php, который вебмастер
  может переопределить по своему усмотрению.

Кроме того при создании шаблона нужно использовать «_»-файлы из каталога custom. В этом случае шаблон можно будет безболезненно
обновлять, если изменится default-шаблон в новых версиях MaxSite CMS.



ОБНОВЛЕНИЕ СВОЕГО ШАБЛОНА ВНЕ КАТАЛОГА DEFAULT
----------------------------------------------
В новых версиях MaxSite CMS может меняться default-шаблон. Изменения могут касаться как изменений в основных файлах, 
вроде main.php, так и какие-то новые дополнения, например css-профили и компоненты. Обновление своего шаблона следует 
делать в нескольких случаях:
	- если шаблон публичный, следовательно он должен поддерживать все последние возможности из default-шаблона;
	- если в предыдущей версии default-шаблона были недочеты и ошибки, которые перекочевали в ваш шаблон.
	
Идеальный вариант, когда при создании своего шаблона вы используете именование файлов, отличных от default-шаблона. 

Например все свои компоненты следует сопровождать каким-то префиксом (например «my_»), чтобы их однозначно отличать.
Если у вас много различных компонентов для разных сайтов, то можно в качестве префикса использовать имя сайта, 
например «maxsite-org-header.php».

Таким образом, обновление своего шаблона сведется к простому копированию новых файлов компонетов из default-шаблона.

Что касается css-стилей, то если ваш шаблон использует только add_style.css, то можно без проблем 
использовать базовые стили из default-шаблона. Для того, чтобы автоматичести загружались default-стили нужно удалить из своего
шаблона файлы style-all-mini.css и style-all.css. В таком варианте default-стили будут автоматом обновляться вместе с MaxSite CMS.

Если предполагается «зафиксировать» стили, то можно скопировать из default-шаблона style-all.css и style-all-mini.css 
и дальше с ними работать на уровне своего шаблона. В этом случае вопросы обновления стилей ценликом ложится на вебмастера.

Если вы используете для css-профилей префиксы, чтобы они отличались от дефолтных, то профили можно просто обновить 
из default-шаблона.


ОПЦИИ ШАБЛОНА
-------------
Алгоритм подключения файлов опций заключен в файле шаблона options.php. Он копируется в свой шаблон без изменений. 
Порядок подключения опций будет таков:

	- default/options.ini 
		Основные базовые опции шаблонов. Как правило их не требуется менять от шаблона к шаблону.
		Данные опции используются в type-файлах, поэтому менять их следует с осторожностью.
		
	- options.ini
		Специфичные опции, имеющие отличия от default-шаблона.
		
	- options-template.ini
		Опции относящиеся только к текущему шаблону. Например в default-шаблоне указывается расположение блоков.
		
	- custom/my_options.php
	- custom/my_options.ini
		Опции расширяющие опции шаблона. Если это каталог Default, то расширение опций default-шаблона.
	
	- components/options/*.php
	- components/options/*.ini
		Опции компонентов.

При использовании опций следует учитывать тот момент, что некоторые опции могут не поддерживаться между шаблонами. 
Например шаблон может не поддерживать какие-то default-опции (из default/options.ini). В таких случаях, хорошим 
тоном будет скрытие в шаблоне неиспльзуемых опций. 

	ВАЖНО! Скрытие опций не означает их уделения из базы. Они просто будут недоступны в админ-панели.

Скрыть неиспользуемые опции проще всего в ini-файле путём добавления пустых секций. Например, шаблон
не поддерживает опцию «Текст для главной перед всеми записями», которая определена в default/options.ini. 
В своём шаблоне в любом из файлов:
 
	custom/my_options.ini 
	или 
	options-template.ini 
	или 
	options.ini
	
	пишем:

	[Текст для главной перед всеми записями]

Теперь данная опция будет скрыта в админ-панели. 

Какой именно использовать ini-файл в своём шаблоне зависит от вебмастера и поставленной задачи. Если опции добавляютя 
непосредственно в каталог default-шаблона, то выбор один - custom/my_options.ini. Он не потеряется при обновлении системы.

Если же шаблон использует отдельный каталог, то следует определить в каком объеме он будет поддерживать возможности default-шаблона.
Если предполагается, что шаблон будет полностью совместим, то файл options-template.ini можно скопировать из default-шаблона без изменений. Файл options.ini уже не потребуется, а свои опции можно внести в custom/my_options.ini.

Если же шаблон лишь частично будет поддерживать опции из default/options-template.ini, то можно указать поддерживаемые опции как в 
options-template.ini или в options.ini - они полностью равнозначны. Следует только учитывать, что если предполагается 
обновление шаблона из default, то эти файлы не должны быть затерты. 
