====== What is a widget? ======

**Widget** is a component that can be added to the widget panel ( index page, dashboard, profile page, etc. ). **Widget** is a child of the **BASE_CLASS_Widget** class, which in its turn is a child class of **OW_Component**. 

Thus, widget is a standard component with additional functionality. 

====== Widget creation ======

We will use the standard Custom Html widget as an example.

Class
<code php>
class BASE_CMP_CustomHtmlWidget extends BASE_CLASS_Widget
{
    private $content = false;
    private $nl2br = false;

    public function __construct( BASE_CLASS_WidgetParameter $paramObject )
    {
        parent::__construct();

        $params = $paramObject->customParamList;

        if ( !empty($params['content']) )
        {
            $this->content = $paramObject->customizeMode && !empty($_GET['disable-js']) ? UTIL_HtmlTag::stripJs($params['content']) : $params['content'];
        }

        if ( isset($params['nl_to_br']) )
        {
            $this->nl2br = (bool) $params['nl_to_br'];
        }
    }

    public static function getSettingList() // If you redefine this method, you'll be able to add fields to the widget configuration form 
    {
        $settingList = array();
        $settingList['content'] = array(
            'presentation' => self::PRESENTATION_TEXTAREA, // Field type
            'label' => OW::getLanguage()->text('base', 'custom_html_widget_content_label'), // Field name
            'value' => '' // Default value
        );

        $settingList['nl_to_br'] = array(
            'presentation' => self::PRESENTATION_CHECKBOX,
            'label' => OW::getLanguage()->text('base', 'custom_html_widget_nl2br_label'),
            'value' => '0'
        );

        return $settingList;
    }

    public static function processSettingList( $settings, $place ) // This method is called before saving the widget settings. Here you can process the settings entered by a user before saving them. 
    {
        if ( $place != BOL_ComponentService::PLACE_DASHBOARD && !OW::getUser()->isAdmin() )
        {
            $settings['content'] = UTIL_HtmlTag::stripJs($settings['content']);
            $settings['content'] = UTIL_HtmlTag::stripTags($settings['content'], array('frame'), array(), true, true);
        }
        else
        {
            $settings['content'] = UTIL_HtmlTag::sanitize($settings['content']);
        }
        
        return $settings;
    }
    
    public static function getStandardSettingValueList() // If you redefine this method, you will be able to set default values for the standard widget settings. 
    {
        return array(
            self::SETTING_TITLE => OW::getLanguage()->text('base', 'custom_html_widget_default_title') // Set the widget title 
        );
    }

    public static function getAccess() // If you redefine this method, you'll be able to manage the widget visibility 
    {
        return self::ACCESS_ALL;
    }

    public function onBeforeRender() // The standard method of the component that is called before rendering
    {
        $content = $this->nl2br ? nl2br( $this->content ) : $this->content;
        $this->assign('content', $content);
    }
}
</code>

Each widget's constructor has one parameter - the object of BASE_CLASS_WidgetParameter class\\

**BASE_CLASS_WidgetParameter** has the following fields\\
- **$customParamList** - is the associative array of the settings' fields values added by a user\\
- **$additionalParamList** - is the associative array of the additional parameters. For example, user ID can be taken from this array (if the widget is placed to the profile page).\\
Array element **entityId** - is user Id\\
- **$standartParamLiqt** - is the object of WidgetStandartParamList class. You can get the values of the standard widget settings from this object.\\
- **$customizeMode** - this field contains boolean value.\\
- **$widgetDetails** - is the object of WidgetDetails class. It contains information on a certain widget sample. Currently it consists of only one field - **$uniqName** - unique widget name\\

The widget functionality can be managed by redefining the following methods of the parent class\\
- **getSettingList** - if this method is redefined, you will be able to add fields to the widget configuration form\\
- **processSettingList** - this method is called before saving the widget settings. Here you can process the settings entered by a user before saving them.\\ 
- **getStandardSettingValueList** - if this method is redefined, you will be able to set default values for the standard widget settings\\
- **getAccess** - if this method is redefined, you will be able to manage the widget visibility \\
- **validateSettingList** - redefining this method will make it possible to check the data entered by a user in the widget configuration form. Throwing WidgetSettingValidateException type exception into this method will prevent settings from being saved. You should pass the message and the name of the form's field whose value failed the check to the exception constructor\\

In other aspects, a widget's behavior is no different from a standard component's behavior\\

====== Adding a widget (activate.php)======

Once you've created a widget, you should add it to the widgets page\\
Here is an example of adding a Custom Html widget to the Dashboard page\\
<code php>
$widgetService = BOL_ComponentAdminService::getInstance();

$widget = $widgetService->addWidget('BASE_CMP_CustomHtml', true); // Register the widget. The first parameter is the name of the widget class. The second parameter stands for whether the widget can be cloned, or may have only one sample on the page\\
$widgetPlace = $widgetService->addWidgetToPlace($widget, BOL_ComponentService::PLACE_DASHBOARD); // Add the widget to the page
$widgetService->addWidgetToPosition($widgetPlace, BOL_ComponentService::SECTION_LEFT, 0); // Choose a special position on the page to add the widget. the third parameter of this function is the widget's position in a certain section. If you want to add the widget to the very bottom, you should set -1. 
</code>

====== Deleting a widget (deactivate.php)======
The widget can be deleted the following way\\
<code php>
BOL_ComponentAdminService::getInstance()->deleteWidget('BASE_CMP_CustomHtml'); // remove the widget and all its samples from all pages 
</code>

Remember, If edits are made you need to deactivate and reactivate your widget in your admin panel

Usually, a plugin activation adds a widget. Deactivating a plugin removes a widget.