ROXORITY

Lately we received a number of feature requests that could all be addressed by a single feature we've been meaning to add for quite some time, so we finally implemented it for the 1.9 release of PeopleZen: Customizable Data Field Templates.

Simply put, this gives you an easy tool that lets you fully redefine how PeopleZen displays or transforms certain user information, which is typically returned in rather raw form by your Data Source and may not be ready for human consumption as is.

PeopleZen has since its inception for many a common User Profile Property adopted "the most meaningful or usable way to display it", based on hard-coded heuristics driven initially by educated guesses and then increasingly by user feedback:

• multi-valued properties are displayed comma-separated (but this is configurable)
• email addresses are typically displayed as hyperlinks
• date/time values are slightly re-formatted
• all other information is displayed as plain text

But even if PeopleZen gets 90% of your needs right, out of the box, sometimes your users require more sophistication unique enough to your organization that we cannot simply hard-code it into the tool for everyone. Instead, with the new Custom Data Field Templates feature you can easily define your custom property display logic yourself — without having to struggle with messy XSLT.

Because this feature is so flexible, we will walk you through three real-world scenario of our users (anonymized) and how this new feature lets them implement their requirements:

Scenario 1: a better Manager field

Real-world user request:

I'm showing Manager as a column in my newest iteration. I'd like to display that as a clickable link to the manager's profile page (just like the main link in the far left column). Can I do that and at the same time show the person name rather than account name?

So by default the Manager user profile property stores just the account name / domain login name (ie. in the yourdomain\user123 pattern). Instead, this PeopleZen user wants to:

1. show the real name (in a Farm User Profiles Data Source, this would be the PreferredName user profile property)
2. and link it to the manager's profile page

Here are the steps to achieve this:

• go to Site Settings / PeopleZen Studio / Data Field Templates and add a new Data Field Template. If you do not have any yet, simply use the form readily shown to add one:
  • Name: ShowManager
  • Content mode: HTML source code
  • Template content: <a href="{UserProfiles_PropertyValue;#AccountName;#[Manager];#rox___pu}">{UserProfiles_PropertyValue;#AccountName;#[Manager];#PreferredName}</a>
• after saving this, replace your previous, unsatisfactory Manager field (in the User Profile Properties section of your PeopleZen Web Part's settings tool pane, and/or in the Default Data Fields setting on the Data Fields tab of your Data Source under Site Settings / PeopleZen Studio / Data Sources) with the following line:
  • {ShowManager}:Manager

The part after the colon is simply the display name of your field as shown to end users. The part before the colon, where you would typically specify a Data Source field, now instead references your own Data Field Template which you called ShowManager.

Inside this template, we used a similar (but a tad more complex) {placeholder syntax} to:

• obtain both the PreferredName of the manager for the display text inside the <a> hyperlink
• obtain for the <a href> attribute the profile page URL for which the special built-in field name rox___pu is used (which points back to the Link URL data field/s setting on the Data Source's Data Fields tab)

Inside your template you could use the same {placeholder syntax} to "call" any of your other Data Field Templates, if you have more than one. In fact this is precisely what is happening here -- a call to "another template" -- only you have never defined a template named UserProfiles_PropertyValue before, instead it is already built into PeopleZen and is simply a "predefined template" performing some very specific logic. In the above examples, when invoking the UserProfiles_PropertyValue template, it requires and is given three values:

1. the User Profile Property to match with the next (2nd) given value. That property is AccountName for Farm User Profiles Data Sources.
2. the value to obtain the User Profile to use for the next (3rd) given value. We pass [Manager] so now the template knows: pick the user profile whose AccountName is the Manager field of the current user profile.
3. the property value to obtain from the fetched user profile. In this case, we want to show the PreferredName inside the link and for its URL, the rox___pu user profile page link.

All values given to a template are separated from each other and from the template name with SharePoint's ubiquitous ;# separator. So this is how you end up with an initially scary-looking, but ultimately very simple definition such as {UserProfiles_PropertyValue;#AccountName;#[Manager];#PreferredName}...

Scenario 2: display a field value but linked to a custom-composed dynamic URL

The next scenario is pretty similar in kind:

We need a special formatting for a certain Data Field in the rendered PeopleZen Web Part: <a href="http://roxority.com/ats/pages.aspx?param2=CurrentlyLoggedOnUser">datafieldValue</a> — is it possible to render a Data Field as a hyperlink exactly like in that example? All values in the column should have that rendering format. The currently logged-on user is also needed!

The steps are almost identical to scenario #1 above but let's walk through them again:

• go to Site Settings / PeopleZen Studio / Data Field Templates and add a new Data Field Template. If you do not have any yet, simply use the form readily shown to add one:
  • Name: CustomLink
  • Content mode: HTML source code
  • Template content: <a href="http://roxority.com/ats/pages.aspx?param2={UserProfiles_CurrentUser}"&gt;[Department]&lt;/a&gt;
• after saving this, add your custom linked field to your user profile lists (via the User Profile Properties section of your PeopleZen Web Part's settings tool pane, and/or in the Default Data Fields setting on the Data Fields tab of your Data Source under Site Settings / PeopleZen Studio / Data Sources) with the following line:
  • {CustomLink}:Field Title
    

The part after the colon is simply the display name of your field as shown to end users. The part before the colon, where you would typically specify a Data Source field, now instead references your own Data Field Template which you called CustomLink.

Inside this template, we used a similar {placeholder syntax} to obtain the acount name of the current calling SharePoint user via the special, built-in "template" {UserProfiles_CurrentUser}. Note that the use of [Department] is just an example, this user probably wanted to show another User Profile Property but didn't tell us which. So replace [Department] with another know User Profile Property as required.

Scenario 3: Date/Time conversions

Real-world user request:

Our date of birth and hire date are entered into AD as Long Integers (ie. 122918688000000000 for 7/6/1990). Is there a way in PeopleZen to convert these to "human readable" dates?

Here you do not even really need to define your own custom Data Field Template. Simply replace your

• SPS-Birthday:Birthday (or SPS-HireDate:Hire Date etc.)

or similar line (via the User Profile Properties section of your PeopleZen Web Part's settings tool pane, and/or in the Default Data Fields setting on the Data Fields tab of your Data Source under Site Settings / PeopleZen Studio / Data Sources) with any one of the following:

• {DateTime_FromBinary;#[SPS-Birthday]}:Birthday
• {DateTime_FromFileTime;#[SPS-Birthday]}:Birthday
• {DateTime_FromFileTimeUtc;#[SPS-Birthday]}:Birthday
• {DateTime_FromTicks;#[SPS-Birthday]}:Birthday

These are simply different conversion functions for long integer representations of date/time values. Try them all if you're not sure which long format your Data Source's date/time values are in fact using.