Author Topic: Questions: Building a Continued Professional Development Extension (Read 2614 times)

awasson · December 02, 2012, 10:37:09 pm

Hi all,

I am working on an extension to add "Continued Professional Development" tracking/reporting to civiCRM. I'm calling the extension civiCPD and referring to continued professional development as CPD although I could very easily be persuaded to use CPL for continued professional learning if there was enough interest

Preamble: I work with professional organizations and I've decided to use civiCRM as the platform/tool for their membership management. One thing I have found is that all of the organizations I work with require that their members follow some sort of CPD obligation where they do various activities throughout the year and track/report them as part of their continued membership requirement. This page on the wiki has a better description of what it's all about.

I'm using the (excellent) civix tool to stub out the extension module I'm building and have some specific questions in a few areas I'm getting hung up with.

1) I've added code to the my-module-name.php file so that it creates a link to the CPD administration page in the main civiCRM navigation as follows:

Code: [Select]

/**
 * Implementation of hook_civicrm_navigationMenu
 *
 * @param $params array(string)
 */
function my-module-name_civicrm_navigationMenu( &$params ) {
  // get the maximum key of $params
  $maxKey = ( max( array_keys($params) ) );
  $params[$maxKey+1] = array (
    'attributes' => array (
      'label' => 'CiviCPD',
      'name' => 'CiviCPD',
      'url' => 'civicrm/cpd',
      'permission' => 'administer CiviCRM',
      'operator' => null,
      'separator' => null,
      'parentID' => 2,
      'navID' => $maxKey+1,
      'active' => 1
    )
  );
}

That code puts the civiCPD link at the end of the civCRM navigation bar but I'd like to add it into civiCRM's Administer menu somewhere around the links for civiContribute, civiMember, etc... Is that possible? It's not a deal breaker but it would be nice to give it a more cohesive fit with civiCRM.

2) I have a reporting page that once complete will be a place for contacts to log and report their CPD activities. I'd like to have it accessible from the "My Contact Dashboard" page with a heading of "Your CDP Credits" and then a line with the current total number of credits and a link to the detailed reporting page. WHat hooks to I grab/alter to influence the Contact Dashboard?

3) I'll need some way to control who has the ability/obligation to log and report CPD activities... My reasoning is that it should be available to groups and/or members but I'm open to any ideas about how to best control access to it.

I think that covers it for now... I have more questions about how best to present forms for inputting and how to run queries against the database for logging and reporting but I'll come back for those once I have these areas handled.

Thanks for any direction and if anyone wants to help out with the development of the extension I'm happy to share what I'm working on. I've built systems like this from scratch and it is not very complex; I just don't know all the ins/outs with civiCRM's hooks and extension development.

Andrew

Michael McAndrew · December 03, 2012, 06:08:50 am

Hey there,

Try experimenting with the

Quote

$maxKey = ( max( array_keys($params) ) );

line. I suspect it uses that for weight.

You could also try printing out the array and seeing what that looks like / how you could manipulate it.

http://wiki.civicrm.org/confluence/display/CRMDOC42/Hook+Reference#HookReference-hook_civicrm_dashboard might be the hook you need for the dashboard - that page in general is quite useful.

Have you also seen / come across this: http://civicrm.org/blogs/andrewtombszingitorguk/civihr-0

NASACT · December 03, 2012, 08:01:22 am

Hi, I am highly interested in this as I was getting ready to do this by custom data attached to an event. I might suggest CPE as Continuing Professional Education is often what they call the credits from my experience. Let me know if I can help with testing or workflow.

awasson · December 04, 2012, 11:48:19 pm

Quote from: Michael McAndrew on December 03, 2012, 06:08:50 am

Hey there,

Try experimenting with the
Quote
$maxKey = ( max( array_keys($params) ) );
line. I suspect it uses that for weight.

You could also try printing out the array and seeing what that looks like / how you could manipulate it.

http://wiki.civicrm.org/confluence/display/CRMDOC42/Hook+Reference#HookReference-hook_civicrm_dashboard might be the hook you need for the dashboard - that page in general is quite useful.

Have you also seen / come across this: http://civicrm.org/blogs/andrewtombszingitorguk/civihr-0

Michael,

Thanks for pointing me to those reference hooks... Super helpful stuff. I'm still looking for a method to put information in the "My Contact Dashboard". That reference shows how to add content to the main civiCRM dashboard page which is quite cool and I found a hook to add a 'Tab' to the "Contact Record" which will be very handy too. If you have any other tips or references for hooks, please send them my way and thanks again!

Quote from: NASACT on December 03, 2012, 08:01:22 am

Hi, I am highly interested in this as I was getting ready to do this by custom data attached to an event. I might suggest CPE as Continuing Professional Education is often what they call the credits from my experience. Let me know if I can help with testing or workflow.

Thanks, I'll keep you posted and let you know when I have something to test out.

Michael McAndrew · December 05, 2012, 03:21:05 am

Quote

I'm still looking for a method to put information in the "My Contact Dashboard".

for clarity, can u post the URL of the page that you want to add to?

You can add things to the /civicrm home page (as I like to call it) by defining your own dashlets as well, though it might involed some adding stuff to the directly to the db - it did last time i looked.

Quote

That reference shows how to add content to the main civiCRM dashboard page which is quite cool and I found a hook to add a 'Tab' to the "Contact Record" which will be very handy too. If you have any other tips or references for hooks, please send them my way and thanks again!

I am pretty sure that that is the exhaustive list of hooks so if you can't see it there, it probably doesn't exist / you'll need to create it

awasson · December 05, 2012, 09:39:29 am

Hello Michael,

Regarding the Contact Dashboard, I'm looking to add to the page that can be found here: /civicrm/user?reset=1&id=1

Every contact has one and it's a perfect place to put pertinent information like membership status, groups and for the purposes of this extension, Continuing Ed status so that they can review their totals and then click a link to add/edit their activities from a page that will be provided by the extension.

Thanks,
Andrew

Donald Lobo · December 05, 2012, 01:28:50 pm

you can add / remove stuff from the page via the pageRun hook and customized templates and/or via the "region" functionality (my preferred method currently)

http://wiki.civicrm.org/confluence/display/CRMDOC42/Region+Reference

we've just started adding crmRegion sections to various tpl files, so please do annotate the tpl files that you need and file an issue / patch so we can commit the changes

lobo

awasson · December 05, 2012, 02:56:40 pm

Thanks Lobo,

I read something about regions a while ago and it does sound like a very good way to inject content. I'll do some more digging.

Andrew

awasson · December 05, 2012, 11:51:31 pm

So I'm tinkering away at my extension thinking to myself "I wonder why Lobo is so keen about Regions when it's pretty simple to just crank out a custom template... Oh what the heck, I'll just create a new template for the My Contact Dashboard and be done with it" when it hit me that other than being a cheesy way out, the real reason it's a bad idea is that competing extensions could disable each others templates.

So with that in mind, I will be using regions and I will annotate the tpl files that I need and file an issue / patch so you can commit the changes.

Cheers,
Andrew

Donald Lobo · December 06, 2012, 09:55:12 am

The other super big reason in my mind is that:

adding region specific templates affects only a small part of the template and is incremental. thus changes are more likely to survive without modification as we tweak and improve on various templates

for customized templates, u need to check and port your upgrades for every major version release (and sometime a few minor ones)

lobo

awasson · December 20, 2012, 01:11:41 am

Alright, I'm back...

I'm getting close to having a prototype of this extension done. I won't call it a beta yet because I feel it will need some refining of the MV code but there is a lot of functionality involved so I wanted to get it working first and then I'll refine it so it's more elegantly coded.

Anyway, I am back on the subject of the "my contact dashboard".

I have added my own UserDashboard.tpl file with a region that I can use to populate with an entry about the Continuing Professional Development status and link to the reporting page.

Presently, it is static content in my UserDashboard.tpl: You currently have no CPD credits for this year. Click here to update your CPD activities.

What I would like to do is run the following code and then dynamically populate the information about CPD Credits so that it shows the total number of credits for the year or zero if they have none + the link to the reporting page.

Where do I insert all of this codey goodness within my extension module hierarchy, ie: is there a hook_civicrm_UserDashboard() that I can instantiate in my module_name.php file?

Code: [Select]

       // Find the ID of the person viewing this page 
       $session = CRM_Core_Session::singleton();
       $contact_id = $session->get('userID');
	
        // Find the Year we are interested in and the date to print the report for
        // Default to this year
        $report_year = date("Y");

        // Total credits for the year
       $sql = "SELECT SUM(credits) as total_credits FROM civi_cpd_activities WHERE contact_id = ". $contact_id ." AND EXTRACT(YEAR FROM civi_cpd_activities.credit_date) = " . $report_year;

       $dao = CRM_Core_DAO::executeQuery($sql);
       while( $dao->fetch( ) ) {    
    	   $total_credits = abs($dao->total_credits);
       }
    
       if(isset($total_credits)) {
    	   $this->assign('total_credits', $total_credits);
       } else {
    	   $this->assign('total_credits', 0);
       }

Donald Lobo · December 20, 2012, 08:19:31 am

use hook_civicrm_pageRun

with the pageName as the php class name of the userdashboard

lobo

awasson · December 20, 2012, 11:41:17 am

Ok, this is fantastic. Thanks Lobo!

I'm now using hook_civicrm_pageRun( &$page ) in my extension_name.php file which runs my query and passes a variable to my template which then displays the message

Code: [Select]

function MyExtensionName_civicrm_pageRun( &$page ) {
    
    if($page->getVar('_name')=='CRM_Contact_Page_View_UserDashBoard') {
    
    	// Run my code and wrap the message in a variable: $mcd_cpd_message 

    	$page->assign( 'mcd_cpd_message', $mcd_cpd_message );
    
    }
}

awasson · January 07, 2013, 07:06:49 pm

Hi guys,

I've got my CPD module at a point that I'd like to have it tested out if anyone's interested. I'd like to contribute it back to the civiCRM community but it needs a little fine tuning and I'd like to get some eyes on it to make sure I've got the feature set right. It'll do what the organizations I work with want but it might not for others so I want to make sure it's flexible enough to be useful.

On the admin side
It will currently provide site administrators the ability to select member types to subject to a 'continuing professional development' program which they can create categories for members to report their activities under. It also lets the admin choose the length of time a member has to edit and update their activities. (ie: 1-5 years or any year).

Since naming seems to be a bone of contention, I've added the ability to call it whatever you want. It will default to 'Continued Professional Development' but the admin can name it whatever they like. Once set, the various screens will reflect the new naming convention however the menu item on the civiCRM administration will remain 'civiCPD'.

It also provides for admins to adjust is the ability to assign a field for 'membership number'. All of the organizations I work with have a legacy of years in some system or other and they have their own membership numbers from way back when. I've been using the civicrm_contact.user_unique_id field or the civicrm_contact.external_identifier for this so I've provided the ability to use one of those or the civicrm_membership.id field; whatever suits the organization.

For reporting, admin users can view a full (yearly) report that lists out all members of the types that are associated with the CPD program, ordered by last name with a grand total of CPD credits and the breakdown per category.

* I will be adding a link to the end of each line for admin users to review and edit.

** I will also be adding options to export the report as Excel, CSV, PDF, etc.... Since the reports are outside of civiCRM's report system, I'll be looking at best options to achieve that.

On the Member Side
On the members side, once the module has been activated, it will put a Continued Professional Development item in the 'Contact Dashboard'. If your membership is applicable, it will tell you what your current credit score is and provide a link to your CPD page where you can review, add, edit your CPD activities.

* I will be adjusting the CPD Activity page with a little jQuery to make it more seamless to go from the summary of activities to the details of the activities under categories but that won't affect the mechanics.

TODOs
Other than the items on the full report page, I will need to refactor my model / view code throughout. There are a number of areas in the app where I crammed 'view' code in my model php files because I just wanted to get it working. Now I'll have to go back in and clean those pages up.

Moving Forward
So if anyone wants to give it a test drive, please grab it from my Github (https://github.com/awasson), install it and run it through its paces. Please use the issue queue to log issues so I can keep a concise record of what's going on with it. I'm pretty new to Github, civix and all that goes on with it but my aim is to release and maintain a decent module.

Cheers,
Andrew

CiviCRM Community Forums (archive)

News:

Author Topic: Questions: Building a Continued Professional Development Extension (Read 2614 times)

awasson

Questions: Building a Continued Professional Development Extension

Michael McAndrew

Re: Questions: Building a Continued Professional Development Extension

NASACT

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

Michael McAndrew

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

Donald Lobo

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

Donald Lobo

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

Donald Lobo

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension

awasson

Re: Questions: Building a Continued Professional Development Extension