Here's how we create a widget on the main page that shows the upcoming birthdays of site users.

Objective

• Create “Birthdays” widget for Index page
• Use standard BASE_CMP_UsersWidget component

Implementation - Server Side (PHP)

birthdays/components/birthdays_widget.php

class BIRTHDAYS_CMP_BirthdaysWidget extends BASE_CMP_UsersWidget
{

    public function getData( $count )
    {
        //$language - helps our site to be multilingual  
        $language = OW::getLanguage();

        // $userService - contain basic user functionality
        $userService = BOL_UserService::getInstance();

        // $toolbar - widget's toolbar
        $toolbar = self::getToolbar();

        //set date bounds for birthdays 
        $period = array(
            'start' => date('Y-m-d'),
            'end' => date('Y-m-d', strtotime('+7 day'))
        );

        // getting users
        $users = $userService->findListByBirthdayPeriod($period['start'], $period['end'], 0, $count);


        if ( !$this->isCustomizeMode && empty($users) )
        {
            //hide widget if there are no Birthdays this week
            $this->setVisible(false);
        }

        return array(
            array(
                'key' => 'birthdays',
                'menu-label' => $language->text('birthdays', 'user_list_menu_item_birthdays'),
                'users' => $users,
                'toolbar' => $toolbar['birthdays'][0],
            ),
        );
    }

    //returns array of toolbar items
    public static function getToolbar()
    {
        return array(
            'birthdays' => array(
                array(
                    'label' => OW::getLanguage()->text('base', 'view_all'),
                    'href' => OW::getRouter()->urlForRoute('birthdays_users')
                )
            ),
        );
    }

    //default settings
    public static function getSettingList()
    {
        $settingList = array();
        $settingList['count'] = array(
            'presentation' => 'number',
            'label' => 'Count',
            'value' => '10'
        );

        return $settingList;
    }

    // set title and toolbar
    public static function getStandardSettingValueList()
    {
        $toolbars = self::getToolbar();
        return array(
            self::SETTING_TITLE => OW::getLanguage()->text('birthdays', 'widget_title'),
            self::SETTING_TOOLBAR => $toolbars['birthdays']
        );
    }

    // set who allowed to see widget
    public static function getAccess()
    {
        /*
          ACCESS_GUEST - for guests only,
          ACCESS_ALL  - everyone,
          ACCESS_MEMBER - only for registered users )
         */
        return self::ACCESS_ALL;
    }
}

birthdays/activate.php

        //add 'birthdays' widget to index page when plugin activated
        $placeWidget = BOL_ComponentAdminService::getInstance()->addWidgetToPlace(
            BOL_ComponentAdminService::getInstance()->addWidget('BIRTHDAYS_CMP_BirthdaysWidget', false),
            BOL_ComponentAdminService::PLACE_INDEX
        );
        
        //place widget on index page's left section
        BOL_ComponentAdminService::getInstance()->addWidgetToPosition($placeWidget, BOL_ComponentAdminService::SECTION_LEFT);

birthdays/deactivate.php

	//remove 'birthdays' widget when plugin deactivated
	BOL_ComponentAdminService::getInstance()->deleteWidget('BIRTHDAYS_CMP_BirthdaysWidget');