Documentation

Class

NameFmt

NameFmt(options)

Creates a formatter that can format person name instances (Name) for display to a user. The options may contain the following properties:

  • locale - Use the conventions of the given locale to construct the name format.
  • style - Format the name with the given style. The value of this property should be one of the following strings:
    • short - Format a short name with just the given and family names. eg. "John Smith"
    • medium - Format a medium-length name with the given, middle, and family names. eg. "John James Smith"
    • long - Format a long name with all names available in the given name object, including prefixes. eg. "Mr. John James Smith"
    • full - Format a long name with all names available in the given name object, including prefixes and suffixes. eg. "Mr. John James Smith, Jr."
    • formal_short - Format a name with the honorific or prefix/suffix and the family name. eg. "Mr. Smith"
    • formal_long - Format a name with the honorific or prefix/suffix and the given and family name. eg. "Mr. John Smith"
    • familiar - Format a name with the most familiar style that the culture of the locale will accept. In some locales, it is not rude to address people you just met by their given name. In others, it is rude to address a person in such a familiar style unless you are previously invited to do so or unless you have known them for a while. In this case, it will use a more formal style, but still as familiar as possible so as not to be rude.
  • components - Format the name with the given components in the correct order for those components. Components are encoded as a string of letters representing the desired components:
    • p - prefixes
    • g - given name
    • m - middle names
    • f - family name
    • s - suffixes
    • h - honorifics (selects the prefix or suffix as required by the locale)

    For example, the string "pf" would mean to only format any prefixes and family names together and leave out all the other parts of the name.

    The components can be listed in any order in the string. The components option overrides the style option if both are specified.
  • onLoad - a callback function to call when the locale info object is fully loaded. When the onLoad option is given, the localeinfo object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
  • sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
  • loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

Formatting names is a locale-dependent function, as the order of the components depends on the locale. The following explains some of the details:

  • In Western countries, the given name comes first, followed by a space, followed by the family name. In Asian countries, the family name comes first, followed immediately by the given name with no space. But, that format is only used with Asian names written in ideographic characters. In Asian countries, especially ones where both an Asian and a Western language are used (Hong Kong, Singapore, etc.), the convention is often to follow the language of the name. That is, Asian names are written in Asian style, and Western names are written in Western style. This class follows that convention as well.
  • In other Asian countries, Asian names written in Latin script are written with Asian ordering. eg. "Xu Ping-an" instead of the more Western order "Ping-an Xu", as the order is thought to go with the style that is appropriate for the name rather than the style for the language being written.
  • In some Spanish speaking countries, people often take both their maternal and paternal last names as their own family name. When formatting a short or medium style of that family name, only the paternal name is used. In the long style, all the names are used. eg. "Juan Julio Raul Lopez Ortiz" took the name "Lopez" from his father and the name "Ortiz" from his mother. His family name would be "Lopez Ortiz". The formatted short style of his name would be simply "Juan Lopez" which only uses his paternal family name of "Lopez".
  • In many Western languages, it is common to use auxillary words in family names. For example, the family name of "Ludwig von Beethoven" in German is "von Beethoven", not "Beethoven". This class ensures that the family name is formatted correctly with all auxillary words.
Constructor

# new NameFmt(options)

Parameters:
Name Type Description
options Object

A set of options that govern how the formatter will behave

View Source NameFmt.js, line 127

Methods

# format(name) → {string|undefined}

Format the name for display in the current locale with the options set up in the constructor of this formatter instance.

If the name does not contain all the parts required for the style, those parts will be left blank.

There are two basic styles of formatting: European, and Asian. If this formatter object is set for European style, but an Asian name is passed to the format method, then this method will format the Asian name with a generic Asian template. Similarly, if the formatter is set for an Asian style, and a European name is passed to the format method, the formatter will use a generic European template.

This means it is always safe to format any name with a formatter for any locale. You should always get something at least reasonable as output.

Parameters:
Name Type Description
name Name | Object

the name instance to format, or an object containing name parts to format

View Source NameFmt.js, line 326

the name formatted according to the style of this formatter instance

string | undefined

# getComponents() → {string}

Return the list of components used to format names in this formatter

View Source NameFmt.js, line 303

the list of components

string

# getLocale() → {Locale}

Return the locale for this formatter instance.

View Source NameFmt.js, line 287

the locale instance for this formatter

Locale

# getStyle() → {string}

Return the style of names returned by this formatter

View Source NameFmt.js, line 295

the style of names returned by this formatter

string