Nette Documentation Preview

syntax
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.

Création d'extensions de Tracy

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

Vous pouvez trouver des extensions utiles pour Tracy sur Componette.

Extensions de la barre Tracy

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é.

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

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

Enregistrement

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

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

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

tracy:
	bar:
		- ExamplePanel

Code HTML de l'onglet

devrait ressembler à quelque chose comme ceci :

<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

devrait ressembler à quelque chose comme ceci :

<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

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.

<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

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

L'extension est faite comme ceci :

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.