Class ilib.NameFmt
Creates a formatter that can format person name instances (ilib.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.
- medium - Format a medium-length name with the given, middle, and family names.
- long - Format a long name with all names available in the given name object, including prefixes.
- full - Format a long name with all names available in the given name object, including prefixes and suffixes.
- 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
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.
- 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.
Defined in: ilib-dyn-full.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
ilib.NameFmt(options)
|
| Method Attributes | Method Name and Description |
|---|---|
|
format(name)
Format the name for display in the current locale with the options set up
in the constructor of this formatter instance.
|
|
|
Return the list of components used to format names in this formatter
|
|
|
Return the locale for this formatter instance.
|
|
|
getStyle()
Return the style of names returned by this formatter
|
Class Detail
ilib.NameFmt(options)
- Parameters:
- {Object} options
- A set of options that govern how the formatter will behave
Method Detail
{string|undefined}
format(name)
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:
- {ilib.Name} name
- the name to format
- Returns:
- {string|undefined} the name formatted according to the style of this formatter instance
{string}
getComponents()
Return the list of components used to format names in this formatter
- Returns:
- {string} the list of components
{ilib.Locale}
getLocale()
Return the locale for this formatter instance.
- Returns:
- {ilib.Locale} the locale instance for this formatter
{string}
getStyle()
Return the style of names returned by this formatter
- Returns:
- {string} the style of names returned by this formatter