4.2.1 Build widget from interface

Using interface feWidgetContract to build your own widget

This interface/contract can be located at "/vendor/feiron/felaraframe/src/widgets/contracts/feWidgetContract.php"

Interface explained

When building a widget, certain methods are required to properly picked up by the framework and rendering correctly. The following descriptions will explain every required methods to be implemented.

1. WidgetName()

   This method is used to retrieve the widget name to differentiate itself from other widgets in the bank.

2. render()

   This method is responsible for outputting the final HTMLs to the recipient. Within this method, you may:

   • Initialize or process widget related parameters such as "WidgetData", "AjaxLoad" or header/footer scripts parameters.
   • You may also build a brand new Laravel view object, pass in all necessary values and call the "render" function to output a view.

   Bottom line is, the return of this method is what finally shows at the front-end.

3. dataFunction()

   This method is responsible for building widget specific data when objects are used as part of the widget output. The objective of this method is to set the value for "WidgetData" parameter.

   This method is called within the process of render() method to build the main contents of the widget.

4. renderAjax($request)

   This method takes a Laravel Request object and returns the result for widgets that load their data via Ajax requests.

   The return can be json, text, etc, and it's sent directly back to the browser.

5. getAjaxData($request)

   This method acts like an outlet for extended classes to build their own version of data generation functions.

   You can simply make this a proxy of dataFunction() and return $this->dataFunction(), to have the same behavior when rending widget and sending ajax results. Or you can have widget render html framework via dataFunction() and use getAjaxData() to provide data to fill in the framework via ajax request.

6. SetID($name)

   This method sets the ID of the widget. An ID that uniquely identifies itself within the bank.

7. static userSettingOutlet()

   This method is responsible for providing widget specific settings to the front-end for users to configure. Making widget highly adaptive for a variety of users.

   The return value could be json or array. It will be picked up by the framework, converted to the right control and provided to the user.

   The format of the options should be like the following:

      [
          'key'=>'option name', 
          'type'=>'html control type(text,radio,select,etc...)',
          'placeholder'=>'html place holder',
          'options'=>['1','2','3','4'],//if radio or select is used as type, we can set the options
          'value'=>'default value'
      ]
   

8. getWidgetSettings()

   Returns the list of settings available as an array to the widget with their values.

9. getHeaderScripts()

   Returns the list of js scripts as an array to be loaded at the beginning of the document when rendering the widget.

10. getHeaderStyle()

    Returns the list of css scripts as an array to be loaded at the beginning of the document when rendering the widget.

11. getFooterScripts()

    Returns the list of js scripts as an array to be loaded at the end of the document when rendering the widget.

12. getFooterStyle()

    Returns the list of css scripts as an array to be loaded at the end of the document when rendering the widget.

---

How to use it.

It is rather extensive and for the sake of keeping this article short, please refer to the abstract class for an example of how to use the interface.

/vendor/feiron/felaraframe/src/widgets/lib/WidgetAbstract.php

I promise you for a good example when I finally get some time to write it 😄