API Справочник

На этой странице подробно описано, как отобразить Pug с помощью JavaScript API.

Параметры

Все методы API принимают следующий набор параметров:

filename: строка

Имя файла, который компилируется. Используется в исключениях и требуется для относительных include\s и extend\s. По умолчанию 'Pug'.

basedir: строка

Корневая директория всех абсолютных включений.

doctype: строка

Если doctype не указан в шаблоне, вы можете указать его здесь. Иногда это полезно для получения самозакрывающихся тегов и удаления дублирования логических атрибутов. Для получения дополнительной информации см. документацию по доctype.

pretty: логическое значение или строка

[Устарело.] Добавляет пробелы в результирующий HTML для лучшей читабельности, используя '  ' в качестве отступа. Если указана строка, она будет использоваться в качестве отступа (например, '\t'). Мы настоятельно рекомендуем не использовать этот параметр. Он часто создает скрытые ошибки в ваших шаблонах из-за того, как он изменяет интерпретацию и отображение пробелов, поэтому эта функция будет удалена. По умолчанию false.

filters: объект

Таблица хешей пользовательских фильтров. По умолчанию undefined.

self: логическое значение

Использовать пространство имен self для хранения локальных переменных. Это ускорит компиляцию, но вместо написания variable вам придётся написать self.variable для доступа к свойству объекта locals. По умолчанию false.

debug: логическое значение

Если установлено в true, то токены и тело функции будут выведены в stdout.

compileDebug: логическое значение

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

globals: Массив строк

Добавление списка глобальных имён, которые будут доступны в шаблонах.

cache: логическое значение

Если установлено в true, скомпилированные функции кешируются. filename должно быть установлено в качестве ключа кеша. Применимо только к функциям render. По умолчанию false.

inlineRuntimeFunctions: логическое значение

Встраивание функций выполнения вместо require-ния их из общей версии. Для функций compileClient, значение по умолчанию true (чтобы не нужно было включать выполнение). Для всех остальных типов компиляции или рендеринга значение по умолчанию false.

name: строка

Имя функции шаблона. Применимо только к функциям compileClient. По умолчанию 'template'.

Методы

pug.compile(source, ?options)

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

source: строка

Исходный Pug шаблон для компиляции

options: ?options

Объект параметров

returns: функция

Функция для генерации HTML из объекта, содержащего локальные переменные

var pug = require('pug');

// Compile a function
var fn = pug.compile('string of pug', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileFile(path, ?options)

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

path: строка

Путь к файлу Pug

options: ?options

Объект параметров

returns: функция

Функция для генерации HTML из объекта, содержащего локальные переменные

var pug = require('pug');

// Compile a function
var fn = pug.compileFile('path to pug file', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileClient(source, ?options)

Компиляция Pug шаблона в строку JavaScript, которая может использоваться на стороне клиента.

source: строка

Pug шаблон для компиляции

options: ?options

Объект параметров

returns: строка

Строка JavaScript, представляющая функцию

var pug = require('pug');

// Compile a function
var fn = pug.compileClient('string of pug', options);

// Render the function
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }'

pug.compileClientWithDependenciesTracked(source, ?options)

То же, что и compileClient, за исключением того, что этот метод возвращает объект следующего вида:

{
  'body': 'function (locals) {...}',
  'dependencies': ['filename.pug']
}

Используйте этот метод только если вам необходимо dependencies реализовать что-то вроде отслеживания изменений в файлах Pug.

pug.compileFileClient(path, ?options)

Компиляция файла Pug в строку JavaScript, которая может использоваться на стороне клиента.

path: строка

Путь к файлу Pug

options: ?options

Объект параметров

options.name: строка

Если вы передадите свойство .name в объекте параметров, оно будет использоваться в качестве имени вашей функции шаблона на стороне клиента.

returns: строка

Тело JavaScript функции.

Сначала наш файл шаблона.

h1 This is a Pug template
h2 By #{author}

Затем мы компилируем Pug файл в строку функции.

var fs = require('fs');
var pug = require('pug');

// Compile the template to a function string
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// Maybe you want to compile all of your templates to a templates.js file and serve it to the client
fs.writeFileSync("templates.js", jsFunctionString);

Вот как выглядит выходная строка функции (сохраняется в templates.js).

function fancyTemplateFun(locals) {
  var buf = [];
  var pug_mixins = {};
  var pug_interp;

  var locals_for_with = (locals || {});

  (function (author) {
    buf.push("<h1>This is a Pug template</h1><h2>By "
      + (pug.escape((pug_interp = author) == null ? '' : pug_interp))
      + "</h2>");
  }.call(this, "author" in locals_for_with ?
    locals_for_with.author : typeof author !== "undefined" ?
      author : undefined)
  );

  return buf.join("");
}

<!DOCTYPE html>
<html>
  <head>
    <script src="/templates.js"></script>
  </head>

  <body>
    <h1>This is one fancy template.</h1>

    <script type="text/javascript">
      var html = window.fancyTemplateFun({author: "enlore"});
      var div = document.createElement("div");
      div.innerHTML = html;
      document.body.appendChild(div);
    </script>
  </body>
</html>

pug.render(source, ?options, ?callback)

source: строка

Исходный Pug шаблон для рендеринга

options: ?options

Объект параметров, также используемый как объект локальных переменных

callback: ?функция

Обратный вызов в стиле Node.js, принимающий результаты рендеринга. Этот обратный вызов вызывается синхронно.

returns: строка

Результирующая строка HTML

var pug = require('pug');

var html = pug.render('string of pug', options);
// => '<string>of pug</string>'

pug.renderFile(path, ?options, ?callback)

path: строка

Путь к файлу Pug для рендеринга

options: ?options

Объект параметров, также используемый как объект локальных переменных

callback: ?функция

Обратный вызов в стиле Node.js, принимающий результаты рендеринга. Этот обратный вызов вызывается синхронно.

returns: строка

Результирующая строка HTML

var pug = require('pug');

var html = pug.renderFile('path/to/file.pug', options);
// ...

Свойства

pug.filters

Таблица хешей пользовательских фильтров.

Этот объект имеет те же семантику, что и filters параметр, но применяется глобально ко всей компиляции Pug. Когда фильтр присутствует как в pug.filters, так и в options.filters, параметр filters имеет приоритет.