Toolbar API

Revision as of 14:09, 18 January 2013 by Sinisakrisan (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This Toolbar API allows 3rd party plugin provider to add custom toolbar item in JomSocial toolbar menu. This API will be available in JomSocial version 1.2. The below article will show how developers can add new menu items into JomSocial toolbar through plugin.

Utilise onSystemStart

The toolbar API will only work in any of your plugins through onSystemStart function. In JomSocial, every pages will first execute this onSystemStart trigger. Thus, calling this toolbar API in onSystemStart will ease the creation of custom toolbars into JomSocial.

function onSystemStart()
{
   include_once (JPATH_ROOT . DS . "components" . DS . "com_myblog" . DS . "functions.myblog.php");
 
   if(! class_exists('CFactory'))
   {
      require_once( JPATH_ROOT . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'core.php');
   }
 
   //initialize the toolbar object	
   $toolbar	=& CFactory::getToolbar();
 
   $userName 		= $this->_user->getDisplayName();
   $myblogItemId	= myGetItemId();
 
   //adding new 'tab' 'MyBlog' in JomSocial toolbar
   $toolbar->addGroup('MYBLOG', 'MyBlog', 
	JRoute::_('index.php?option=com_myblog&task=adminhome&Itemid='.$myblogItemId));
 
   if( myGetUserCanPost() )
   {
      $writeUrl	= 'myAzrulShowWindow(\''.JURI::root().'index.php?option=com_myblog'
                . '&tmpl=component&task=write&keepThis=true&TB_iframe=true&no_html=1&id=0\')';
      $toolbar->addItem('MYBLOG', 'MYBLOG_WRITE', 'Write Blog', $writeUrl, '', true);		 
   }
 
   $toolbar->addItem('MYBLOG', 'MYBLOG_VIEW', 'View Your Blog', 
	JRoute::_('index.php?option=com_myblog&blogger='.$userName.'&Itemid='.$myblogItemId));
   $toolbar->addItem('MYBLOG', 'MYBLOG_ALL', 'All Blog Entries', 
	JRoute::_('index.php?option=com_myblog&Itemid='.$myblogItemId));
 
}


The above example will create a JomSocial's tab called 'MyBlog'.

Calling the CToolbar API

Before you can call the CToolbar API, you will need to make sure, JomSocial core class 'CFactory' is loaded. We will need this CFactory to load the CToolbar class object later on.

if(! class_exists('CFactory'))
{
   require_once JPATH_ROOT.'/components/com_community/libraries/core.php';
}


Here is how we can get the Ctoolbar object from CFactory.

$toolbar	=& CFactory::getToolbar();


The first things that you will need to do is to add a toolbar 'group' if you wanted a new 'tab' in JomSocial toolbar menu. Here is the list of functions available in CToolbar library:
/**
 * Function to add new toolbar group.
 * param - key : string - the key of the group
 *       - caption : string - the label of the group name
 *       - link	: string - the url that link to the page
 */
function addGroup($key, $caption='', $link=''){}
 
 
 
 
/**
 * Function used to remove toolbar group and its associated menu items.
 * param - key : string - the key of the group
 */
function removeGroup($key){}
 
 
 
 
/**
 * Function to add new toolbar menu items.
 * param - groupKey : string - the key of the group
 *       - itemKey : string - the unique key of the menu item 
 *       - caption : string - the label of the menu item name
 *       - link	: string - the url that link to the page
 *       - order : string - display sequence : append | prepend	
 *       - isScriptCall : boolean - to indicate whether this is a javascript function or is a anchor link.
 *       - hasSeparator : boolean - to indicate whether this item should use the class 'seperator' from JomSocial.	 	  
 */
function addItem($groupKey, $itemKey, $caption='', $link='', $order='append', $isScriptCall=false, $hasSeparator=false){}
 
 
 
 
/**
 * Function used to remove toolbar menu item
 * param - groupKey : string - the key of the group
 *       - itemKey : string - the unique key of the menu item
 */
function removeItem($groupKey, $itemKey){}
 
 
 
 
/**
 * Function used to return html anchor link
 * param  - string - toolbar group key	
 *        - string - order of the items	 	 
 * return - string - html anchor links	 
 */	 	
function getMenuItems($groupKey, $order){}
 
 
 
 
/**
 *	Function to retrieve those toolbar that user custom add.
 *	return - an array of objects.	 
 */	
function getExtraToolbars(){}
 
 
 
 
/**
 * Function to retrieve custom toolbar menu items to caller
 * param - groupKey : string - the key of the group 
 * return array of object
 */
function getToolbarItems($groupKey){}
 
 
 
 
/**
 * Function used to determined whether a core menu group was set.
 * param  - string - toolbar group key
 * return - boolean	 
 */	 	 	
function hasToolBarGroup($groupKey){}
 
 
 
 
/**
 * Function to get the current viewing page, the toolbar group key.
 * param  - string - uri of the current view page	 	  
 * return - string	 
 */
function getActiveToolBarGroup($uri){}
 
 
 
 
/**
 * Function used to return all the toolbar group keys. 	  
 * return - array	 
 */	
function getToolBarGroupKey(){}
 
 
 
 
/**
 * Function to get the toolbar group key based on what view being associated.
 * param  - string - view name	 	  
 * return - string
 */	
function getGroupActiveView($viewName){}
 
 
 
 
/**
 * Function to add views that associated with the toolbar group.
 * param  - string - group key
 * param  - string - view name
 */
function addGroupActiveView($groupkey, $viewName){}


Adding new 'toolbar' and toolbar's menu items

Below statement is how we can add new toolbar, or, preferable 'tab', into jomsocial.

$toolbar->addGroup('MYBLOG', 'MyBlog', JRoute::_('index.php?option=com_myblog&task=adminhome&Itemid='.$myblogItemId));


Here is the function defination of addGroup:

function addGroup($key, $caption='', $link=''){}
 
$key     - The unique key used.
$caption - The label caption of your tab.
$link    - The url link.


If your menu link is point to outside of JomSocial, you should use JRoute::_() instead of CRoute::_(). Also, you must add the group follow by the group's items otherwise all your item will not be shown in JomSocial toolbar menu.

$toolbar->addItem('MYBLOG', 'MYBLOG_VIEW', 'View Your Blog', 
	JRoute::_('index.php?option=com_myblog&blogger='.$userName.'&Itemid='.$myblogItemId), 'prepend');
 
$toolbar->addItem('MYBLOG', 'MYBLOG_ALL', 'All Blog Entries', 
	JRoute::_('index.php?option=com_myblog&Itemid='.$myblogItemId), 'append');


Above is how you add menu items into your own toolbar tab. addItem works almost the same as addGroup but with few extra parameters with the following order.

function addItem($groupKey, $itemKey, $caption='', $link='', $order='append', $isScriptCall=false, $hasSeparator=false){}
 
$groupKey     - The key used in your custom toolbar menu. In this case is the 'MYBLOG'
$itemKey      - The unique key used in your menu items.
$caption      - The label caption of the menu item.
$link         - The url link.
$order	      - The order of the menu item. Possible value ( 'prepend','append' ). Default is 'append'
$isScriptCall - To indicate whether this is a javascript function or is a anchor link.
$hasSeparator - To indicate whether this item should use the class 'seperator' from JomSocial.


Below is the example on how you can call a javascript function from the link.

$writeUrl	= 'myAzrulShowWindow(\''.JURI::root().'index.php?option=com_myblog'
                . '&tmpl=component&task=write&keepThis=true&TB_iframe=true&no_html=1&id=0\')';
 
$toolbar->addItem('MYBLOG', 'MYBLOG_WRITE', 'Write Blog', $writeUrl, '', true);


Ctoolbar image01.jpg

Above is the example of JomSocial custom toolbar menu 'MyBlog'.

Add extra menu into exisiting JomSocial toolbar

In some circumstances, we need to add extra menu items into JomSocial existing toolbar menu. CToolbar allow you to achieve that. Below is the existing constant / predefined toolbars that are available by default.

TOOLBAR_HOME	- Home toolbar
TOOLBAR_PROFILE - Profile toolbar
TOOLBAR_FRIEND  - Friend toolbar
TOOLBAR_APP     - Application toolbar
TOOLBAR_INBOX   - Inbox toolbar


The example below will demonstrate how you add 'Logout' menu item into 'Home' toolbar.

function onSystemStart()
{
   if(! class_exists('CFactory'))
   {
      require_once( JPATH_ROOT . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'core.php');
   }
 
   //initialize the toolbar object	
   $toolbar	=& CFactory::getToolbar();
 
   $toolbar->addItem(TOOLBAR_HOME, 'HOME_LOGOUT', 'Logout', CRoute::_('index.php?option=com_user&view=login'));
}


Calling the same method addItem, you now added the 'Logout' menu item.

Ctoolbar image02.jpg

Removing core menu group or core menu items from JomSocial toolbar

Ctoolbar library actually allow you to remove any core menu items or even removing the core menu group completely from showing. To remove a core menu group from JomSocial toolbar, we use function removeGroup().

$toolbar->removeGroup(TOOLBAR_INBOX);


If you just want to remove one or some of the core menu items, then you should use this function removeItem() instead. By giving the correct menu group key and menu item key, you can remove any of the core menu items from JomSocial.

$toolbar->removeItem(TOOLBAR_INBOX, 'INBOX_INBOX');


Here is the key string that used in JomSocial toolbar menu items.

Profile
 
'PROFILE_AVATAR'       - Change profile picture
'PROFILE_EDIT_PROFILE' - Edit Profile	
'PROFILE_EDIT_DETAILS' - Edit Details
'PROFILE_EDIT_PRIVACY' - Privacy
 
Friends
 
'FRIEND_SHOW_ALL_FRIENDS'       - Show all
'FRIEND_SEARCH_FRIENDS'         - Search
'FRIEND_ADVANCE_SEARCH_FRIENDS' - Advanced Search
'FRIEND_INVITE_FRIENDS'         - Invite Friends
'FRIEND_REQUEST_SENT'           - Request sent
'FRIEND_PENDING_APPROVAL'       - Pending my approval
 
Application
 
'APP_EDIT_APPS'   - My Applications
'APP_BROWSE_APPS' - Browse
'APP_GROUP'       - Groups
'APP_PHOTOS'      - Photos
'APP_VIDEOS'      - Videos
 
Inbox
 
'INBOX_INBOX'  - Inbox
'INBOX_SENT'   - Sent
'INBOX_WRITE'  - Write