User Facing Text

Examples

// Get all currently set values
hx.userFacingText()

// Get all values that were first set
hx.userFacingText.defaults()

// Set multiple values
var text = {
  form: {
    missingValue: 'Value Missing'
  },
  yourComponentName: {
    yourKeyValue: 'Some Text'
  }
}
hx.userFacingText(text)

// Get and set inbuilt values:
hx.userFacingText('form', 'missingValue') // Get the text for the 'form' module and 'missingValue' key
hx.userFacingText('form', 'missingValue', 'Value Missing') // Set the text

// Get and set custom values
hx.userFacingText('yourComponentName', 'yourKeyValue', 'Some Text') // Set a custom user facing text
hx.userFacingText('yourComponentName', 'yourKeyValue') // Returns: "Some Text"


// Plurals use the `$n` parameter. This defaults to 1 if not provided.
hx.userFacingText('example', 'plural-key', [
  [null, 0, 'Value Zero'],
  [1, 1, 'Value Singular'],
  [2, 2, 'Value Two'],
  [3, null, 'Value $n']
])

hx.userFacingText('example', 'plural-key')
hx.userFacingText('example', 'plural-key', { n: 0 })
// => 'Value Singular'

hx.userFacingText('example', 'plural-key', { n: 0 })
// => 'Value Zero'

hx.userFacingText('example', 'plural-key', { n: 2 })
// => 'Value Two'

hx.userFacingText('example', 'plural-key', { n: 100 })
// => 'Value 100'

// The following are equivalent:
hx.userFacingText('form', 'missingValue', 'Value Missing') // Set the text
hx.userFacingText('form', 'missingValue', [[null, null, 'Value Missing']) // Set the text

Main Page -

HTML

<h4>Main Page - <span id="currentVersion"></span></h4>
<h4>Main Page - <span id="currentVersion-noparse"></span></h4>
<h4>Main Page - <span id="currentVersion-arrayparam"></span></h4>
<div id="introduction"></div>

<button id="confirmBtn" class="hx-btn"></button>
<button id="cancelBtn" class="hx-btn"></button>

JavaScript

// Translation text is two-levels deep
const myText = {
  buttons: {
    confirm: 'Confirm',
  },
  homePage: {
    introduction: 'This is an introduction.\nIt contains multiple lines',
    version: 'Current version: $version',
    versionCustom: 'Current version: {0}',
  },
}

// Set with an object
hx.userFacingText(myText)

// Set with a specific key
hx.userFacingText('buttons', 'cancel', 'Cancel')

// Use keys
hx.select('#confirmBtn').text(hx.userFacingText('buttons', 'confirm'))
hx.select('#cancelBtn').text(hx.userFacingText('buttons', 'cancel'))

// Use multiline strings in selections
hx.select('#introduction').add(hx.userFacingText.toMultilineSelection(hx.userFacingText('homePage', 'introduction')))

// Inject parameters
hx.select('#currentVersion').text(hx.userFacingText('homePage', 'version', { version: '10.10.10' }))

// Parse parameters after creation
const customVersionText = hx.userFacingText('homePage', 'version', true)
hx.select('#currentVersion-noparse').text(hx.userFacingText.format(customVersionText, { version: '1.2.3' }))

// Custom param replacement
const customText = hx.userFacingText('homePage', 'versionCustom')
const arrayReplacer = (str, key, array) => str.replace(new RegExp(`\\\{${key}\\\}`, 'g'), array[key]);
hx.select('#currentVersion-arrayparam').text(hx.userFacingText.format(customText, ['10.11.12'], arrayReplacer));

Api

Change Log

Functions

hx.userFacingTextObject

Get the currently set text for all modules

Returns

Object

The currently set userFacingText object

hx.userFacingTexttextObject

Sets multiple module text keys:

var text = {
  picker: {
    chooseValue: 'Text'
  },
  form: {
    typeMismatch: 'Type mismatch error',
    missingValue: 'Missing Value'
  }
}
hx.userFacingText(text)

It can also be used to reset the text to the default values

hx.userFacingText(hx.userFacingText.defaults())

Arguments

text

The object with module/key objects to set.

hx.userFacingTextmoduleStringkeyStringparseLaterBooleanString

Gets the text for a module key

Arguments

moduleString

The module to get text from

keyString

The key to get text for

parseLaterBoolean

Set to true to parse parameters with $param s that you are parsing at a later point in the code

Default: false

Returns

String

The currently set text

hx.userFacingTextmoduleStringkeyStringvalueString / Array

Sets the text for a module key.

When using a plurals array, the $n parameter is used to indicate how many of the value are being used.

If the $n parameter is not provided when getting the value, it defaults to 1.

hx.userFacingText('something', 'value', 'the value')

hx.userFacingText('something', 'value')
// => 'the value'


// Plurals use the `$n` parameter. This defaults to 1 if not provided.
hx.userFacingText('example', 'plural-key', [
  [null, 0, 'Value Zero'],
  [1, 1, 'Value Singular'],
  [2, 2, 'Value Two'],
  [3, null, 'Value $n']
])

hx.userFacingText('example', 'plural-key')
hx.userFacingText('example', 'plural-key', { n: 1 })
// => 'Value Singular'

hx.userFacingText('example', 'plural-key', { n: 0 })
// => 'Value Zero'

hx.userFacingText('example', 'plural-key', { n: 2 })
// => 'Value Two'

hx.userFacingText('example', 'plural-key', { n: 100 })
// => 'Value 100'

Arguments

moduleString

The module to set text for

keyString

The key to set text for.

valueString / Array

The text to set

When using an array the format is an array of arrays

[
  [min, max, string]
]

minNumber / Null

The minimum value of $n that will show this string. When using null, this is treated as 'everything below max'.

maxNumber / Null

The maximum value of $n that will show this string. When using null, this is treated as 'everything above min'.

stringString

The string to display when $n is between min/max.

hx.userFacingTextmoduleStringkeyStringparametersObjectString

Gets the text for a module key with parameter replacement.

Uses hx.userFacingText.format(string, parameters) and allows only $param style parameters.

hx.userFacingText({
  myModule: {
    helloUser: 'Hello $user!',
  },
})

hx.userFacingText('myModule', 'helloUser', { user: 'Bob' })
// => Hello Bob!

Arguments

moduleString

The module to get text from

keyString

The key to get text for

parameters

The parameter object with keys to inject into the string.

Default: false

Returns

String

The currently set text

hx.userFacingText.defaultsObject

Gets the set of values that were first set in the user facing text before any changes or updates were applied to the user facing text.

textFirst = {
  module: {
    key1: 'value1orig',
    key2: 'value2orig',
    key4: 'value4orig'
  }
}

textSecond = {
  module: {
    key1: 'value1changed',
    key3: 'value3orig',
    key4: 'value4changed',
  }
  otherModule: {
    key: 'valueorig',
  }
}
userFacingText(textFirst)
userFacingText(textSecond)

userFacingText()
// => {
//   module: {
//     key1: 'value1changed',
//     key2: 'value2orig',
//     key3: 'value3orig',
//     key4: 'value4changed',
//   },
//   otherModule: {
//     key: 'valueorig'
//   }
// }

userFacingText.defaults()
// => {
//   module: {
//     key1: 'value1orig',
//     key2: 'value2orig',
//     key3: 'value3orig',
//     key4: 'value4orig',
//   },
//   otherModule: {
//     key: 'valueorig'
//   }
// }

Returns

Object

The initial value set for the userFacingText object.

hx.userFacingText.formatstringStringparametersObjectreplacerFunction

hx.userFacingText.format('Hello $name!', { name: 'Bob' })
// => Hello Bob!

Replace based on array arguments

function arrayReplacer (str, key, array) {
  return str.replace(new RegExp("\\\{#{key}\\\}", 'g'), array[key])
}
hx.userFacingText.format('{0} {1}', ['A', 'B'], arrayReplacer)
// => 'A B'

Use rest/spread arguments to mimic other formatting libraries

function arrayReplacer (str, key, array) {
  return str.replace(new RegExp("\\\{#{key}\\\}", 'g'), array[key])
}
function replaceNumericArgs(string, thingsToReplace...) {
  return hx.userFacingText.format(text, thingsToReplace, arrayReplacer)
}
replaceNumericArgs('{0} {1} {2}', 'A', 'B', 'C')
// => 'A B C'

Arguments

stringString

The string to format. By default, this should be a string with $param values to replace.

parameters

The parameter object with keys to inject into the string.

By default this expects a plain object with string/number key value pairs however a custom replacer can be used to allow other things to be used (e.g. an array)

replacerstringStringkeyStringparametersObjectString

An optional replacer function that is run for every key in the parameters.

format uses Object.keys(parameters) and then reduces over the string with this function to produce the final parsed string.

Default:

// Replaces $key with parameters[key]
function (str, key, parameters) {
  return str.replace(new RegExp("\\\$#{key}", 'g'), parameters[key])
}

Arguments

stringString

The string that is being reduced over to find and replace parameters

keyString

The current param key

parameters

The parameters object as passed in to format

Returns

String

The replaced string

hx.userFacingText.toMultilineSelectionstringToSplitStringtextElementStringdontAddBreakBooleanSelection

A utility for converting a text string with \n characters into a selection containing text elements separated by br elements.

The element tag can be configured, as well as the presence of the br tag.

Basic Example

Paragraph Example

HTML

<h4>Basic Example</h4>
<div id="toMultiline-example-1"></div>
<h4>Paragraph Example</h4>
<div id="toMultiline-example-2"></div>

JavaScript

const stringWithMultiline = 'First Line\nSecond Line\nThird Line';

hx.select('#toMultiline-example-1').add(hx.userFacingText.toMultilineSelection(stringWithMultiline))

hx.select('#toMultiline-example-2').add(hx.userFacingText.toMultilineSelection(stringWithMultiline, 'p', true))

Arguments

stringToSplitString

The string to split on \n characters.

textElementString

The type of element to wrap each line of text with

Default: 'span'

dontAddBreakBoolean

Set to true to remove the br elements from the selection

Default: false

Returns

Selection

A selection containing the string split into multiple elements joined by br tags.