Oxwall Software Documentation dev:tuts

Birthday list

2012-10-24T11:08:26+00:00

Birthday list

Here is a an example of a working plugin that shows users with upcoming birthdays. It consists of:

Main page widget - shows all site users with upcoming birthdays within 7 days if any.
Dashboard widget - shows member's friends with upcoming birthdays within 7 days if any.
Profile widget - shows member's upcoming birthday status within 7 days if available.
Separate page with the list of users with upcoming birthdays withing 7 days if any.

You can view the above pieces of code and also download the plugin from the Oxwall Store for general plugin creation guidelines.

Birthdays: Separate page

2012-10-24T11:08:38+00:00

Birthdays: Separate page

Here we create a separate page with upcoming birthdays of site users.

Objective

Add “Birthdays” list to “Members” page

Implementation - Server Side (PHP)

birthdays/init.php

// class that contains all data and functionality to add new type of members listing  
        class BIRTHDAYS_UsersPageData implements BASE_CLASS_IusersPageData
        {

            //set menu item for "Birthdays" page
            public function getMenuItem()
            {
                //$language - helps our site to be multilingual
                $language = OW::getLanguage();

                //initializing menu item
                $item = new BASE_MenuItem();

                $item->setLabel($language->text('base', 'user_list_menu_item_birthdays'))
                    ->setKey('birthdays')
                    ->setUrl(OW::getRouter()
                        ->urlForRoute('birthdays_users'))
                    ->setOrder(5)
                    ->setIconClass('ow_ic_calendar');

                if ( $this->isCase() )
                {
                    $item->setActive(true); // activate menu if "Birthdays" selected
                }

                return $item;
            }

            // check if URL is belong to "Birthdays" page
            public function isCase()
            {
                return false !== strstr(OW::getRequest()->getRequestUri(), OW::getRouter()->uriForRoute('birthdays_users'));
            }

            // "Birthdays" page's unique key
            public function getCase()
            {
                return 'birthdays';
            }

            // get data for "Birthdays" user listing
            public function getData( $first, $count )
            {
                $service = BOL_UserService::getInstance();

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

                return array(
                    $service->findListByBirthdayPeriod($period['start'], $period['end'], $first, $count), // get users
                    $service->countByBirthdayPeriod($start, $end) // count users
                );
            }
        }

        // register data for "Birthdays" page. 
        OW::getRegistry()->addToArray('users_page_data', new BIRTHDAYS_UsersPageData());

Birthdays: Main page widget

2012-10-24T11:08:50+00:00

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');

Sample plugins with tutorials

2012-10-24T11:09:02+00:00

Sample plugins with tutorials

Here you can find examples and code's samples of some plugins. In some cases this is the good practice to learn code structure and begin to study plugin's development.

Birthday List

dev:tuts:repository

2013-08-27T12:18:32+00:00

Using Oxwall Repository.

1. Create an account at: https://bitbucket.org/account/simple-signup/
2. Sign in and proceed to Oxwall's public repository located at : https://bitbucket.org/oxwall/public
3. Fork the repository
4. Clone forked repository to your local machine
5. Do the changes.
6. Push changes ( commit) to your fork
6. Create Pull Request.
7. Wait.