# Eshop Optima

Интернет-магазин на базе Битрикс и наших внутренних наработок.

# Описание структуры файлов

```
(00) .
(01) +-- ajax
(02) +-- bitrix
(02a)|   +-- admin
(02b)|   +-- php_interface
(03) +-- _optima
(04) |   +-- catalog_armatura
(05) |   +-- news
(06) |   +-- ...
(07) +-- catalog
(08) +-- news
(09) +-- ...
(10) +-- local
(11) |   +-- admin
(12) |   +-- classes
(13) |   +-- components
(14) |   +-- modules
(15) |   +-- php_interface
(16) |   +-- cron
(17) |   +-- templates
(18) |       +-- .default
(19) |       |   +-- components
(20) |       |   +-- js
(21) |       |   +-- css
(22) |       |   +-- img
(23) |       |   +-- _source
(24) |       +-- customize-me
(25) |   +-- vendor
(26) +-- upload
(27) +-- include_areas
(28) +-- ...
```

#### (01) ajax
В этой папке лежит ровно один файл index.php, общий, он разбирает запрос и вызывает соответствующий метод
соответствующего класса. Модифицировать этот файл под конкретный проект — не нужно.

Запросы имеют вид ```/ajax/?mod=НазванияКласса&act=НазваниеМетода&other_stuff```

#### (02) bitrix
Стандартное ядро Битрикс, мы не трогаем эту папку, только файлы ```.settings.php``` и ```php_interface/dbconn.php```.
```init.php``` располагается в ```/local/php_interface/init.php```.

#### (02b) admin
Кастомные разделы административной панели мы размещаем в той же папке, в которой битрикс размещает стандартные разделы.
Но делаем это аналогичным образом — в файле не должно быть ничего, кроме include соответствующего файла из папки local.
Файлы админских разделов должны начинаться с префикса ```webprofy_```.

#### (03) _optima
В этой папке лежат настроенные разделы сайта в том виде, в котором клиент их может скопировать
в корень сайта и начать использовать с минимальными изменениями.
На заглавной странице index.php выводится список таких разделов с описанием функционала
и инструкцией по подключению этого раздела.

В Большой Оптиме (eshop.optima.webprofy.ru) такие разделы сайта представлены в нескольких вариантах,
также присутствуют разделы, которые не входят в стандартную поставку Оптимы. Перед сдачей сайта мы должны удалить
лишние варианты и разделы, оставив только то, что было включено в КП для клиента.

#### (04) _optima/catalog_armatura
Настроенный раздел сайта, готовый к использованию. Структура файлов:
```
(00) /_optima/catalog-armatura/
(01) +-- .section.php
(02) +-- index.php
(03) +-- readme.md
(04) +-- contentplan_catalog.xslx
(05) +-- contentplan_catalog.php
(06) +-- images
```
В readme.md содержится описание раздела.
Для динамических разделов (с комплексными компонентами) должен быть приведён список страниц и по каким ЧПУ они открываются.
Далее идёт описание каждой простой страницы, с описанием поведения страницы и указанием используемых компонентов и шаблонов.

В contentplan_catalog.xslx — Рыбный контент для импорта через Инспектор контента

В contentplan_catalog.php — настройки Инспектора для импорта и валидации контент-плана.

В images размещаются изображения для контент-плана, для импорта через инспектор.

#### (04) _optima/news
Настроенный раздел сайта, готовый к использованию. Аналогично (03) catalog_armatura

#### (07) catalog
```
(00) /catalog/
(01) +-- .section.php
(02) +-- index.php
```
Здесь размещается презентационный вариант каталога — то есть пример раздела "Каталог".
Фактически — это должна быть копия /_optima/catalog-armatura/index.php (или любого другого варианта, который мы сочтём
наиболее репрезентабельным). Readme, контент-планов и прочего в этой папке не размещается.

#### (08) news
```
(00) /news/
(01) +-- .section.php
(02) +-- index.php
```
Аналогично (07) catalog

#### (11) local/admin

Здесь размещаются кастомные разделы административной панели.
Для каждого такого раздела в папке /bitrix/admin/ должен быть создан файл вида webprofy_название_раздела.php, в котором
должен быть include соответствующего файла из /local/admin/

#### (12) local/classes

Классы, размещённые по папкам-неймспейсам. Подключаются автоматически в init.php
Каждый класс документирован по коду, в формате phpDoc.

#### (13) local/components

Наши компоненты и шаблоны наших компонентов.

```
(00) /local/components/
(01) +-- webprofy
(02) |   +-- catalog.favorites.list
(03) |   |   +-- lang
(04) |   |   |   +-- ru
(05) |   |   |   +-- en
(06) |   |   +-- description.php
(07) |   |   +-- parameters.php
(08) |   |   +-- component.php
(09) |   |   +-- templates
(10) |   |   |   +-- .default
(11) |   |   |   |   +-- template.php
(12) |   |   |   |   +-- readme.md
(13) |   |   |   +-- another-one
(14) |   |   +-- readme.md
(15) |   +-- ...
(16) +-- custom
(17)     +-- news.list
(18)     +-- ...
```

Наши компоненты находятся в неймспейсе webprofy.
Слегка модифицированные под проект компоненты битрикс размещаются в неймспейсе custom.

Есть 2 readme.md файла. Первый описывает работу компонента в целом и размещается в корне компонента.
Второй — в шаблоне компонента. Описывает параметры шаблона и особенности работы связки компонент+шаблон.

#### (14) local/modules

Здесь находятся модули, которые мы разрабатываем.

Все наши модули имеют вендора — webprofy.

Каждый модуль является отдельным репозиторием Git (submodule)

```
(00) /local/modules/
(01) +-- webprofy.regional
(02) +-- admin
(03) +-- classes
(04) +-- components
(05) |   +-- webprofy
(06) |       +-- regional.content
(07) |       +-- ...
(08) +-- default_option.php
(09) +-- include.php
(10) +-- install
(11) +-- js
(12) +-- lang
(13) +-- options.php
(14) +-- style.css
```

#### (15) local/php_interface
```
(00) /local/php_interface/
(01) +-- init.php
(02) +-- include
```
В init.php происходит автоподключение классов.
Всё остальное должно лежать в отдельных файлах в папке include и подключаться внутри init.php

#####  local/php_interface/include/settings.php

Файл с глобальными настрой. Содержит 2 массива
1. $arImageSizes - Массив с Размерами миниатюр изображений для обрезания и масштабирования изображений в зависимости от блока и шаблона. используется функциями resizeImgTag, resizeImgSrc, resizeImageGet и др
2. $arCatalogTopParamsDefault - Массив с Настройкой по умолчанию для компонентов "bitrix:catalog.top","webprofy:catalog.favorites.list", "bitrix:catalog.viewed.products" и других где отображается список товаров с ценами. Необходимо держать всегда в актуальном состоянии.


#### (16) local/cron

В этой папке находятся скрипты, запускаемые из под крона. В частности — запуск агентов по крону.

#### (18) local/templates/.default и (24) local/templates/customize-me

У готового сайта на оптиме — два шаблона сайта. Первый — шаблон оптимы по-умолчанию, размещается
 в папке .default. Для готового сайта — эта папка что-то вроде ядра оптимы — мы всегда можем накатить на неё обновление.

В этой папке прежде размещаются все шаблоны компонентов.

Второй шаблон — шаблон конкретного сайта. Располагается в папке customize_me, которая должна быть переименована по названию проекта. Именно он подключен на сайте и из него берётся шапка, футер и стили. В нём, по-умолчанию, не определены компоненты, поэтому битрикс ищет их в папке .default. Но есть возможность переопределить любой из шаблонов, что даёт возможность кастомизации с сохранением обновляемости (остальных шаблонов).

**Вся кастомизация шаблонов компонентов делается в папке /local/templates/название-проектов/**

**В папке /local/templates/.default/ никаких правок не делаем!**

#### (19) /local/templates/.default/components
```
(00) /local/templates/.default/
(01) +-- bitrix
(02)     +-- news.list
(03)     |   +-- .default
(04)     |   |   +-- template.php
(05)     |   |   +-- readme.md
(06)     |   +-- readme.md
(07)     +-- ...
```
Здесь располагаются шаблоны стандартных компонентов битрикс. Неймспейс bitrix. Мы не размещаем здесь шаблонов для наших собственных компонентов — они хранятся вместе с компонентом.

readme.md в папке с конкретным шаблоном — описание связки шаблон+компонент, описание параметров шаблона.
readme.md в корне (06) — описание работы компонента

#### (23) /local/templates/.default/_source/

Это отдельный репозиторий с вёрсткой оптимы (в дефолтном стиле).

```
(00) /local/templates/.default/_source/
(01) +-- blocks
(02) +-- copy
(03) +-- css
(04) +-- docs
(05) +-- fonts
(06) +-- gulp_tasks
(07) +-- img
(08) +-- js
(09) +-- pages
(09) |   +-- layout
(09) |   +-- index.jade
(10) +-- sass
(11) |   +-- _blocks.scss
(09) |   +-- _variables.scss
(12) |   +-- global.scss
(11) +-- gulpfile.js
(12) +-- readme.md
```
Описание, что где лежит и как работает — отдельном файле (12)

#### (24) local/templates/customize-me

На большой оптиме (eshop.optima.webprofy.ru) эта папка залинкована на .default (т. е. это одно и то же)

На конкретном проекте — здесь размещаются шапка и футер сайта, стили, картинки и скрипты. Здесь же идёт переопределение шаблонов компонентов, заданных в .default. Только тех, что требовали переопределения. Здесь можно переопределять шаблоны наших собственных компонентов.

readme.md в этих папках не делается.

```
(00) /local/templates/customize-me/
(01) +-- components
(02) |   +-- bitrix
(03) |   |   +-- news.list
(04) |   |       +-- .default
(05) |   |           +-- template.php
(06) |   +-- webprofy
(07) +-- _source
(08) +-- header.php
(09) +-- footer.php
(10) +-- css
(11) +-- js
(12) +-- template_styles.css
(13) +-- styles.css
```

В папке _source внутри шаблона конкретного сайта — исходники стилей конкретного сайта. Они могут являться форком репозитория с дефолтной оптимы, а могут размещаться в общем репозитории конкретного проекта.

Весь сайт стилизуется и кастомизируется здесь.

#### (25) local/vendor
Здесь размещаются зависимости композера, если нужны. Для чего нужен композер?
Composer — это отличный менеджер зависимостей для php. Это значит, что с его помощью вы можете управлять зависимостями вашего проекта буквально в "пару кликов".
Зависимости описываются в файле local/composer.json в секции require, указывается название пакета и версия.
По умолчанию, пакеты скачиваются из официального репозитория packagist.org. Так же есть возможность скачивать пакеты из других репозиториев
Для установки зависимостей потребуется ввести простую команду
```
composer install
```
находясь в папке local (через консоль/терминал).

Есть еще одна команда, которую стоит запомнить
```
composer update
```
 обновит все установленные пакеты (или установит заново случайно удаленные) до свежих версий. При этом, если создать специальный composer.lock файл — это позволяет зафиксировать комбинацию из стабильных версий всех используемых в проекте библиотек.

После установки пакетов автоматически генерируется autoload.php, с помощью которого можно подключить установленные библиотеки в коде проекта
```php
require_once $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';
```
[Официальный Сайт Composer](https://getcomposer.org/)

#### (26) upload


#### (27) include_areas

Здесь размещаются разнообразные включаемые области сайта, как размещённые в шаблоне, так и на конкретных страницах со сложной вёрсткой.

# Правила вёрстки
Вёрстка лежит в папке /local/templates/.default/_source/. Подключается отдельным субмодулем, репозиторий называется optima-2.1

Всё собирается с помощью gulp, используется sass, jade, WebProfy БЭМ. Ручное изменение стилей и скриптов запрещено. Проект регулярно пересобирается и все изменения в генерируемых файлах будут потеряны безвозвратно.

Подробно про процесс написано в [readme файле](https://bitbucket.org/webprofy/optima-2.1/src) в корне репозитория вёрстки.

# Источник данных
На проекте репозитория реальных данных нет, для проверки работоспособности используется демо-каталог битрикс.

# Особенности проекта
С этого репозитория обновляются все наши проекты, поэтому нужно быть предельно аккуратными, чтобы не сломать живые сайты клиентов. Это наш собственный битрикс.

## Действия для настройки свойств каталога
Настройка каталога обычно должна осуществляться в 3х местах
1. Настройка компонента каталога "bitrix.catalog" на странице /catalog/index.php
2. Настройка компонента "bitrix:catalog.top" на главной странице /index.php
3. Настройка массива $arCatalogTopParamsDefault local/php_interface/include/settings.php (свойства можно скопировать с настроек компонента на главной странице)

Ключевыми параметрами считаются свойства товаров и торговых предложений как отображаемых в карточке, так и попадающих в корзину, а также тип цены. В всех указанных местах они должны быть одинаковые в избежание трудноулавливаемых ошибок.

## Вывод заголовков и хлебных крошек
Для вывода хлебных крошек и заголовков используются специальные константы. 

- BREADCRUMBS, 
- CONDITIONAL_BREADCRUMBS, 
- H1, 
- CONDITIONAL_H1.

Константы, начинающиеся с "CONDITIONAL" показываются, исходя из значений свойств страницы/раздела "DONOTSHOWBREADCRUMBS" и "DONOTSHOWTITLE" соответственно.
Остальные показываются всегда, если они вставлены в тело страницы.

Для вывода заголовка или хлебных крошек в любом месте страницы (даже внутри закешированного компонента) нужно использовать код вида ``<?=H1?>``

## Псевдоразделы
Это модуль WebProfy, который позволяет добавлять товары в разделы автоматически по условию, а также перенаправлять из выбранных значений фильтра в разделы, соответствующие запросу. Подробной документации по нему пока нет, можно читать код модуля.

## Генерация ТЗ
В корне лежит файл generateDosc.php. Почти всё статика, но для базовых страниц (пункта 7) генерируется автоматически. Берутся все файлы readme.md из папки _optima, парсятся, вставляются в пункты меню.
Код простой, никакой сложной логики сейчас нет.

# FAQ

####Что такое оптима?
[Документ, который отвечает почти на все вопросы по оптиме](https://docs.google.com/document/d/1wdn6qCfxVY-XOydtkh2KFhz2g21PAP5Mj8fVF1tFdO8)

# TODO

- Где и как будут располагаться тесты?