Nette Documentation Preview

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

Criando Extensões Tracy

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

Você pode encontrar extensões úteis para Tracy em Componette.

Extensões de Barras Tracy

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.

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

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

Registro

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

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

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

tracy:
	bar:
		- ExamplePanel

Tab Código HTML

Deve ser parecido com isto:

<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

Deve ser parecido com isto:

<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

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.

<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

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:

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.