API Reference

このページではJavaScript APIを使ってPugをレンダリングする方法を 詳しく解説していきます。

tips

PugはWebブラウザのコンソールから使えます！
試しにPugのAPIを動かしてみるなら、このページに書かれていることをやってみてください。

pug.render('p Hello world!');

* F12でコンソールを立ち上げて以下を入力すると "<p>Hello world!</p>"と表示されます。

オプション

全てのAPIメソッドは以下のオプションを受け取ります

filename: string

コンパイル時のファイル名。 例外発生時や、include、extendで使用します。 デフォルトはPugです。

basedir: string

絶対パスのルートディレクトリ。

doctype: string

テンプレートにdoctypeが指定されていない場合、ここで指定します。 自己終了タグを付与したり、boolean属性による影響を無くすのに便利です。 詳しくはdoctypeを参照してください。

pretty: boolean | string

[廃止予定]
HTMLにインデントとして' '(スペース2つ)を追加し、人が読みやすいファイルとして出力します。 stringが指定されている場合、その文字をインデントに使用します。(例:'\t')
スペースの解釈とレンダリングが変更されるため、頻繁にバグを生みます。 そのため、この機能を廃止する予定です。デフォルトはfalseです。

filters: object

カスタムフィルタのハッシュテーブルですです。 デフォルトはundefinedです。

self: boolean

名前空間selfを使うことで、localsを保持します。 コンパイルを高速化しますが、localsのプロパティにアクセスために、 variableではなくself.variableと記述する必要があります。 デフォルトはfalseです。

debug: boolean

trueにすると、トークンと関数がstdoutに記録されます。

compileDebug: boolean

trueにすると、コンパイル時のエラーメッセージを表示するために、 関数のソースがテンプレート内に含まれます。 (開発中に便利です。) 本番モードでExpressと共に使われない限り デフォルトは有効になっています。

globals: Array

テンプレートからアクセスするためのグローバル名をリストに追加します。

cache: boolean

trueにすると、コンパイル時の関数をキャッシュします。 filenameはキャッシュのキーとしてセットしなければなりません。 render機能のみに適用されます。 デフォルトはfalseです。

inlineRuntimeFunctions: boolean

requireする、しないにかかわらず、インラインでpug-runtimeを含めるかどうかを指定します。 compileClient関数では、デフォルトはtrueです。 (pug-runtimeを含める必要はありません。) compileまたはrenderの場合、デフォルトはfalseです。

name: string

テンプレート関数名。compileClient関数の場合のみ有効です。 デフォルトは'template'です。

関数

pug.compile(source, ?options)

Pugテンプレートを関数に変換し、 別のlocalsからも何度でもレンダリングすることができます。

source: string

コンパイルするPugテンプレート文字列

options: ?options

オプション

returns: function

localsを含むオブジェクトからHTMLを生成する関数

var pug = require('pug');
 
// 関数をコンパイル
var fn = pug.compile('string of pug', options);
 
// 関数をレンダリング
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileFile(path, ?options)

Pugテンプレートが記述されたファイルを関数に変換し、 別のlocalsからも何度でもレンダリング出来るようにします。

path: string

Pugファイルのパス

options: ?options

オプション

returns: function

localsを含むオブジェクトからHTMLを生成する関数

var pug = require('pug');
 
// 関数をコンパイル
var fn = pug.compileFile('path to pug file', options);
 
// 関数をレンダリング
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileClient(source, ?options)

PugテンプレートをJavaScriptの文字列に変換し、 pug-runtimeライブラリと共に、ブラウザでPugを使えるようにします。

source: string

コンパイルするPugテンプレート文字列

options: ?options

オプション

returns: string

JavaScript関数の文字列

var pug = require('pug');

// 関数をコンパイル
var fn = pug.compileClient('string of pug', options);

// 関数をレンダリング
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }'

pug.compileClientWithDependenciesTracked(source, ?options)

compileClientと同じです。 しかし、このメソッドは以下のオブジェクトを返します。

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

Pugファイルの変更を監視するようなものを実装し、 ファイルのdependencies(依存関係)が必要な場合のみ利用してください。

pug.compileFileClient(path, ?options)

Pugテンプレートが記述されたファイルをJavaScriptの文字列に変換し、 pug-runtimeと共に、ブラウザでPugを使えるようにします。

path: string

Pugファイルのパス

options: ?options

オプション

options.name: string

オプションに.nameを指定すると、ブラウザで使う場合の関数名として利用されます。

returns: string

JavaScript本体

まずテンプレートファイルを用意します。

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

次に、PugファイルにJavaScriptの関数文字列を追加します。

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

// テンプレートを関数文字列にコンパイル
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// ブラウザで使えるように、全てのテンプレートにtemplate.jsを追加したいかもしれません。
fs.writeFileSync("templates.js", jsFunctionString);

出力される関数文字列は以下のようになります。(template.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("");
}

pug-runtime(node_modules/pug/runtime.js)をテンプレートに追加し コンパイルした関数を実行できるようにします。

<!DOCTYPE html>
<html>
  <head>
    <script src="/runtime.js"></script>
    <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: string

レンダリングするPugテンプレート

options: ?options

オプション。localsとしても利用されます。

callback: ?function

レンダリング結果をNode.js形式で受け取るコールバック。このコールバックは同期的に呼び出されます。

returns: string

結果のHTML文字列。

var pug = require('pug');

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

Properties

pug.filters

カスタムフィルタのハッシュテーブル。

このオブジェクトはoptions.filtersと同じセマンティクスを持ちます。しかし、Pugのコンパイル時にグローバルに適用されます。 pug.filtersとoptions.filtersを両方指定している場合、options.filtersが優先されます。

廃止予定

このプロパティはoptions.filtersを優先するため、廃止予定です。