Getting started with new Name and Greetings features in 4.5

2014-09-17 15:24
Written by

With CiviCRM 4.5 around the corner, it's time to talk about one of the great new features in this release: improved handling of non-English names and greetings!

This goes back quite a bit: I posted the original plan (as linked above) in July 2013. There was little feedback, so I concluded we are on the right track (nobody complained, so it must have been good! ;-) ), and implemented it over the course of that summer. At the unforgettable Dalesbrige sprint, I added some documentation; and the code was finally merged as the very first feature for CiviCRM 4.5! (The sprints are magical: between playing hacky sack and darts, wandering the breathtaking peaks and beautiful countryside, and generally having a wonderful time, we still managed to do quite some work :-) )

Now that 4.5 is finally nearing a stable release, and by now surely everyone has a beta version running in their testing environment (haven't you? ;-) ), it's a good time to get familiar with the new possibilities offered. Most of the name/greetings changes are probably not relevant for organisation is English-speaking countries; if however your organisation is located elsewhere (such as most of Continental Europe), read on! :-)

First off, the actual name fields. At Administer » Customize Data and Screens » Display Preferences, in the Editing Contacts section, you can now select which name fields show up in the input forms for Individual contacts (both on the dedicated Contact Edit form, and the inline form activated when clicking the contact name on the Contact Overview pane) -- now is your chance to get rid of those pesky Middle Name or Suffix fields that are just in the way all the time! ;-) (Well, at least in Germany, these fields are not commonly used...)

Perhaps (yet) more importantly, there is a new Formal Title field you can activate here. This is a free-text input field that shows up in the input forms after the prefix, but before the first name; to be used for academic titles, professional titles etc. (E.g. 'Prof.', 'Dr.', 'RA'.) This field is disabled by default, to not interfere with the "traditional" US-centric default behaviour; but if you are in Germany (and I guess many other parts of the world as well), you most definitely want to enable this.

If you have been using a custom field for the title so far, you can directly migrate the values to the new standard field, and drop the custom field. This is probably most easily achieved by exporting the old custom title field value of all Individual contacts along with their Contact ID, and importing into the new standard Formal Title field.

Some German organisations have been (mis)using the otherwise unneeded Suffix field for the title instead. This can be easily migrated using the aforementioned method as well: although the Suffix field is an option select field rather than free-text, this should not matter when doing the export, as the textual representation of the value is exported.

In lack of a more appropriate solution, also some organisations have been misusing the Prefix field. While this might seem the most natural approach at first -- like the title, the Prefix field shows up in front of the name -- this is actually the least fortunate possible workaround, as it interferes with the intended use of the Prefix field as a gender-specific prefix. ("Anrede" in German.) In this case, after migrating the titles to the new field (but careful not to include any actual gender prefixes that might also have been in there!), the Prefix field needs to be restored (at Administer » Customize Data and Screens » Dropdown Options » Individual Prefixes (Ms, Mr...)) to only offer a choice of the proper equivalents of the 'Mr.' and 'Ms.' prefixes (e.g. 'Herr' and 'Frau'), and then populated with the proper values for all Individual contacts missing it. (Possibly derived from the Gender field values in the Demographic Data tab, if present.)

Along with configuring the input fields in use, of course we also want to change the fields in the name display format accordingly. This is done by editing the Individual Display Name Format template (also at Administer » Customize Data and Screens » Display Preferences), which affects pretty much all places where contact names are shown in the UI. For German organisations, the template should usually look like this:

{contact.individual_prefix} {contact.formal_title} {contact.first_name} {contact.last_name}

(You can also include {contact.individual_suffix} at the end, if you are using the Suffix field for some reason.)

Now let's get to the tricky fun part: handling of greeting and addressee tokens!

As you probably know, the idea here is that for every contact, CiviCRM automatically generates appropriate postal greeting, email greeting, and addressee tokens, which can be used for mass mailings by including them in the mailing templates. (Or alternatively exporting along with the other relevant data for use in external mailing tools.) The appropriate texts of course vary between organisations and countries, and thus the templates for constructing these tokens can be customised. (At Administer » Communications » Email Greeting Formats etc.)

Now if you are an organisation using CiviCRM in Germany (or perhaps another non-English country), you quite possibly have two variants for each greeting: male and female. Or maybe you have not been using the greeting tokens at all: needing to select between male and female variants for every single contact is just too much hassle... And doesn't work at all when people are entering their own contact data through public forms.

Another new feature in CiviCRM 4.5 comes to our rescue: it's now possible to use Smarty syntax in the greetings (and addressee) templates. This enables using a conditionals to automatically generate the right variant, based (typically) on the value of the Prefix field. So for a typical German informal greeting for example, use a template looking like this:

{capture assign=prefix}{contact.individual_prefix}{/capture}{if $prefix=="Frau"}Liebe{else}Lieber{/if} {contact.first_name}

Or if you have some contacts with no Prefix set, you can use this slightly more complex variant which catches these cases as well:

{capture assign=prefix}{contact.individual_prefix}{/capture}{if $prefix=="Frau"}Liebe{elseif $prefix=="Herr"}Lieber{else}Liebe/r{/if} {contact.first_name}

Set this as the default email and/or postal greeting template, and from now on every newly created contact (either through the back-office or through self-service forms) will automatically get the right greetings :-)

Here are some other possible variants for reference. For a (half-)formal German greeting use one of these:

{capture assign=prefix}{contact.individual_prefix}{/capture}{if $prefix=="Frau"}Liebe{else}Lieber{/if} {$prefix} {contact.formal_title} {contact.last_name}
{capture assign=prefix}{contact.individual_prefix}{/capture}{if $prefix=="Frau"}Liebe Frau{elseif $prefix=="Herr"}Lieber Herr{else}Liebe/r Herr oder Frau{/if}{contact.formal_title} {contact.last_name}

Or for a traditional very formal greeting try these:

{capture assign=prefix}{contact.individual_prefix}{/capture}Sehr {if $prefix=="Frau"}geehrte{else}geehrter{/if} {$prefix} {contact.formal_title} {contact.last_name}
{capture assign=prefix}{contact.individual_prefix}{/capture}Sehr {if $prefix=="Frau"}geehrte Frau{elseif $prefix=="Herr"}geehrter Herr{else}geehrte/r Herr oder Frau{/if} {contact.formal_title} {contact.last_name}

Other regions/languages needing a gender distinction should be able to use similar conditionals.

The addressee on the other hand remains simple, as it doesn't really need conditionals (at least in Germany):

{contact.formal_title} {contact.first_name} {contact.last_name}

Note that this doesn't include the Prefix. While this is traditionally included as part of the address in Germany, it's not part of the addressee, but rather printed on a separate line before the addressee.

(I for my part don't think it's necessary to include it at all. It certainly doesn't help the postal service; and I doubt any recipient will get offended if it's missing... Indeed I didn't even notice this tradition until recently.)

In all of these forms, we just include the Title field literally. This is not always entirely correct: some complex titles traditionally undergo various abbreviations and/or replacements, which differ between use in the postal address and use in a greeting. We could write an extension that provides a pair of special Smarty functions for doing these conversions... However, I don't think this would really be worth the effort, as these cases are not terribly common -- for the few you are likely to encounter, you can just enter the right texts by hand. (Plus, I very much doubt other IT systems handle these cases correctly either...)

A further complication applies for organisations wanting to address some of their contacts in a different style, such as formal vs. informal. In English-speaking countries, you just need to use a different greeting template and that's it; but in Germany for example, we also have to adjust various pronouns in the mail body -- either dividing the contacts into two groups and sending them separate mailings with different templates; or (preferably) using a single mailing with conditionals in the template.

Either way, we need to know which formality level is in use for each particular contact. In some cases, this could be derived from the greeting form -- but this is not always possible, and never elegant. Thus some organisations have added a separate (custom) field. With CiviCRM 4.5, there is a new dedicated core field (in the Communication Preferences block) for handling this: Communication Style.

The values offered are 'Formal' and 'Informal'. If that doesn't suit your organisation's needs, you can customise the available option values (and which one is selected as default for new contacts) at Administer » Communications » Communication Style Options. If you have no use for this field and it's only in the way, you can also delete all option values, which will suppress displaying of the field entirely.

Now of course setting the explicit Communication Style in addition to the appropriate greeting variant(s) would be redundant. Thus, the right approach is instead to use an even more complex default template, with another conditional for the Communication Style:

{capture assign=c}{contact.communication_style}{/capture}{capture assign=p}{contact.individual_prefix}{/capture}{if $p=="Frau"}Liebe{else}Lieber{/if} {if $c=="Familiar"}{contact.first_name}{else}{$p} {contact.formal_title} {contact.last_name}{/if}

Having that, you only ever need to explicitly select a different greeting template for special cases.

Note that if you already have appropriate greetings with the right gender and style set for your existing contacts, it's not imperative to migrate these to the new automatic template -- you could just leave them as is, and use the new template only for newly entered contacts. This of course is somewhat unelegant; and also slightly more work if you ever decide to change your greeting texts. On the other hand, migration might be a bit tricky: you have to find and export all contacts where the new default template applies (i.e. no special form was selected before), and then import them in just the right way so they get the new template -- I heard there are some quirks with greetings import...

Speaking of quirks, there is one major limitation to the new complex templates (which becomes most pronounced with the last example): the templates are (still) stored in the Label field of the option values. This bears a number of problems: for one, the template code has to be entered without any line breaks in a single-line side-scrolling input field. This is OK when copy-and-pasting a pre-made template; but any manual changes become rather painful. Also, the entire template code shows up in the select drop-down... Oh the ugly!

But most importantly, the Label field is limited to 255 characters in length, which severely restricts the use of complex conditionals -- the last example just barely fits; anything more advanced (such as handling missing Prefix values for example) won't :-(

I had hoped that I'd manage to address this shortcoming before the new functionality gets released in CiviCRM 4.5... But then there was SEPA. Well, let's hope for 4.6 :-)

(For the curious kind: my thinking is instead to store the templates in the Description field going forward. This is slightly non-trivial of course, as it will require adjustments to the existing greetings handling code in various places...)

Click thumbs up if you thought this blog post was useful (login to vote or to comment)


Thanks for the extensive writeup. Thought you might be interested to know that I've added support for this new feature to webform-civicrm integration as well :)

This looks very well thought out. One question I have is how you plan to deal with greetings for couples/spouses.   I previously shared code and blogged about the issue for properly addressing a couple at:

My code is US-centric, but I thought it could be expanded on for other laguagues as needed. (I am in process of re-packaging my code as a native extension, which will be published on soon)

The main issues I run into is the level of formality depends entirely on context, not a static preference of a contact. For example if the end-user is using CiviCRM to send invitations to picnic at a local park, they will use very a casual greeting. If they are sending invitiations to an annual dinner dance, they will use as much formality as possible.   Hence in the code I shared, the user can choose among various mail merge tokens that run the range from casual to formal, and in between. 

The issues with couples is more complex, as it depends on so many factors: Does the couple share a last name or not, are they the same gender as each other, or different genders, does either person (or both) have a professional title such as Dr.  Or can a courtesy title be derived from their gender alone? ie "Mr" or "Ms"  Are there any special situations, such as for a widow, etc.  Even with a couple, sometimes I need to invite both of them. Other times I am only inviting one person, such as for a Women's social group.

I would like your input on how I can make my code less US-centric.



Interesting point about context-dependant greetings. While we haven't run into this so far (AFAIK), I tend to think of "email greeting" as a less formal variant, and "postal greeting" as a more formal one. Apart from possible confusion, there is really nothing to prevent using either one for any type of communication... Of course this only works as long as you do not need more than two context-dependant formality levels :-)

As for couples, these are generally a relatively rare occurence at the organisations we are involved with. Not sure whether it depends on the type of organisation, or whether it's more of a US-vs.-Germany cultural difference... At any rate, I tend to think automatic handling would be overkill for us. Rather, we simply use a very generic default greeting for households (appropriate for addressing pretty much any group of people), and manually set different greetings where desired.

So no actual input on internationalisation of your extension from me... Sorry to disappoint you ;-)

Very helpful:

I miss wildcards, something like this:
{if $contact.formal_title|strstr 'Prof'}
Sehr geehrte Frau Professorin {$contact.last_name},
Why? Because there may be "Prof.", "Prof. Dr.", "Prof. rer. sc." and "Prof. Dr. Dr." in the database, but all of them are called "Professor" (m) or "Professorin" (f) in German formal greetings.