Criando Extensões Tracy
***********************

<div class=perex>

Tracy é uma ótima ferramenta para depuração de sua aplicação. Entretanto, às vezes você precisa de mais informações do que Tracy oferece. Você aprenderá sobre isso:

- Criando seus próprios painéis Tracy Bar
- Criando suas próprias extensões Bluescreen

</div>

.[tip]
Você pode encontrar extensões úteis para Tracy em "Componette":https://componette.org/search/tracy.


Extensões de Barras Tracy .[#toc-tracy-bar-extensions]
======================================================

Criar uma nova extensão para Tracy Bar é simples. Você precisa implementar `Tracy\IBarPanel` interface com os métodos `getTab()` e `getPanel()`. Os métodos devem retornar o código HTML de uma aba (pequena etiqueta na Tracy Bar) e um painel (pop-up exibido após clicar na aba). Se `getPanel()` não retorna nada, somente a aba será exibida. Se `getTab()` não retorna nada, nada será exibido e `getPanel()` não será chamado.

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

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


Registro .[#toc-registration]
-----------------------------

O registro é feito ligando para `Tracy\Bar::addPanel()`:

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

ou você pode simplesmente registrar seu painel na configuração da aplicação:

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


Tab Código HTML .[#toc-tab-html-code]
-------------------------------------

Deve ser parecido com isto:

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

A imagem deve estar no formato SVG. Se você não precisa de ponta de ferramenta, você pode deixar `<span>` fora.


Código HTML do Painel .[#toc-panel-html-code]
---------------------------------------------

Deve ser parecido com isto:

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

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

O título deve ser o mesmo que na guia ou conter informações adicionais.

Uma extensão pode ser registrada várias vezes, por isso é recomendado não utilizar o atributo `id` para a criação de estilos. Você pode usar classes, de preferência em `tracy-addons-<class-name>[-<optional>]` formato. Ao criar o CSS, é melhor usar `#tracy-debug .class`, pois tal regra tem maior prioridade do que o reset.


Estilos padrão .[#toc-default-styles]
-------------------------------------

No painel, elementos `<a>`, `<table>`, `<pre>`, `<code>` têm estilos padrão. Para criar um link para esconder ou exibir outro elemento, conecte-os com `href` e `id` atributos e classe `tracy-toggle`.

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

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

Se o estado padrão for desmoronado, adicione a classe `tracy-collapsed` a ambos os elementos.

Use um contador estático para evitar duplicatas de identificação em uma página.


Extensões de tela Bluescreen .[#toc-bluescreen-extensions]
==========================================================

Você pode adicionar suas próprias visualizações de exceção ou painéis, que aparecerão na tela azul.

A extensão é feita desta forma:
```php
Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // catched exception
	return [
		'tab' => '...Título...',
		'panel' => '...conteúdo...',
	];
});
```

A função é chamada duas vezes, primeiro a própria exceção é passada no parâmetro `$e` e o painel retornado é apresentado no início da página. Se nada for retornado, o painel não é renderizado. Em seguida é chamado com o parâmetro `null` e o painel retornado é renderizado abaixo do indicativo. Se a função retorna `'bottom' => true` no array, o painel é renderizado na parte inferior.