Joomla! Modules Using CiviCRM API 3

A great thing in CiviCRM v3.4 and v4.0 is that for Joomla! users there is a new helper file that makes it very easy to access the CiviCRM API. That combined with version 3 of the API makes it easier than ever to put CiviCRM data anywhere in your site. I'm going to show you how I made a module that shows the groups a logged in user is a member of. Because it uses the API this can display on any page whether or not it is a CiviCRM page.

A few notes before I start. This is going to be a Joomla! 1.6 module. Also, I did have to make a slight change to administrator/components/com_civicrm/helpers/api.php, changing 
$this->civiInit( );
to
self::civiInit( );
at line 31. Also I'm going to make this module Joomla! style, which means that it can have a layout override or alternative layout.

The helper file has two functions, CiviInit to get all of the CiviCRM settings and configuration information and civiImport which loads specific APIs.

My module is going to be called mod_mycivigroups. As with most Joomla! modules it has some standard files:

• mod_mycivigroups.php
• mod_mycivigroups.xml
• helper.php
• tmpl/default.php
• language/en-GB/en-GB.mod_mycivigroups.ini
• language/en-GB/en-GB.mod_mycivigroups.sys.ini

And of course language files and index.html files in each folder.

The helper is the best place to start:

// no direct access
defined('_JEXEC') or die;

class modMyCivigroupsHelper
{
  // This will get the list of groups the logged in user is a member of.
   function myCiviGroupsGetGroupContacts()
   {
        CivicrmHelperApi::civiimport('api');
        CivicrmHelperApi::civiimport('GroupContact');
        CivicrmHelperApi::civiimport('UFMatch');

        $user =& JFactory::getUser();

               $results = null;
               if (!$user->guest){
                   $userarray = array ('uf_id' => (string) $user->id, 'version' => '3');
       $contact_id = civicrm_api('UFMatch','get',$userarray);

       // We can only get groups for people who have a value for contact_id. 
       if ($contact_id['is_error'] == 0){
         $params = array('contact_id' =>  $contact_id['id'] , 'version' => '3');
          $results = civicrm_api('GroupContact','get', $params);
        }

      }
      return $results;
     }
}

Remembering that Joomla is strongly convention driven, the class takes its name from the module. The function starts by using the functions from the component helper to import the base API, the GroupContact API (which gets a list of groups for a given contact ID), and the  UFMatch API (which gets the contact ID for a given userid from the CMS). 

We can only get the list of groups for users who are logged in so we limit this to people who are not guests.

Reading the API we then make a parameters array of the data the API needs, in this case the user ID and the version  of the API. The API itself always takes three arguments: the API name (entity), the action, and an array of parameters.   Then we use the API wrapper

$contact_id = civicrm_api('UFMatch','get',$userarray);

to get the contact_id. However, we don't only get the contact_id because API v3 always returns an array with the same structure. In this case $contact_id['id'] is the id itself, $contact_id['is_error'] is 0 on success and 1 on failure, and $contact-Id['count'], the number of results, which in this case should be 1 if we find a maching contact.

Next we check to see if there was actually a result using $contact_id['is_error'] and if so, we use the GroupContact API to get the list of groups the contact is a member of.

In this case the $params are just the id and the API version.

Now taking a step back, the mod_mycivigroups.php files consists of:

//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
/**
 * 
 *This assumes contacts and users have been synched so all Joomla! users should have contact_id values. 
 */

//Get the helper and include the files needed for group contact and UF Match

require_once JPATH_ROOT . '/administrator/components/com_civicrm/helpers/api.php';

require_once dirname(__FILE__).'/helper.php';

$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

$results = modMyCiviGroupsHelper::myCiviGroupsGetGroupContacts();

require JModuleHelper::getLayoutPath('mod_mycivigroups', $params->get('layout', 'default'));

Which is a standard Joomla! module file with the addition of 

require_once JPATH_ROOT . '/administrator/components/com_civicrm/helpers/api.php';

and

$results = modMyCiviGroupsHelper::myCiviGroupsGetGroupContacts();

which are similar to what you would see in many modules.

Finally, we take the results and use them in our layout file, default.php (in the tmpl folder).

// no direct access
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>
        <?php   
$user =& JFactory::getUser();

          // You have to be logged in to  show your groups.
          if (!$user->guest):
    // Not in a group so nothing to list.
   if ($results['count'] == 0):
      echo JText::_('No_Groups');
    else:
      $values = array_slice($results['values'], 0, $params->get('number', 5)); ?>
   <?php endif;
          // Really a webmaster probably would use the viewing access level to 
// make sure this isn't needed, but you never know.
          else :
   echo JText::_('Not_Logged_In');
endif;

For people who are logged in, we check the results and if the count was 0, post a message. If the count is more than 0 we make an unordered list of groups up to some maximum number (which is set in the module parameters). You want a maximum since listing say 100 groups is probably going to mess up your page. Finally in case there is not a logged in user we gracefully say something, just in case the webmaster is showing the module to them. 

So now you can show a user's groups on any page. And great for Joomla! users you can do either a template override or (in 1.6) an alternative layout for the module. Which means you can make the HTML whatever you want and do your own CSS easily. 

You can download the complete module from joomlacode.org.

What would be great is to get a whole bunch of ready made modules for common things we would like to display on all pages (such as upcoming events, memberships, campaigns etc.).

$contact_id['count'] != 0.

	else:
	$values = array_slice($results['values'], 0, $params->get('number', 5)); ?>

	   
	     else: 
	   
	 $values = array_slice($results['values'], 0, $params->get('number', 5)); ?>
	    <ul>
	       <?php foreach($values AS $value) : ?>
	       <li> <?php echo $value['title'] ?> </ li>
	        <?php   endforeach; ?>
	       </ul>
	   <?php endif;