Tracyの拡張機能の作成
*************

<div class=perex>

Tracyはアプリケーションのデバッグに優れたツールを提供します。しかし、時には他の情報も手元に欲しいと思うことがあります。ここでは、開発をさらに快適にするために、Tracy Bar用のカスタム拡張機能を作成する方法を示します。

- Tracy Bar用のカスタムパネルの作成
- Bluescreen用のカスタム拡張機能の作成

</div>

.[tip]
Tracy用の完成した拡張機能のリポジトリは "Componette":https://componette.org/search/tracy で見つけることができます。


Tracy Barの拡張機能
==============

Tracy Bar用の新しい拡張機能を作成することは複雑ではありません。`Tracy\IBarPanel` インターフェースを実装するオブジェクトを作成します。これには `getTab()` と `getPanel()` の2つのメソッドがあります。これらのメソッドは、タブ（Barに直接表示される小さなラベル）とパネルのHTMLコードを返す必要があります。`getPanel()` が何も返さない場合、ラベル自体のみが表示されます。`getTab()` が何も返さない場合、何も表示されず、`getPanel()` も呼び出されません。

```php
class ExamplePanel implements Tracy\IBarPanel
{
	public function getTab()
	{
		return /* ... */;
	}

	public function getPanel()
	{
		return /* ... */;
	}
}
```


登録
----------

登録は `Tracy\Bar::addPanel()` を使用して行われます：

```php
Tracy\Debugger::getBar()->addPanel(new ExamplePanel);
```

または、アプリケーションの設定で直接パネルを登録することもできます：

```neon
tracy:
	bar:
		- ExamplePanel
```


タブのHTMLコード
----------

おおよそ次のようになります：

```latte
<span title="説明的なラベル">
	<svg>...</svg>
	<span class="tracy-label">タイトル</span>
</span>
```

画像はSVG形式であるべきです。説明的なラベルが必要ない場合は、`<span>` を省略できます。


パネルのHTMLコード
-----------

おおよそ次のようになります：

```latte
<h1>タイトル</h1>

<div class="tracy-inner">
<div class="tracy-inner-container">
	... 内容 ...
</div>
</div>
```

タイトルはタブのタイトルと同じであるべきか、追加情報を含むことができます。

1つの拡張機能が、例えば異なる設定で複数回登録される可能性があることを考慮に入れる必要があります。そのため、スタイリングにはCSS idを使用できず、`tracy-addons-<ClassName>[-<optional>]` の形式のクラスのみを使用する必要があります。次に、クラスを `tracy-inner` クラスと一緒にdivに記述します。CSSを記述する際には、`#tracy-debug .class` と書くと便利です。なぜなら、ルールはリセットよりも高い優先度を持つからです。


デフォルトスタイル
---------

パネル内では、`<a>`、`<table>`、`<pre>`、`<code>` が事前スタイル設定されています。別の要素を隠したり表示したりするリンクを作成したい場合は、`href` と `id` 属性および `tracy-toggle` クラスでそれらをリンクさせます：

```latte
<a href="#tracy-addons-ClassName-{$counter}" class="tracy-toggle">詳細</a>

<div id="tracy-addons-ClassName-{$counter}">...</div>
```

デフォルト状態が折りたたまれている場合は、両方の要素に `tracy-collapsed` クラスを追加します。

カウンターは静的に使用して、1つのページに重複したIDが作成されないようにします。


Bluescreenの拡張機能
===============

この方法で、例外のカスタム視覚化や、bluescreenに表示されるパネルを追加できます。

拡張機能はこのコマンドで作成されます：
```php
Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // キャッチされた例外
	return [
		'tab' => '...ラベル...',
		'panel' => '...パネルのHTMLコード...',
	];
});
```

関数は2回呼び出されます。まず、パラメータ `$e` に例外自体が渡され、返されたパネルがページの先頭にレンダリングされます。何も返さない場合、パネルはレンダリングされません。その後、`null` パラメータで呼び出され、返されたパネルがコールスタックの下にレンダリングされます。関数が配列のキー `'bottom' => true` を返す場合、パネルは一番下にレンダリングされます。