Pug - にほんご。

API Reference

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

tips

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

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

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


オプション

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

filename: string
コンパイル時のファイル名。 例外発生時や、includeextendで使用します。 デフォルトは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 "of pug"; }'

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 

次に、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.filtersoptions.filtersを両方指定している場合、options.filtersが優先されます。

廃止予定

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


© 2017 pugjs.org Released under the MIT license

このコンテンツはpugドキュメントを翻訳/改変したものです。