エメラルドマウンテンの麓。

Nice Page Builderのマニュアル

onBeforeWrite から beforeBuild へ修正。構成を改めてマークアップと文言の修正をしました。目次を追加しました。(2021.5.11)

page.URL について追記。(version 0.0.12~, 2019.5.2)

加筆と修正を行いました。(2017.2.2)

目次

  1. はじめに
  2. インストール
    1. settings.json
  3. デバッグ
  4. 実行フロー
  5. HTML の拡張タグ
    1. ページのプロパティを記述
      1. ページのプロパティの優先順位
    2. onBeforeWritebeforeBuild スクリプト
  6. HTML の拡張表記
    1. {$$ インラインスクリプト $$}
    2. ($$ ルート相対パスの相対パスへの変換 $$)
  7. Page クラス
    1. Page インスタンスの読み取り専用プロパティ
    2. Page インスタンスのビルトインメソッド
    3. Page インスタンスのビルトインプロパティ

1. はじめに

テンプレートとなる HTML ファイル、コンテンツだけを記述した HTML ファイル、複数のページで共通したプロパティが記述してある json (.js 形式でも可)ファイル。データが記述された json ファイル。これらから Web サイトを生成する静的サイトジェネレータです。

HTML を生成する複雑なロジックを javascript で記述できます。この文書より先にチュートリアルを読んだ方が良いでしょう。僕が書いたにしては分かりやすく書けていると思います。

2. インストール

拡張機能のインストールは VS Code の GUI から簡単に行えます。拡張機能タブを開いて『Nice Page Builder』を検索してください。

2.1. settings.json

ワークスペースの設定にソースフォルダのルートや json の読み込み、アウトプットフォルダを指示します。アウトプットフォルダには RAM ディスクなどの異なるドライブを指定することもできます。

{
    "nicePageBuilder.tasks" : [{
            "htmlRoot" : { "rootPath" : "source", "include" : "", "exclude" : "" },
            "jsonList" : [
                { "path" : "jsons/comment.json", "name" : "comment" },
                { "path" : "jsons/tweet.json",   "name" : "tweet"   }
            ],
            "output"   : "R:/output"
    }]
}

3. デバッグ

エラー時には簡単なエラーメッセージが表示されます。

詳細なデバッグには開発者ツールを使用します。JavaScript デバッガが使えないようで console.log で頑張ります…

4. 実行フロー

  1. コンテンツだけの HTML、このページのプロパティで関連付けられたテンプレートファイルとミックスインファイルの読み込み
  2. settings.json の "jsonList" に記述された json ファイルの読み込み
  3. HTML に拡張タグ内に記述された onBeforeWritebeforeBuild スクリプトの実行
  4. 書き出し

5. HTML の拡張タグ

5.1. ページのプロパティを記述

<script type="nice-page-builder/object" for="page-option">
{
 TEMPLETE : '/Templetes/templete.html',
 MIXINS   : ['/Mixin/top.json'],
 title    : '俺のサイトにようこそ!'
}
</script>

TEMPLETE についてはミックスインファイル側に書いておくこともできます。テンプレートファイルのプロパティに TEMPLETE を持つことはできません。

5.1.1. ページのプロパティの優先順位

  1. ページの <script type="nice-page-builder/object" for="page-option"> 下にあるプロパティ
  2. MIXINS[0] のプロパティ
  3. MIXINS[n] のプロパティ
  4. TEMPLETE のプロパティ

5.2. onBeforeWritebeforeBuild スクリプト

ソースの HTML、 ミックスインファイル、テンプレート、JSON の読み取りが終わって、ファイルの書き出しがはじまる前に実行したい javascript を記述します。

名前説明
PageクラスPage.prototype.createSocialButton=function(){}などとページ用のメソッドを追加できます
pages全ての page を収めたハッシュkey:ルート相対パス, value:page で全てのページを保持しています
page または thisインスタンスonBeforeWritebeforeBuild スクリプトの書いてあった page が入っています
<script type="nice-page-builder/js" for="beforeBuild">
// 全ページから label を回収
var labels = {}, path, label;
for( path in pages ){
    if( pages[path].label ) labels[ label ] = true;
};
// ラベルリストを書きだすメソッドの追加
Page.prototype.ALL_LABELS = labels;
Page.prototype.createLabelList = function(){
    var html = [], label;
    for( label in this.ALL_LABELS ){
        html.push('<b>' + label + '</b>');
    };
    return html.join(',');
};
</script>

このタイミングで新しいページを追加することもできます。pages の集計結果や json を使って動的にページを追加します。

<script type="nice-page-builder/js" for="beforeBuild">
var comments = this.getJSON( 'bbs' ), comment, bbsPage, key, lastPage;

while( comment = comments.shift() ){
    bbsPage = new Page( '/bbs/' + comment.file_name );
    bbsPage.MIXINS  = ['/Templetes/bbs.js'];
    bbsPage.CONTENT = '<div>' +
        '<span itemprop="author">' + comment.author + '</span> ' +
        '<time datetime="' + (new Date(comment.created_at)).toISOString() + '" itemprop="commentTime">' + comment.created_at + '</time> ' +
    '</div>' +
    '<p itemprop="commentText">' + comment.comment + '</p>';
    for( key in comment ) bbsPage[ key ] = comment[ key ];
};
</script>

6. HTML の拡張表記

6.1. {$$ インラインスクリプト $$}

eval() の戻り値が文字列として埋め込まれます。thispage インスタンスです。

<main>{$$ this.CONTENT $$}</main>

6.2. ($$ ルート相対パスの相対パスへの変換 $$)

内容をパスとして評価しルート相対パスの場合、相対リンクに変換する。page.FOLDER_PATH を元に置き換えます。

またルート相対パスは、ソースフォルダをルートとするルート相対パスを記述する点に注意が必要です。

<link href="($$ /campany/about.html $$)">
↓
<link href="about.html">

Nice Page Builder では出力結果にルート相対パスを含むことはありません。これはジオシティーズのようにサブディレクトリをルートにしてホームページスペースが提供されている場合に都合が悪いためです。

geocities.jp/outcloud/

7. Page クラス

次に示す以外のプロパティはサイト制作者がプロジェクト毎に定義します。page のメソッドもサイト制作者によって <script type="nice-page-builder/js" for="beforeBuild"> スクリプト時に追加できます。

7.1. Page インスタンスの読み取り専用プロパティ

NicePageBuilder によって設定されるプロパティ。書き換えないでね。

キーワード説明
FILE_PATH"/game/rpg/about.html"stringソースのルートフォルダからのルート相対パス
FILE_NAME"about.html"string
FOLDER_PATH"/game/rpg"stringソースのルートフォルダからのルート相対パス、ルート直下の場合 ""(空文字列)
URL"/game/puzzle/", "/game/rpg/about.html"stringFILE_PATH から "index.html" を除いた文字列
CREATED_AT1234567890numberファイルが作られた日付
MODIFIED_AT1234567890numberファイル自身が修正された日付
UPDATED_AT1234567890numberファイル自身と TEMPLETEMIXINS の更新日のうち最新のもの
CONTENT"<p>俺のホームページにようこそ!俺です…"string

.html ファイルの内容。

但しページのプロパティ(<script type="nice-page-builder/object" for="page-option">)と <script type="nice-page-builder/js" for="beforeBuild"> は除去してある。

同一ドメインの他ファイルへのパスを書くときはソースのルートフォルダからのルート相対パスとします。つまり / で始まります。

7.2. Page インスタンスのビルトインメソッド

メソッド引数戻り値説明
toRelativePathstring ルート相対パスstring 相対パスthis.FILE_PATH を元に相対パスに変換します
getPagestring ルート相対パスpage
getJSONstring 名前objectsettings.json に書いた名前を使って json を取得します

7.3. Page インスタンスのビルトインプロパティ

ビルトイン機能のためのプロパティです。ページのプロパティ(<script type="nice-page-builder/object" for="page-option"> かテンプレートファイルかミックスインファイル)に記述しておくと javascript からは次のプロパティからアクセスできます。

キーワード説明
TEMPLETE"/Templete/templete.html"stringテンプレートファイルへの参照。
MIXINS["/Mixin/category-game.json", "/Mixin/pageType-item.json"]array.<string>ミックスイン用 json ファイルへの参照。