Merge 52156ba into ff5efbe

common.blocks/loader/loader.ru.md

@@ -0,0 +1,120 @@
+# loader
+
+Блок `loader` служит для загрузки и подключения фрагментов кода по URL.
+
+Блок реализован в технологии `js` и подходит для использования клиентских приложениях.
+
+
+## Модификаторы блока
+
+### `type`
+
+В зависимости от значения модификатора `type`, блок `loader` позволяет получить по URL и подключить:
+
+* `js` - фрагмент JavaScript кода;
+* `bundle` – пакет, собранный из CSS и JS-файлов – "бандл".  
+
+#### `type_js`
+
+Блок с модификатором `loader_type_js` реализует функцию, принимающую два аргумента:
+
+* `{String}` `url` – URL загружаемого фрагмента JS-кода;
+* `{Function}` `cb` – функция обратного вызова, которая будет выполнена по завершению загрузки фрагмента кода.
+
+Например:
+
+```js
+modules.define('test-js-load', ['loader_type_js'], function(provide, jsLoader) {
+
+    provide(function() {
+        jsLoader('http://mysite.org/test.js', function() { console.log("Wow, it's loaded") })
+    });
+});
+```
+
+При инициализации блока с модификатором `loader_type_js`:
+
+* создается очередь для функций обратного вызова, ожидающих выполнения после загрузки. Для каждого значения `url` в очереди создается отдельный массив колбеков;
+* формируется объект для списка уже подключенных `url`.
+
+При вызове функции производится поиск строки – первого аргумента:
+
+* среди имен подключенных `url`. В случае успеха, колбек (аргумент  `cb`) немедленно вызывается, а управление возвращается вызывавшей функции;
+* среди имен `url`, ожидающих подключения. В случае успеха, колбек помещается в очередь и управление возвращается вызывавшей функции.
+
+Если текущее значение `url` не найдено, создается запись в очереди на подключение. Колбек –  аргумент `cb` помещается в очередь. 
+
+Затем создается DOM-элемент `script` со всеми нужными свойствами, который добавляется к элементу `head` документа.
+
+По завершению загрузки:
+
+* выполняются все колбеки из очереди на подключение;
+* `url` удаляется из очереди и добавляется к списку подключенных. 
+
+
+#### `type_bundle`
+
+Блок с модификатором `loader_type_bundle` реализует функцию от четырех аргументов:
+
+* `{String}` `id` – идентификатор бандла;
+* `{String}` `url` – путь до файла бандла в формате URL;
+* `{Function}` `onSuccess` – колбек, вызываемый по завершению загрузки бандла;
+* `{Function}` `onError` – колбек, вызываемый при неудачной загрузке бандла.
+
+Например:
+
+```js
+modules.define('test-bundle-load', ['loader_type_bundle'], function(provide, bundleLoader) {
+
+    provide(function() {
+        var onSuccess = function() { console.log("Wow, it's loaded") },
+            onError = function() { throw new Error('ups') };
+        bundleLoader(
+            'test1',
+            'http://mysite.org/test.bundle.js', 
+            onSuccess,
+            onError
+        )
+    });
+});
+```
+
+При инициализации блока с модификатором `loader_type_js` создается объект бандлов, содержащий в ключах `id`, а в значениях массивы функций обратного вызова, которые нужно выполнить:
+
+*  после успешной загрузки бандла;
+*  в случае ошибки загрузки.
+
+При вызове функция, реализованная блоком, проверяет значение аргумента `id`. Если соответствующее ему свойство найдено в объекте бандлов, проверяется загружен ли бандл:
+
+* если да, колбек `onSuccess` немедленно вызывается с помощью `setTimeout` с задержкой 0;
+* если нет, оба колбека из аргументов (`onSuccess` и `onError`) добавляются к соответствующим массивам объекта бандлов.
+
+В обоих случаях управление возвращается вызывавшей функции.
+
+Если свойство, соответствующее `id` в объекте бандлов не найдено, такое свойство создается. В его значениях сохраняются массивы, содержащие колбеки `onSuccess` и `onError`.
+
+Затем функция создает DOM-элемент `script` со всеми нужными свойствами, который добавляется перед первым дочерним элементом элемента `head`.
+
+Кроме того функция устанавливает таймер загрузки на интервал, равный значению константы `LOADING_TIMEOUT` (по умолчанию 8000 миллисекунд). Таймер устанавливается с помощью `setTimeout`. Метод `setTimeout` возвращает ссылку на объект счетчика, которая сохраняется во вложенном свойстве `timer` объекта бандлов для текущего `id` . 
+
+По истечению указанного интервала вызывается функция – обработчик ошибок. Обработчик:
+
+* очищает таймер загрузки;
+* вызывает все колбеки `onError` из соответствующего массива объекта бандла;
+* удаляет свойство, соответствующее `id` из объекта бандла.
+
+
+##### Статические методы, доступные с модификатором `loader_type_bundle`
+
+Функция, реализованная блоком с модификатором `loader_type_bundle`, обладает одним статическим методом – `_loaded`. Он используется как вспомогательный после успешной загрузки бандла.
+
+На вход метод `_loaded` принимает объект со свойством `id`, содержащим строку с `id` загруженного бандла (URL). 
+
+В ходе выполнения метод:
+
+* очищает таймер загрузки;
+* вызывает загруженный `bundle.js` в глобальном пространстве имен;
+* подключает бандл CSS, в ходе чего:
+    * создается DOM-элемент `style` с нужными свойствами;
+    * DOM-элемент помещается перед первым вложенным элементом в `head`;
+* выполняет все колбеки `onSuccess` из соответствующего массива, после чего удаляет массив.