• Standard structure
• List of events
  • onInit()
  • onRender()
• template
• resouceSettings
• useDataSource
• useAutoName
• useLanguage
• Conclusion

Create Widget

Standard structure #

MyWidget.php

class MyWidget extends \koolreport\core\Widget
{
    /**
     * This method will be called when the widget is initiated.
     * 
     * @return null
     */
    protected function onInit()
    {
        
    }

    /**
     * Be called to render widget
     * 
     * The descendant widget class will overwrite this function to render itself.
     * 
     * @return null
     */
    protected function onRender()
    {
        $this->template('MyWidget');
    }
}

MyWidget.tpl.php

<div>Hello world!</div>

List of events #

onInit() #

This method will be called when widget is initiated, you may get all the parameters provided through $this->params.

onRender() #

This method will be called when widget is about to render. Here you will manually render the view of Widget. You can echo any content of widget to the browser. There is template() method which can use to render any template associated with the widget. We will learn about the template method in the following section.

Note: If you do not overwrite the onRender() method, widget will look for the view {widget-name}.tpl.php to render. For example if your widget classname is MyWidget, it will look for MyWidget.tpl.php to render the view.

template #

template([string $view],[array $variables],[bool $return])

This method is to render template view of widget, it should be called inside the onRender() event handler. There are several case of usages:

Case 1: If you call this method without any parameters, it will render default view which is {widget-class-name}.tpl.php

$this->template(); // Render the MyWidget.tpl.php

Case 2: You can render any template that suffixed with tpl.php:

$this->template("MyWidget"); //Render MyWidget.tpl.php

$this->template("AnotherView"); //Render AnotherView.tpl.php

Case 3: Send some parameters to the view

$this->template("MyWidget",array(
    "name"=>"Peter";
));

//MyWidget.tpl.php
<div>Hello <?php echo $name ?>!</div>

//Result: Hello Peter!

Case 3: You need template to return content in string instead of sending content to browser

$content = $this->template("MyWidget",array(),true);

resouceSettings #

Now your widget may have resource file like css or js to be called. You should store all your resources file in a folder next the your widget, something like this:

widgets
├── resources
│   ├── mywidget.js
│   └── mywidget.css
├── MyWidget.php
└── MyWidget.tpl.php

Now in your Widget.php, you specify resourceSettings() method which return list of dependent resources:

class MyWidget extends \koolreport\core\Widget
{
    protected function resourceSettings()
    {
        return array(
            "libraries"=>array("jQuery"),
            "folder"=>"resources"
            "css"=>array("mywidget.css"),
            "js"=>array("mywidget.js")
        );
    }
}

Above resource settings tell widget to load jQuery built-in and then look for other resources inside resources folder. It should load the the mywidget.js and mywidget.css on render.

Now inside the MyWidget.tpl.php, you should have the following code:

<div> My Widget content</div>
<script type="text/javascript">
KoolReport.widget.init(<?php echo json_encode($this->getResources()); ?>,function(){
    // You can write any code to initate your widget in here.
    // This will be execute when all resources is loaded
});
</script>

Above KoolReport.widget.init() help widget to load its specified resources like jQuery, mywidget.js and mywidget.css before executing your initiating code.

useDataSource #

Normally your widget will need data to be rendered. Although it is not compulsory, most of KoolReport widget will have following pattern:

MyWidget::create(array(
    "dataSource"=>$this->dataStore("result")
));

In order to get dataSource auto settings like above, you just need to called useDataSource() inside onInit() method:

class MyWidget extends \koolreport\core\Widget
{
    protected function onInit()
    {
        $this->useDataSource();
        ...
    }

    protected function onRender()
    {
        //You can access data through $this->dataStore
        foreach($this->dataStore as $row)
        {
            echo $row["name"];
        }
    }
}

And now, you can access data provided to your widget at $this->dataStore.

useAutoName #

If your widget need an auto name, you can use useAutoName() like below:

class MyWidget extends \koolreport\core\Widget
{
    protected function onInit()
    {
        $this->useAutoName("mywidget");
        ...
    }

    protected function onRender()
    {
        //Your name is auto generated
        echo $this->name; // You will get name with prefix "mywidget" like "mywidget12hdhffd"
    }
}

useLanguage #

Widget may have language to be set

MyWidget::create(array(
    ...
    "language"=>"es"
    ...
));

In order to create language for your widget, you need to create languages folder next to MyWidget.php like this:

widgets
├── languages
│   ├── MyWidget.th.json
│   └── MyWidget.es.json
├── MyWidget.php
└── MyWidget.tpl.php

In your MyWidget.es.json for example, you write the translation in form of key value like following:

{
    "There is no data"=>"No hay datos"
}

Now, in your MyWidget.php you turn on the language feature

class MyWidget extends \koolreport\core\Widget
{
    protected function onInit()
    {
        $this->useLanguage();
        ...
    }
}

And then in your MyWidget.tpl.php, you can use your language translation like this:

<div><?php echo $this->translate("There is no data"); ?></div>

Now your widget will render the language based on the "language" settings you put to widget's parameters.

Conclusion #

We have covered the standard structure of KoolReport's Widget. We also cover how to render template, how to add dependent resources to widget, how to use data in your widget and how to set language. Have fun with creating new widget. If you need any assistance, feel free to post on our forum.