Known as field

• Part of: LH Profile Page

Since 3.14.0 a member can have a Known as name: the first name they go by when it isn’t their legal first name (e.g. "Tezzuh"). Clubs must hold a member’s full legal name, so first_name and last_name hold the legal name and Known as holds the name they are shown by. It is always labelled "Known as", never "Nickname".

Storage and validation

• Stored in the core nickname user meta. No new meta key and no register_meta() (core key, as with first name). Logic lives in LH_Profile_Known_As_Field (includes/lh-profile-known-as-field-class.php).
• One first name only. No spaces or surname, never an email address; letters, marks, apostrophes, hyphens and full stops; at most 50 characters.
• Reading. WordPress and LH User Provisioning fill nickname with placeholders (a username, an email address, a full name or the first name), so return_known_as() only reports it when it is a valid single name that differs from the legal first name. Anything else reads as empty.
• Clearing. Emptying the field on the profile form sets nickname back to the legal first name rather than blanking it. An empty value never touches a nickname that isn’t a Known as value.
• Audit. Each write stamps lh_profile-updated_field and lh_profile-updated_time, like the other profile fields.

Display name

Members are shown by their Known as name and legal last name (e.g. "Tezzuh Jiang"), or by their legal first and last name when there is no Known as. sync-display-name sets this with display_name_from: known_as_last. Saving or clearing Known as through the profile form updates the display name automatically, but only when it was built from the names (legal first and last name, the previous Known as and last name, or a placeholder); a display name chosen some other way is left alone. On the BuddyPress profile edit form the script builds the Name field the same way.

xProfile and abilities

• xProfile field type lh_profile-known_as ("User Known As", LH_Profile_xprofile_known_as_extender). Add it to a field group after the name fields, labelled "Known as", with the description "The first name you go by, if it’s not your legal first name." Adding it to onboarding is configuration only.
• search-users returns known_as and searches it (partial, against nickname).
• create-or-fill-user takes known_as, fill-if-empty, and refuses it together with nickname. For a new user without a supplied display_name, the display name becomes the Known as name and last name.