HexagonJS
Edit Page
User Facing Text
A module used for defining the default text for hexagon modules.
All the default text within hexagon is now defined using this module. It can be overriden for each instance if required using the options for each component.
This module can also be used as a method for localisation of user facing text.
Hexagon provides all text in English.
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 -

Main Page -

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
Functions
hx.userFacingText.formatstringStringparametersObjectreplacerFunctionadded
Added
Expose the function used in Hexagon to format strings with parameters
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
The current param key
parameters
The parameters object as passed in to format
Returns
The replaced string
hx.userFacingText.toMultilineSelectionstringToSplitStringtextElementStringdontAddBreakBooleanSelectionadded
Added
Added a utility for converting a text string with \n characters into a selection containing span elements separated by br elements
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.
hx.userFacingTextmoduleStringkeyStringparseLaterBooleanStringupdated
Updated
This function will now show a console warning when it returns a string with a $param in.
Call with hx.userFacingText(module, key, parameters) to replace the parameters immediately or call hx.userFacingText(module, key, true) if you need to retain the current functionality and hide the warning.
Gets the text for a module key
Arguments
moduleString
The module to get text from
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
The currently set text
hx.userFacingTextmoduleStringkeyStringvalueString / Arrayupdated
Updated
Updated the value argument to allow an array to be set, allowing plurals.
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'
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
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.userFacingTextmoduleStringkeyStringparametersObjectStringupdated
Updated
Added a new function for getting the user facing text with parameters
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
The key to get text for
parameters
The parameter object with keys to inject into the string.
Default: false
Returns
The currently set text
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.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.