Création d'extensions de Tracy
******************************

<div class=perex>

Tracy est un excellent outil pour déboguer votre application. Cependant, vous avez parfois besoin de plus d'informations que celles offertes par Tracy. Vous apprendrez à connaître :

- Créer vos propres panneaux Tracy Bar
- Créer vos propres extensions Bluescreen

</div>

.[tip]
Vous pouvez trouver des extensions utiles pour Tracy sur "Componette":https://componette.org/search/tracy.


Extensions de la barre Tracy .[#toc-tracy-bar-extensions]
=========================================================

La création d'une nouvelle extension pour Tracy Bar est simple. Vous devez implémenter l'interface `Tracy\IBarPanel` avec les méthodes `getTab()` et `getPanel()`. Ces méthodes doivent renvoyer le code HTML d'un onglet (petite étiquette sur Tracy Bar) et d'un panneau (fenêtre contextuelle affichée après avoir cliqué sur l'onglet). Si `getPanel()` ne renvoie rien, seul l'onglet sera affiché. Si `getTab()` ne renvoie rien, rien n'est affiché et `getPanel()` ne sera pas appelé.

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

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


Enregistrement .[#toc-registration]
-----------------------------------

L'inscription se fait en appelant `Tracy\Bar::addPanel()`:

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

ou vous pouvez simplement enregistrer votre panneau dans la configuration de l'application :

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


Code HTML de l'onglet .[#toc-tab-html-code]
-------------------------------------------

devrait ressembler à quelque chose comme ceci :

```latte
<span title="Explaining tooltip">
	<svg>...</svg>
	<span class="tracy-label">Title</span>
</span>
```

L'image doit être au format SVG. Si vous n'avez pas besoin d'infobulle, vous pouvez omettre `<span>` l'info-bulle.


Code HTML du panneau .[#toc-panel-html-code]
--------------------------------------------

devrait ressembler à quelque chose comme ceci :

```latte
<h1>Title</h1>

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

Le titre doit être identique à celui de l'onglet ou contenir des informations supplémentaires.

Une extension peut être enregistrée plusieurs fois, il est donc recommandé de ne pas utiliser l'attribut `id` pour le style. Vous pouvez utiliser des classes, de préférence au format `tracy-addons-<class-name>[-<optional>]` de préférence. Lors de la création d'un CSS, il est préférable d'utiliser `#tracy-debug .class`, car cette règle a une priorité supérieure à celle de la réinitialisation.


Styles par défaut .[#toc-default-styles]
----------------------------------------

Dans le panneau, les éléments `<a>`, `<table>`, `<pre>`, `<code>` ont des styles par défaut. Pour créer un lien permettant de masquer ou d'afficher un autre élément, connectez-les avec les attributs `href` et `id` et la classe `tracy-toggle`.

```latte
<a href="#tracy-addons-className-{$counter}" class="tracy-toggle">Detail</a>

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

Si l'état par défaut est effondré, ajoutez la classe `tracy-collapsed` aux deux éléments.

Utilisez un compteur statique pour éviter les doublons d'identifiants sur une page.


Extensions de Bluescreen .[#toc-bluescreen-extensions]
======================================================

Vous pouvez ajouter vos propres visualisations d'exception ou panneaux, qui apparaîtront sur le bluescreen.

L'extension est faite comme ceci :
```php
Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // catched exception
	return [
		'tab' => '...Title...',
		'panel' => '...content...',
	];
});
```

La fonction est appelée deux fois, d'abord l'exception elle-même est passée dans le paramètre `$e` et le panneau retourné est rendu au début de la page. Si rien n'est renvoyé, le panneau n'est pas rendu. Ensuite, elle est appelée avec le paramètre `null` et le panneau renvoyé est rendu en dessous de la pile d'appels. Si la fonction renvoie `'bottom' => true` dans le tableau, le panneau est rendu tout en bas.