icingaweb2/doc/widgets.md

# Widgets

Widgets are reusable UI components that are able to render themselves and return HTML to be included in your template.

## Basic interface

The interface needed for implementing widgets can be found under library/Icinga/Web/Widget/Widget.php. This is a rather
simple interface, only providing a 'render' method that takes a view and returns HTML:

    interface Widget
    {
        public function render(Zend_View_Abstract $view);
    }

When implementing own Widgets you just have to make sure that you provide this render method.

## Using widgets

Widgets are normally created in the controller and added to the view:

    // in your Controller
    public function myControllerAction()
    {
        $this->view->myWidget = new MyWidget();
    }

 The HTML is then rendered in the template using the *render()* method described above. As the '$this' scope in a view is
 a reference to your current view, you can just pass it to the *render()* method:

    // in your template

    <div>
        <h4>Look at my beautiful widget</h4>
        <?= $this->myWidget->render($this); ?>
    </div>

## The 'Tabs' widget

The Tabs (Icinga\Web\Widgets\Tabs) widget handles creation of Tab bars and allows you to create and add single tabs to this view. To create an empty
Tab bar, you just have to call:

    $tabbar = new Tabs();

**Note** : When using an ActionController, there's already an empty tabs object created under $this->view->tabs. This is
         done in the preDispatch function

### Adding tabs

Afterwards you can add tabs by calling the add($name, $tab) function, whereas $name is the name of your tab and $tab
is either an array with tab parameters or an existing Tab object.

    // Adding tabs:
    $tabbar->add("myTab", array(
        "title" => "My hosts",   // displayed as the tab text
        "iconCls"  => "myicon",  // icon-myicon will be used as an icon in a <i> tag
        "url"   => "/my/url",         // the url to use
        "urlParams" => array("host" => "localhost") // will be used as GET parameter
    ));

### Adding tabs to the dropdown list

Sometimes you want additional actions to be displayed in your tabbar. This can be accomplished with the 'addAsDropdown'
method. This one is similar to the *add* method, but displays your tab in a dropdown list on the right side of the tabbar.

## Using tabextensions

Often you find yourself adding the same tabs over and over again. You can write a Tabextension that does this for you
and just apply them on your tabs. Tabextensions are locate the Icinga/Web/Widgets/Tabextension/ and use the simple
Tabextension interface that just defines *apply(Tabs $tab)*. A simple example is the DashboardAction Tabextender which
just adds a new field to the dropdown list:

    class DashboardAction implements Tabextension
    {
        /**
         * @see Tabextension::apply()
         */
        public function apply(Tabs $tabs)
        {
            $tabs->addAsDropdown(
                'dashboard',
                array(
                    'title' => 'Add to Dashboard',
                    'iconCls' => 'dashboard',
                    'url'   => Url::fromPath('dashboard/addurl'),
                    'urlParams' => array(
                        'url'       => Url::fromRequest()->getRelativeUrl()
                    )
                )
            );
        }
    }

You can now either extend your Tabs object using the DashboardAction's *apply()* method or by calling the Tabs *extend*
method (which is more fluent):

    $tabs->extend(new DashboardAction())