A while back, Atlas added the ability for users to add personal pronouns to their user profile. You can read about this enhancement in Atlas Proudly Adds Pronouns Option to Profile.

Today, we take a technical dive into how we added a Pronouns field on the Atlas user profile and registration page using a custom field setting and a custom component.

Note: Customizations in your community might conflict with the implementation that we describe in this article. For example, if your community has removed the "Personal Information" tab in My Settings > Personal, you will not be able to add the pronouns to the Personal Information tab exactly as described here.

• Pronoun field on the User Registration page
• Pronoun field in the Personal Information tab
• Customization overview
• Create your Support ticket
• Create a redirect component
• Update attribute mappings in Community Admin (SSO-only)
• Use pronouns in customizations

Pronoun field on the User Registration page

Here is how the Pronoun field appears on the User Registration page.

Pronoun field in the Personal Information tab

Here is how the Pronoun field appears on the Personal Information tab under My Settings > Personal. We created a custom component to add an Update who can see your private info link under the field that redirects the user to the My Settings > Preferences > Privacy page to modify their pronoun privacy preference. We show the code for this link in Create a redirect component.

Note: If your community had the Personal Information section removed from My Settings > Personal, you will need to consider asking Support to restore the Personal Information tab with just the Pronoun field or implement some other method for users to edit their personal pronouns through the community user interface.

Customization overview

Let's take a quick look at the customization as it was implemented on Atlas. You'll need Khoros Support to perform some back-end tasks and you'll also need to build a simple custom component.

Important: Our implementation uses a non-SSO registration flow. If you're interested in trying this customization in an SSO community, be sure to read the next section for caveats and considerations.

Developer/Community Manager tasks:

• Create a custom component that creates a redirect link to the user's Privacy Settings page so that they can control who can see their personal pronouns.
• File a Support ticket requesting back-end configurations

Khoros Support tasks:

• Create a custom field setting where users can enter and modify their personal pronouns.
• Add the new field to the required page forms.

Once the custom field is in place, you'll be able to access it via the Community REST API in FreeMarker customizations.

NOTE TO KHOROS SUPPORT STAFF: See Add a custom pronoun field setting to the user profile for instructions relating to these enablement and configuration tasks.

 

SSO considerations

This section applies only to customers using SSO. If you are using Khoros Community's out-of-the-box Authentication feature you can ignore this section.

If your company already stores pronoun data (outside of Community) and wants to pass the pronoun data through SSO, the implementation differs depending on which method of SSO you use.

Methods that require a Services engagement will need to be scoped for cost.

SSO Method	Who Implements it?	Services Engagement?
Khoros SSO (previously called Lithium SSO)	The customer must add the data to the SSO token they generate. Reference the name of the setting configured for you by Khoros Support with the value to set. See About Khoros Single Sign-On (SSO) for more information.	No
Self-Service SAML	Customer must update the attribute mapping in Community Admin. See Self-serve SAML SSO set up in the Admin Panel.	No
Legacy SAML	Khoros Support must update the attribute mapping configuration	No
Self-Service OAuth 2/Open ID Connect	Customer can update the attribute mapping in Community Admin. See and About the OpenID Connect Plugin.	No
Legacy Oauth 2 or Open ID Connect	Khoros Professional Services	Yes
Custom SSO solution	Khoros Professional Services	Yes

Create your Support ticket

This customization requires a Support ticket to:

• create a custom user setting field that will hold the pronoun value.
• add the new field to user registration and user profile forms in the Community UI.

In your Support ticket:

• request a custom user setting field that will hold the pronoun value. Request the new field be set as type "String"
• provide a name for the setting field. It should be lower-case with underscores if needed. Example: profile_name_pronoun
• include the name of the custom component used to redirect to the My Settings > Preferences > Privacy page. (We describe how to write this component in the next section).
• request for the new setting and redirect component to be added to the PersonalProfile form XML as a field setting.
• (SSO-only) include the method of SSO that your community uses (see options from the table above)
• (Non-SSO only) request for the new setting to be added to the UserRegistration and UserRegistrationDialog form XML as a setting field.

Create a redirect component

We created a custom component called custom.profile.name.prefix.make_public to provide a link to the My Settings > Preferences > Privacy page. The link enables the user to quickly modify their pronoun privacy preference if they desire.

To replicate this, create a custom component to render the link. Include the component name in your Support ticket. Instead of adding the component to a page, Support will add a reference to the component when they add the new pronoun user setting to the Personal Profile form XML.

This is the code for the link. You'll want to add your own styling for the component in your CSS and use a text key for the link text if your community uses multiple languages.

 

 

<a href="/t5/user/myprofilepage/tab/user-preferences:privacy" target="_blank">Update who can see your private info</a>

 

 

Update attribute mappings in Community Admin (SSO-only)

If your community uses Khoros SSO, Self-Service SAML, or Self-Service OAuth 2/Open ID Connect update attribute mappings as directed in the guides referred to in the table above in SSO considerations.

Use pronouns in customizations

After Support has finished with your ticket (and you have updated attribute mappings required for an SSO implementation), you're ready to use pronouns in customizations.

• Request the pronoun metadata
• Display the pronouns

Once users set their own pronouns, you can display them in custom components. You'll see on Atlas that we display pronouns in several places (given that the end-user has given permission for pronouns to be displayed). For example, you can see mine in my profile hovercard and in my member profile.

Profile Hover Card

Member Profile

Request the pronoun metadata

In your custom component, you'll need to make a request to the Community REST API v1 endpoint /users/id/[id]/settings/name/[setting_name].

The FreeMarker will look something like this

 

 

<#assign namePronouns = rest("/users/id/${page.context.user.id}/settings/name/custom-setting-name").value />

 

 

Notice here that we are retrieving the user specific to the Profile Page context using the page.context.user.id FreeMarker context object and that we pass the name of the custom pronoun field. The .value returns the value of the field. We've assigned the pronoun value to the namePronouns variable.

Display the pronouns

Now that we've got the user's pronouns, we can display them using a FreeMarker interpolation. We reference this text key to render the field name:
page.search.field.custom.profile_name_prefix = Pronouns

 

 

<section>
  <span>${page.search.field.custom.profile_name_prefix}</span>
  <span>${namePronouns!""}</span>
</section>

 

 

If you wanted to display the user's name in addition to their pronouns, the code could look something like this.

 

 

<#assign namePronouns = rest("/users/id/${page.context.user.id}/settings/name/custom-setting-name").value />
<#assign nameFirst = rest("/users/id/${page.context.user.id}/settings/name/profile.name_first").value />
<#assign nameLast = rest("/users/id/${page.context.user.id}/settings/name/profile.name_last").value />

<table>
  <tbody>
  
    <#if namePronouns?? && namePronouns?length gt 0>
    <tr>
      <td>${page.search.field.custom.profile_name_prefix}</td>
      <td>${namePronouns}</td>
    </tr>
    </#if>

    <#if nameFirst?? && nameFirst?length gt 0>
    <tr>
      <td>${custom.profile_name.title}</td>
      <td>${nameFirst!""} ${nameLast!""}</td>
    </tr>
    </#if>

  </tbody>
</table>

 

 

And there you have it! A custom profile field to store pronouns that can be added to any component in your Community.