Merge pull request #48 from pafnuty/dev

Dev

storage/pages/documentation/composite.md

@@ -0,0 +1,138 @@
+---
+title: Композитный сайт
+description: Документация к Bitrix Quick Start, Проблемы композита
+template: index
+
+---
+
+# Композитный сайт 
+
+<div class="tip">
+    :construction: Страница не закончена. <a href="https://github.com/pafnuty/bqs-site/blob/dev/storage/pages/documentation/composite.md" class="btn btn-small" target="_blank">Редактировать</a>
+</div>
+
+[Композитный сайт](https://www.1c-bitrix.ru/composite/) — очень полезная технология, если её использовать с умом. И как в любой новинке, в композите хватает недоработок и проблем. 
+
+В этом разделе собраны основные проблемы композита, причины и пути их решения.
+
+---
+## [Композит не сработает в следующих случаях](#composite_not_work){#composite_not_work .h3}
+---
+
+- Не включена настройка в админке, либо страница попадает под условия исключения, либо не входит в условия включения, либо страница не прошла проверку по параметрам (например компонент проголосовал против).
+- В технологии работают только GET запросы. С другими запросами технология не работает.
+- Адрес страницы начинается с `/bitrix`.
+- Есть служебная cookie **_NCC** (No Composite Cache), которая позволяет определять входит ли пользователь в группу, для которой разрешено отображение страниц по технологии или не входит.
+- В `$_GET` есть параметр `ncc=1`. Если нужны собственные исключающие параметры по которым не будет работать композит, то используйте `~EXCLUDE_PARAMS` в `/home/bitrix/www/bitrix/html_pages/.config.php`.
+- Если в запросе есть сохранённая авторизация, то будет выдана страница по обычной технологии. Если авторизация сохранена, а пользователь принадлежит к группе, которая должна видеть страницу из композитного кеша, то он увидит её при повторном хите.
+- В `REQUEST_URI` есть `..`, `.php`, `.html` в середине адреса. (Это требование по безопасности.)
+- Если ajax-запрос сделан с помощью `BX.ajax`.
+
+---
+## [Основные проблемы композита](#probems){#probems .h3}
+---
+
+Тут собраны самые частые и типовые проблемы и ошибки.
+
+
+### [Моргание контента](#blink_content){#blink_content .text-secondary .col-margin}
+
+При динамической загрузке больших блоков (баннер, список элементов каталога) возникает неприятный для глаза эффект, моргания или прыгания контента страницы, особенно если этот контент находится на первом экране. Для устранения этого эффекта можно использовать метод `$frame->setAnimation(true)`, он "включает" анимацию появления контента, подгружаемого через ajax. Просто и не раздражает глаз.
+```php
+<div id="my_div">
+    <?
+        $frame = $this->createFrame('my_div', false)->begin();
+
+        // Включаем плавную анимацию
+        $frame->setAnimation(true); 
+    ?>
+        Динамический контент.
+    <? 
+        $frame->end(); 
+    ?>
+</div>
+```
+
+
+### [JS и Композитный сайт](#js_composite){#js_composite .text-secondary .col-margin}
+
+Очень важно понимать, что при композитном хите контент динамических областей **физически не существует на странице**, поэтому любые js-обработчики, завязанные на DOM-дерево внутри динамической области не сработают или сработают не так, как ожидается. К таким обработчикам можно отнести различные карусельки, стилизацию селектов и т.п.
+
+При этом писать js в шаблон компонента — не самая лучшая идея и этого необходимо избегать всеми возможными способами (без фанатизма конечно же).
+
+Решение проблемы очень простое — **достаточно "дождаться", когда ajax-контент динамических областей подгрузится**.
+```js
+if (window.frameCacheVars !== undefined) {
+    BX.addCustomEvent("onFrameDataReceived", function (json) {
+        // Все динамические области загружены при композитном хите.
+        runFunction();
+    });
+} else {
+    jQuery(document).ready(function ($) {
+        // Тут произошел обычный, не композитный хит.
+        runFunction();
+    });
+}
+
+function runFunction() {
+    // Код, написанный тут, выполнится корректно и при обычном и при композитном хитах.
+    console.log('go-go-go');
+}
+```
+
+Не стоит навешивать обработчики пользовательских событий (click, focus, hover, input и т.п.) внутри функции `runFunction` из примера выше т.к. это пустая трата времени и некорректное написание js т.к. пользователь всёравно не сможет кликнуть по несуществующей кнопке :smile:. 
+
+Для пользовательских событий используйте нормальный код, который можно записать в самое начало js-файла:
+```js
+$(document).on('click', '.selector', function(event) {
+    /* Обрабатываем клик по элементу .selector */
+});
+```
+Такой код не зависит от композитного режима сайта и обработчик сработает тогда, когда это необходимо.
+
+
+---
+## [Необычные или редкие проблемы композита](#additional_probems){#additional_probems .h3}
+---
+Тут собраны редкие или необычные и нелогичные проблемы композита<div class=""></div>
+
+### [Куки + композит](#cookie_composite){#cookie_composite .text-secondary .col-margin}
+
+**Когда возникает:**
+- При установке шаблона сайта на основании значения куки пользователя.
+
+**Причины возникновения:**
+- При выполнении страницы композит учитывает только URL и служебные куки **_NCC**, остальные куки ему до лампочки.
+
+**Пути решения:**
+- "Отключить" композит для страниц, отображение которых зависит от cookies посетителя.
+- Если возможно - посылать посетителя по другому адресу (например побильная версия сайта), при этом делать это лучше средствами nginx или apache.
+
+### [Контент сайта попадает внутрь заголовка H1](#content_in_h1){#content_in_h1 .text-secondary .col-margin}
+
+**Когда возникает:**
+- Фильтр каталога вынесен в другое место страницы через [ShowViewContent](https://dev.1c-bitrix.ru/api_help/main/reference/cmain/showviewcontent.php).
+- Попытка завернуть баннеры в динамическую область.
+
+**Причины возникновения:**
+- Некорректный расчёт динамических областей из-за отсутствия конкретных ID этих областей.
+- Динамическая область вложена в другую динамическую область.
+
+**Пути решения:**
+- Указывать конкретные ID динамических областей
+
+```php
+echo '<div id="my_div">';
+$frame = $this->createFrame('my_div', false)->begin();
+   //динамический контент
+$frame->beginStub();
+   //заглушка
+$frame->end();
+echo '</div>';
+```
+- Не включать одну динамическую область в другую.
+
+---
+
+Для подготовки раздела использовалась [документация из курса](http://dev.1c-bitrix.ru/learning/course/?COURSE_ID=39&LESSON_ID=3253&LESSON_PATH=3910.2663.3253), статья [Композитный сайт: tips & tricks](https://dev.1c-bitrix.ru/community/blogs/cookbook/composite-website-tips-tricks.php) и собственные решения проблем, с которыми приходится сталкиваться в процессе работы.
+

themes/bitrix/assets/less/20-base.less

@@ -159,6 +159,11 @@ body {
 				border-bottom-color: inherit;
 			}
 		}
+		&.text-secondary {
+			a {
+				color: @secondary;
+			}
+		}
 	}
 	h4, .h4 {
 		font: normal @baseFontSize/1.4 @sans;

themes/bitrix/landing.tpl

@@ -12,6 +12,7 @@
 		<link rel="shortcut icon" href="/favicon.ico?v=1">
 
 		<title>{$title}</title>
+		<link href="https://fonts.googleapis.com/css?family=Open+Sans:300&amp;text=Bitrix+Quick+Start" rel="stylesheet">
 		<style>
 			html, body {
 				height: 100%;

themes/bitrix/sidebar.tpl

@@ -21,7 +21,9 @@
 					<li {if $slugChild == 'less'} class="active" {/if}>
 						<a href="{$home}/documentation/less">LESS</a>
 					</li>
-
+					<li {if $slugChild == 'composite'} class="active" {/if}>
+						<a href="{$home}/documentation/composite">Композит</a>
+					</li>
 				</ul>
 			</li>