jDango v.0.4

jDango — это компактный javascript framework, предназначенный для быстрого прототипирования. Движок разрабатывается Николаем Яремко (makiwara@humanemagica.com) и распространяется по свободной лицензии.

О проекте в целом

Целью проекта является создание компактного и лёгкого в освоении и использовании движка сборки сложных страниц с использованием концепций «блоков» (из БЭМ) и «наследования» (из Django). Дополнительным условием является пригодность движка для использования как на клиенте (в браузере), так и на сервере (посредством NodeJS).

Синтаксис разметки заимствован из Django.

Состояние дел (0.4)

• Движок компилирует шаблоны в javascript-код и затем исполняет их при рендеринге.
• Движок поддерживает базовые конструкции Django: вложенные шаблоны, наследование шаблонов, вставка данных.
• Движок поддерживает встраивание в шаблоны кода javascript, исполняемого в момент рендеринга шаблона.
• Движок поддерживает блоки, хранящиеся в БЭМ-стиле, в том числе подключение CSS этих блоков в момент компиляции (не рендеринга, отсюда следующий пункт)
• Движок может быть использован только на клиенте (из-за грубой реализации подключения CSS, что исправимо). Возможна доработка движка до степени, когда он полностью исполняется на сервере или же производит на сервере компиляцию шаблонов, чтобы затем на клиенте осуществлять рендеринг.

Краткая документация по методам (0.4)

• $.tpl.init({ cache, url, libs, lego, precompile }, callback) Инициализация движка
  • cache — стартовое состояние кеша, ключ-значение, которое является функцией вида function(tpl, ctx) { return html }
  • url — локальный урл для загрузки шаблонов, лучше абсолютный
  • blocks — путь для доступа к каталогу блоков, лучше абсолютный
  • libs — локальный урл для загрузки JS-библиотек, лучше абсолютный
  • precompile — список шаблонов, которые будут прекомпилированы перед вызовом callback
• $.tpl.put(template, ctx, queryTarget) Форматирование шаблона и вставка его в DOM
  • template — название шаблона
  • ctx — хеш-массив для подстановок данных
  • queryTarget — строка для jQuery, в $(target).html(...) будет вставлен результат
• $.tpl.render(template, ctx, callback) Аналогично put, только вместо вставки вызывает callback
  • callback = function(result) {...}

Синтаксис шаблонов (0.4)

• {{key}} — вставляет ctx['key']
• {{*}} — вставляет название текущего шаблона, самого верхнего в цепи наследования (экстремально полезно для лего-блоков)
• {% extends "parentTemplateName" %} - наследование шаблона из другого, как в Django
• {% block blockName %}...{% endblock %} - блоки для наследования, как в Django
• {% include "templateName" %} - вложенные шаблоны
  • могут быть в каталоге blocks/b-XXXXX/b-XXXX.html, тогда достаточно {% include "b-XXXX" %} при этом всегда пытаемся загрузить CSS-файл с тем же именем.
• {% template subtemplateName %}...{% endtemplate %} - много шаблонов в одном файле
  • используются по адресу templateName/subtemplateName, например: {% include "library.html/help" %} NB: нельзя вкладывать друг в друга
• {% for (var i=0; i<2; i++) { %}...{% } %} - управляющие структуры на яваскрипте NB: не забудьте фигурные скобки! Доступ к хеш-массиву подстановок: ctx[...] Доступ к шаблонизатору: tpl.render(...) Структура выполнения не поддерживает замыканий Переменные из управляющих структур недоступны в шаблонах, для их вывода нужно написать так {% _+=i; %}
• {% load "libraryName" %} - загрузка js-библиотек В настоящее время эти библиотеки становятся доступными для всех шаблонов.
  • можно подгружать из блоков {% load "b-XXXX" %} и {% load "b-XXXX/scriptName.js" %} Хочется в дальнейшем:
  • научиться привязывать их загрузку или выполнение к рендерингу определённого шаблона. Главным образом речь идёт о привязке выполнения, а не загрузки.
  • дать простой инструмент создания фильтров и тегов, как в Django

Ограничения (0.4)

• Управляющие структуры {% for XXX in YYY %} и {% include "templatename.html" param=YYY %} не поддерживают весь спектр подстановок, которые умеет делать {{var}}. Поэтому в качестве значений должны быть или прямые значения (цифры либо строки), либо сведённый в простую последовательность путь внутри контекста: style.color.0.text.

Расположение шаблонов

• прямо в теле страницы <script type="text/html" id="templateName" parent="parentTemplateName">...<;/script>
• в отдельных файлах (будут загружены асинхронно в момент компиляции), в этом случае имя шаблона = имя файла