Tvorba rozšíření pro Tracy
**************************

<div class=perex>

Tracy poskytuje skvělý nástroj pro ladění vaší aplikace. Občas byste ale po ruce měli rádi i některé další informace. Ukážeme si, jak napsat vlastní rozšíření pro Tracy Bar, aby byl vývoj ještě příjemnější.

- Vytvoření vlastního panelu pro Tracy Bar
- Vytvoření vlastního rozšíření pro Bluescreen

</div>

.[tip]
Repozitář hotových rozšíření pro Tracy najdete na "Componette":https://componette.org/search/tracy.


Rozšíření pro Tracy Bar
=======================

Vytvořit nové rozšíření pro Tracy Bar není nic složitého. Vytvoříte objekt implementující rozhraní `Tracy\IBarPanel`, které má dvě metody `getTab()` a `getPanel()`. Metody musí vrátit HTML kód tabu (malý popisek zobrazený přímo na Baru) a panelu. Pokud `getPanel()` nic nevrátí, zobrazí se jen samotný popisek. Pokud `getTab()` nic nevrátí, nezobrazí se vůbec nic a ani getPanel() se už nevolá.

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

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


Registrace
----------

Registrace se provádí pomocí `Tracy\Bar::addPanel()`:

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

Nebo můžete panel registrovat přímo v konfiguraci aplikace:

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


HTML kód tabu
-------------

Měl by vypadat přibližně takto:

```latte
<span title="Vysvětlující popisek">
	<svg>...</svg>
	<span class="tracy-label">Titulek</span>
</span>
```

Obrázek by měl být ve formátu SVG. Pokud není vysvětlující popisek potřeba, lze `<span>` vynechat.


HTML kód panelu
---------------

Měl by vypadat přibližně takto:

```latte
<h1>Titulek</h1>

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

Titulek by měl být buď stejný, jako titulek tabu, nebo může obsahovat údaje navíc.

Je třeba počítat s tím, že jedno rozšíření se může zaregistrovat i vícekrát, kupříkladu s jiným nastavením, takže pro stylování nelze používat CSS id, ale jen class, a to ve tvaru `tracy-addons-<NazevTridy>[-<volitelné>]`. Třídu pak zapište do divu společně s třídou `tracy-inner`. Při zápisu CSS je užitečné psát `#tracy-debug .trida`, protože pravidlo pak má vyšší prioritu než reset.


Výchozí styly
-------------

V panelu jsou předstylované `<a>`, `<table>`, `<pre>`, `<code>`. Pokud chcete vytvořit odkaz, který skrývá a zobrazuje jiný prvek, propojte je atributy `href` a `id` a třídou `tracy-toggle`:

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

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

Pokud má být výchozí stav sbalený, doplňte oběma elementům třídu `tracy-collapsed`.

Counter použijte statický, aby se nevytvářely duplicitní ID na jedné stránce.


Rozšíření pro Bluescreen
========================

Tímto způsobem lze přidávat vlastní vizualizace výjimek nebo panely, které se zobrazí na bluescreen.

Rozšíření se vytvoří tímto příkazem:
```php
Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // zachycená výjimka
	return [
		'tab' => '...Popiska...',
		'panel' => '...HTML kod panelu...',
	];
});
```

Funkce je volána dvakrát, nejprve je v parametru `$e` předána samotná výjimka a vrácený panel se vykreslí na začátku stránky. Pokud nic nevrátí, panel se nevykreslí. Poté je volána s parametrem `null` a vrácený panel se vykreslí pod callstackem. Pokud funkce vrací v poli klíč `'bottom' => true`, panel se vykreslí úplně dole.