# Rendering

Rendering is performed using the `DebugBar\JavascriptRenderer` class. It contains
all the useful functions to included the needed assets and generate a debug bar.

    $renderer = $debugbar->getJavascriptRenderer();

## Assets

The debug bar relies on some css and javascript files which needs to be included
into your webpage. They are located in the *src/DebugBar/Resources* folder.
Additionally, asset providers may provide inline assets that have to be embedded
directly in the HTML.  This can be done in four ways:

 - Using `JavascriptRenderer::renderHead()` which will returns a string with
   the needed script and link tags
 - Using [Assetic](https://github.com/kriswallsmith/assetic) and
   `JavascriptRenderer::getAsseticCollection()`
 - Dumping the assets yourself using `JavascriptRenderer::dumpCssAssets()`,
   `JavascriptRenderer::dumpJsAssets()`, and `JavascriptRenderer::dumpHeadAssets()`.
 - Retrieving filenames and inline content of assets using `JavascriptRenderer::getAssets()`
   and doing something with it

I would recommend using the second method as Assetic is a very powerful asset
manager but the other methods are provided to quickly integrate the debug bar
into any projects.

You can define the base url of your assets using `setBaseUrl()`. This is needed
in 99% of cases.

Using `renderHead()`:

    <html>
        <head>
            ...
            <?php echo $renderer->renderHead() ?>
            ...
        </head>
        ...
    </html>

Using Assetic:

    list($cssCollection, $jsCollection, $inlineHeadCollection) = $renderer->getAsseticCollection();

Dumping the assets:

    header('Content-Type: text/javascript');
    $renderer->dumpJsAssets();

Retrieving the assets:

    list($cssFiles, $jsFiles, $inlineCss, $inlineJs, $inlineHead) = $renderer->getAssets();

Note that you can only use the debug bar assets and manage the dependencies by yourself
using `$renderer->setIncludeVendors(false)`. Instead of false, *css* or *js* may be used
to only include css or js assets of vendors.

## Managing jQuery conflicts

When the debug bar script is included, it will be bound to the current jQuery object.
The default action is to call `jQuery.noConflict(true)` after this is done.

This has two implications:

 - jQuery won't be available anymore if you didn't include your own version
   before including the debug bar's vendors
 - your own version will be restored.

If you use `JavascriptRenderer::setIncludeVendors()` to disable the inclusion of js
vendors (ie. jquery), `jQuery.noConflict(true)` won't be called.

You can manage whether `jQuery.noConflict(true)` should be called or not using
`JavascriptRenderer::setEnableJqueryNoConflict()`.

## The javascript object

The renderer will generate all the needed code for your debug bar. This means
initializing the DebugBar js object, adding tabs and indicators, defining a data map, etc...

Data collectors can provide their own controls when implementing the
`DebugBar\DataCollector\Renderable` interface as explained in the Collecting Data chapter.

Thus in almost all cases, you should only have to use `render()` right away:

    <html>
        ...
        <body>
            <?php echo $renderer->render() ?>
        </body>
    </html>

This will print the initialization code for the toolbar and the dataset for the request.
When you are performing AJAX requests, you do not want to initialize a new toolbar but
add the dataset to the existing one. You can disable initialization using ̀false` as
the first argument of ̀render()`.

    <p>my ajax content</p>
    <?php echo $renderer->render(false) ?>

### Controlling object initialization

You can further control the initialization of the javascript object using `setInitialization()`.
It takes a bitwise value made out of the constants `INITIALIZE_CONSTRUCTOR` and `INITIALIZE_CONTROLS`.
The first one controls whether to initialize the variable (ie. `var debugbar = new DebugBar()`). The
second one whether to initialize all the controls (ie. adding tab and indicators as well as data mapping).

You can also control the class name of the object using `setJavascriptClass()` and the name of
the instance variable using `setVariableName()`.

Let's say you have subclassed `PhpDebugBar.DebugBar` in javascript to do your own initialization.
Your new object is called `MyDebugBar`.

    $renderer->setJavascriptClass("MyDebugBar");
    $renderer->setInitialization(JavascriptRenderer::INITIALIZE_CONSTRUCTOR);
    // ...
    echo $renderer->render();

This has the result of printing:

    <script type="text/javascript">
    var phpdebugbar = new MyDebugBar();
    phpdebugbar.addDataSet({ ... });
    </script>

Using `setInitialization(0)` will only render the addDataSet part.

### Defining controls

Controls can be manually added to the debug bar using `addControl($name, $options)`. You should read
the Javascript bar chapter before this section.

`$name` will be the name of your control and `$options` is a key/value pair array with these
possible values:

- *icon*: icon name
- *tooltip*: string
- *widget*: widget class name
- *map*: a property name from the data to map the control to
- *default*: a js string, default value of the data map
- *tab*: class name of the tab object (to use a custom tab object)
- *indicator*: class name of the indicator object (to use a custom indicator object)
- *position*: position of the indicator ('left' of 'right', default to 'right')

At least *icon* or *widget* are needed (unless *tab* or *indicator* are specified). If *widget* is
specified, a tab will be created, otherwise an indicator. Any other options is also passed to the tab
or indicator.

    $renderer->addControl('messages', array(
        "widget" => "PhpDebugBar.Widgets.MessagesWidget",
        "map" => "messages",
        "default" => "[]"
    ));

You can disable a control using `disableControl($name)` and ignore any controls provided by
a collector using `ignoreCollector($name)`.
