Skip to main content

CiviCRM developer secret handshake

I'm at a CiviCRM developer training and have to share my discoveries. Before yesterday, I always felt like a CiviCRM hacker, without really knowing why, and now I think I do. For me, the difference is between knowing a few tricks to accomplish what I want to do, compared with actually understanding the code as a whole and feeling like I could responsibly contribute stuff and not just cross my fingers that I'm not missing something important. So, no, it's not a secret handshake, but here's  what I've learned:

1. Dispatcher and permissions

In Drupal, we have a bunch of code called the "menu system" which takes care of (among other things, like the actual visible menu), how a particular url maps onto a specific piece of code to be executed - i.e. which callback function gets invoked. This mapping of urls to callbacks is implemented by modules in the hook_menu function and stored in a table that gets rebuilt when modules get added and rebuilt or the menu cache gets cleared. This function in Drupal also takes care of the top level of permissioning - i.e. who gets to call which urls.

CiviCRM, because it's CMS agnostic, doesn't use Drupal's menu for it's individual urls, but instead just exposes to Drupal a single callback path "civicrm" and then deals with the dispatching and permissioning itself.

So here's what I learned: the way CiviCRM implements dispatching and permissioning is similar to Drupal, but it's done via xml files rather than implementing a hook. So, dive into the CiviCRM code base, pick your favourite module (e.g. Events) and look in there for xml files. It's got a pretty obvious structure.

2. Module Extensions

CiviCRM now has a thing equivalent to a Drupal module, it's called a Module Extension.

"Equivalent to" is an expression that gets a lot of abuse by sales types, so let me be more specific: in Drupal, there are really three parts to "core", namely:
a) the really core essential stuff that mostly lives in the includes directory + the index.php file.
b) the modules that you can't disable
c) the other modules that are distributed with Drupal
What makes module development work in Drupal is the discipline this structure imposes on the code as a whole - even modules that you can't disable are built with the same tools as modules that you can contribute, the same hooks, etc. So, at least in theory, a contributed module can do things as powerful as the core.

What we get with a Module Extension is access to the same tools and structure that CiviCRM core is built with. Okay, maybe not quite, not yet, but that's the promise and I'm going to hold them to it.

What this means for CiviCRM developers is: your standard tools for customizing CiviCRM look like this:

a. Custom tpl and php directories - difficult to maintain, limited in what it can do and easy to implement, or difficult to go beyond the really basic stuff. In other words, a documented way to hack core. Roughly "equivalent" to using the theme layer in Drupal to do your customizations.

b. Drupal module - use the civicrm api to expose custom callback functions that  access the civicrm code, db, etc. A nice development environment, but also limited in how much it can sensibly accomplish. Also not portable to other CMSs. Feels kind of like throwing rocks, involves some crossing of fingers.

c. The CiviCRM module extension. Can now replace my big hacks that currently use a grab bag of 1. and 2. - makes them more easily shareable across installations and CMSs.

3. Development Tools

Okay, so we've now got access to the same mechanism that builds CiviCRM functionality (with the usual disclaimers), but we're not core developers so we don't know the code base as well. With Drupal we have the api documentation, books and other documentation. We don't have quite the same level of maturity with CiviCRM, but here's what I've found:

a. the api explorer. You get this automatically with your own civicrm installation, it's a bit beta, but a cool interface and has the basics. A real important difference with Drupal is that the actual api code is a separate, thin layer over the actual code, so most of the time you need to look at the core code to figure out arguments.

b. the core code. See it here: http://api.civicrm.org/v3/, it's linked with the warning "code level documentation".

c. the list of hooks. CiviCRM adopted Drupal's hook idea a while ago. See: http://wiki.civicrm.org/confluence/display/CRMDOC42/Hook+Reference

d. Eileen's civicrm_developer module (the civicrm version of the Drupal devel module). I'm going on hearsay from Tim and respect for Eileen's past work, but I doubt you'll be disappointed.

e. Tim's civix. This should almost be first on the list - it's module extension generator. The only non-obvious thing I ran into was that you first create the module extension, then you use a separate subsequent command to add stuff for different types of things you want your module to do. For example, if you just want to use the hooks to intervene on some existing pages, you can just use the basic scaffolding. If you want to create a new url with functionality, then you add in a "page". Yes Tim, it's documented, I just didn't read it carefully.

Conclusion: many thanks to Tim for explaining all this, and to Joe and Louis-Charles for getting this developer training to happen.

Popular posts from this blog

The Tyee: Bricolage and Drupal Integration

The Tyee is a site I've been involved with since 2006 when I wrote the first, 4.7 version of a Drupal module to integrate Drupal content into a static site that was being generated from bricolage. About a year ago, I met with Dawn Buie and Phillip Smith and we mapped out a number of ways to improve the Drupal integration on the site, including upgrading the Drupal to version 5 from 4.7. Various parts of that grand plan have been slowly incorporated into the site, but as of next week, there'll be a big leap forward that coincides with a new design [implemented in Bricolage by David Wheeler who wrote and maintains Bricolage] as well as a new Drupal release of the Bricolage integration module . Plans Application integration is tricky, and my first time round had quite a few issues. Here's a list of the improvements in the latest version: File space separation. Before, Drupal was installed in the apache document root, which is where bricolage was publishing it's co

Refactoring My Backup Process

A couple of weeks ago, I decided to spend a few hours on a Friday afternoon improving my backup process for my Blackfly managed hosting service . Two weeks later, I've published my ongoing work as an update to my backup-rsync project and have decided to share it with you. You might think I'm trying to compete for "least click-bait like title ever", but I'm going to claim this topic and project might be of interest to anyone who likes to think about refactoring , or who is implementing backups for container-based hosting (like mine ). Definition "Backup" is one of those overloaded words in both vernacular and computer-specific use, so I want to start with definitions. Since "a backup" is amongst the least interesting objects (unless it contains what you absolutely need in that moment), I think it's more interesting and useful to define backups functionally, i.e. A "backup process" is a process that 1. provides a degree of insuranc

drupal, engagement, mailing lists, email

I lived, worked and studied in Costa Rica from 1984 to 1989. Ostensibly, I was there to study Mathematics at the University, and indeed I graduated with an MSc. in Mathematics supervised by Ricardo Estrada (check that page, he even advertises me as one of his past students). And yes, I do have a nine page thesis that I wrote and defended in Spanish somewhere in my files, on a proof and extension of one of Ramanujan's theories. But mathematics is a pretty lonely endeavour, and what drew me back to Central America (after the first visit, which was more of an accident), was the life and politics. The time I lived there was extremely interesting (for me as an outsider, though also painful and tragic for it's inhabitants) because of the various wars that were largely fuelled by US regional hegemonic interests (of the usual corporate suspects and individuals) and neglect (of the politicians and public) - the Contra war in Nicaragua, the full-scale guerrilla wars in El Salvador and