スタイルガイドジェネレータの「Fractal」を使ってみる

2019.03.18

スタイルガイドジェネレータの「Fractal」を使う機会があったので、使用までの流れと使い方をメモ。

インストール

まずはFractalを使用するディレクトリへ移動します。

cd 【プロジェクトディレクトリ】

以下のコマンドでpackage.jsonを生成します。

npm init

Fractalをプロジェクトディレクトリにインストールします。

npm install --save @frctl/fractal

今回はFractal単体で使用するため、グローバルにも同様にインストールします。

npm i -g @frctl/fractal

これでインストールは一通り完了しました。
　

設定

プロジェクトディレクトリ内に、以下の構造でフォルダを作成します。

  • src
    • components
    • docs
  • package.json

プロジェクトディレクトリ直下に、fractalfile.jsというファイル名でファイルを作成します。
今回は以下のような内容で記述します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');

公式のドキュメントだとfractal.jsというファイル名で生成するようになっていますが、Windows環境だとfractal.jsというファイル名でうまくいかないようなので、fractalfile.jsとしています。

package.jsonに以下を追記します。

"fractal": {
	"main": "fractalfile.js"
}

サンプルでコンポーネントを追加してみます。
先ほど作成したcomponentsディレクトリ内にalert.hbsというファイル名で以下のように記述します。

<!-- src/components/alert.hbs -->
<div class="alert">This is an alert!</div>

スタイルガイドのトップページの内容を追加します。
docsのディレクトリ内にindex.mdというファイルを作成して、以下のように記述します。

---
title: cly7796 Fractal sample
---
Fractal sample page.

これで一通り準備完了なので、実際に使ってみます。
以下のコマンドを実行します。

fractal start --sync

「Fractal web UI server is running!」と表示されていればOKです。
記載されているURLにアクセスすると、以下のように表示されました。

左ナビのAlertをクリックすると以下のように表示されます。

ここまでのディレクトリ構造は以下のようになっています。

  • src
    • components
      • alert.hbs
    • docs
      • index.md
  • fractalfile.js
  • package.json

　

CSSの適用

今のままだとコンポーネントのプレビューにスタイルが当たっていない状態なので、CSSを適用してみます。
このプレビュー部分はiframeで読み込む形になっているので、このiframe内のテンプレートを用意します。

プロジェクトディレクトリ直下にpublicというフォルダを作成、さらにその中でcssというフォルダを作成して、style.cssというファイル名で以下のCSSファイルを設置します。

.alert {
	color: red;
	font-weight: bold;
}

fractalfile.jsの内容を以下に変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');

12～13行目に静的ファイルの読み込みファイルを追加していて、これでpublicディレクトリ内をルートとして扱えるようになりました。

componentsディレクトリ内に_preview.hbsというファイル名で以下のように記述します。

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link media="all" rel="stylesheet" href="{{ path '/css/style.css' }}">
<title>Preview Layout</title>
</head>
<body>
{{{ yield }}}
</body>
</html>

CSSのパスは{{ path ‘/css/style.css’ }}で指定していて、{{{ yield }}}の部分にコンポーネントが追加されます。
これでコンポーネントのプレビューにスタイルを当てることができました。

ここまでのディレクトリ構造は以下のようになっています。

  • public
    • css
      • style.css
  • src
    • components
      • _preview.hbs
      • alert.hbs
    • docs
      • index.md
  • fractalfile.js
  • package.json

　

コンポーネントの設定

設定ファイルの追加

設定ファイルは同じディレクトリに同じコンポーネント名で作成する必要があり、ファイル形式はjson,js,ymlのいずれかで作成できます。
例えば先ほどのalert.hbsの設定ファイルをjson形式で作成する場合、componentsディレクトリ内に「alert.config.json」という名前でファイルを作成します。
ファイルの内容を以下のようにしてみます。

{
	"title": "アラート"
}

コンポーネントページのタイトルを変更することができました。

設定ファイルでデータを管理することもできます。
例えば、alert.hbsのテキスト部分を以下のように変更してみます。

<!-- src/components/alert.hbs -->
<div class="alert">{{text}}</div>

先ほど作成したalert.config.jsonに以下のように追加します。

{
	"title": "アラート",
	"context": {
		"text": "alert.config.jsonから設定"
	}
}

これで設定ファイルからデータを渡すことができました。

　

別パターンのコンポーネントを作成

variants(BEMで言うところのモディファイア)を作成してみます。
componentsディレクトリ内にalert–caution.hbsというファイルを作成して、以下の内容を記述します。

<div class="alert alert--caution">{{text}}</div>

/public/css/style.cssにもスタイルを追加します。

.alert--caution {
	color: yellow;
}

左ナビの表示が「Default」と「Caution」になり、別パターンのコンポーネントを追加できました。

先ほど追加した「alert.config.json」にvariantsの設定も追加できます。
以下のように変更します。

{
	"title": "アラート",
	"context": {
		"text": "alert.config.jsonから設定"
	},
	"variants": [
		{
			"name": "caution",
			"title": "アラートの別パターン",
			"context": {
				"text": "variants内で別途設定"
			}
		}
	]
}

ページタイトルとコンポーネントのテキストを変更できました。

　

グループ化

ここまでcomponentsディレクトリ直下にファイルを設置してきましたが、さらにその中でフォルダ分けすることでグループ分けすることもできます。
例として、componentsディレクトリ内にgroupというフォルダを作成して、alert.hbsとalert–caution.hbsとalert.config.jsonをフォルダ内に移動します。
さらにgroupディレクトリ内にbtn.hbsというコンポーネントを以下の内容で追加します。

<button class="btn">Button</button>

/public/css/style.cssにスタイルを追加します。

.btn {
	-webkit-appearance: none;
	-moz-appearance: none;
	appearance: none;
	padding: 0;
	border: none;
	outline: none;
	color: #000;
	font-size: 14px;
	font-family: "ヒラギノ角ゴ ProN W3", "Hiragino Kaku Gothic ProN", "メイリオ", Meiryo, sans-serif;
	background: transparent;
	cursor: pointer;

	border: #000 1px solid;
	border-radius: 3px;
	padding: 5px 10px;
}

左ナビを「Group」という括りでまとめることができました。

　

インクルード

他のコンポーネントの内容をインクルードして使用することもできます。
以下の内容でcomponentsディレクトリ内にsearch.hbsを作成します。

<input type="search" name="keywords">
{{> @btn }}

{{> @btn }}で先ほど追加したbtn.hbsをインクルードしています。

ここまでのディレクトリ構造は以下のようになっています。

  • public
    • css
      • style.css
  • src
    • components
      • group
        • alert.config.json
        • alert.hbs
        • alert–caution.hbs
        • btn.hbs
      • _preview.hbs
      • search.hbs
    • docs
      • index.md
  • fractalfile.js
  • package.json

　

テーマの変更

全体のテーマのカラーがいくつか用意されているようなので設定してみます。
fractalfile.jsを以下のように変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	skin: "olive"
});
fractal.web.theme(myCustomisedTheme);

カラーを変更できました。

用意されているテーマではなく、CSS読み込みの変更もできます。
今回はデフォルトのテーマの後にCSSを追加で読み込み、上書きするようにしてみます。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	"styles": [
		"default",
		"/css/styleguide.css"
	]
});
fractal.web.theme(myCustomisedTheme);

/public/css/にstyleguide.cssを作成して、以下のように記述します。

.Header {
	background: black;
}

ヘッダーの色を変更できました。

　

エクスポート

静的なHTMLにエクスポートするオプションも用意されています。
fractalfile.jsを以下のように変更します。

'use strict';

// fractalインスタンスを作成してエクスポート
const fractal = module.exports = require('@frctl/fractal').create();
// プロジェクト関連のメタデータ設定
fractal.set('project.title', 'cly7796.net');
fractal.set('project.author', 'cly7796');
// コンポーネントの設定
fractal.components.set('path', __dirname + '/src/components');
// ドキュメントページの設定
fractal.docs.set('path', __dirname + '/src/docs');
// 静的ファイルの設定
fractal.web.set('static.path', __dirname + '/public');
// テーマの設定
const mandelbrot = require('@frctl/mandelbrot');
const myCustomisedTheme = mandelbrot({
	"styles": [
		"default",
		"/css/styleguide.css"
	]
});
fractal.web.theme(myCustomisedTheme);
// HTMLの生成
fractal.web.set('builder.dest', __dirname + '/build');

これで/build/に静的HTMLの状態でスタイルガイドが生成されるようになりました。
以下のコマンドでビルドを行います。

fractal build

「Build finished with no errors.」と表示されればOKです。
以下のように生成することができました。
スタイルガイドのデモページ
　

【参考サイト】

　

このエントリーをはてなブックマークに追加

関連記事

コメントを残す

メールアドレスが公開されることはありません。
* が付いている欄は必須項目です

CAPTCHA


コメントが承認されるまで時間がかかります。

Category

Tag

Recent

2024年11月
日 月 火 水 木 金 土
 12
3456789
10111213141516
17181920212223
24252627282930