MessageManager

@objcMembers public class MessageManager: NSObject

Object responsible for managing message strings within Blockly.

MessageManager stores messages that are accessible by a unique key. It also allows the ability to store synonym keys, that map back to an existing message key, as another way to access an existing message.

Here is an example of MessageManager in use:

let manager = MessageManager.shared

// Add a message for "LISTS_INLIST"
manager.loadMessages(["LISTS_INLIST": "in list"])

// Set synonyms of "LISTS_INLIST"
manager.loadSynonyms(["LISTS_GET_INDEX_INPUT_IN_LIST": "LISTS_INLIST"])
manager.loadSynonyms(["LISTS_SET_INDEX_INPUT_IN_LIST": "LISTS_INLIST"])

manager.message(forKey: "LISTS_INLIST")                    // Returns "in list"
manager.message(forKey: "LISTS_GET_INDEX_INPUT_IN_LIST")   // Returns "in list"
manager.message(forKey: "LISTS_SET_INDEX_INPUT_IN_LIST")   // Returns "in list"

This class is designed as a singleton instance, accessible via MessageManager.shared.

  • Shared instance.

    Declaration

    Swift

    public static var shared: MessageManager =
  • Loads messages from a file containing a JSON object, where each object value is a message key mapped to a message value. When a message is stored, each key is automatically prefixed with the prefix parameter passed into the method.

    For example, assume a messages.json file that contains the following data:

    {
      "GREETING": "Welcome",
      "TODAY": "Today"
    }
    

    Here’s how this file would be loaded and accessed in the manager:

    let manager = MessageManager.shared
    try manager.loadMessages(withPrefix: "PREFIX_", jsonPath: "messages.json")
    
    manager.message(forKey: "PREFIX_GREETING")  // Returns "Welcome"
    manager.message(forKey: "GREETING")         // Returns `nil` since there is no prefix
    

    Note

    Message keys are case-insensitive. Any existing message is overwritten by any message in the given file with a duplicate key.

    Declaration

    Swift

    public func loadMessages(
        withPrefix prefix: String, jsonPath: String, bundle: Bundle? = nil) throws
  • Loads messages from a given dictionary, where each pair is a message key mapped to a message value.

    Note

    Message keys are case-insensitive. Any existing message is overwritten by any message in the given dictionary with a duplicate key.

    Declaration

    Swift

    public func loadMessages(_ messages: [String: String])
  • Loads synonyms from a file containing a JSON object, where each object value is a synonym key mapped to a message key. When a synonym is stored, both the synonym key and message key are automatically prefixed with the prefix parameter passed into the method.

    For example, assume a synonyms.json file that contains the following data:

    {
      "MAIN_SCREEN_TITLE": "MAIN_TITLE",
      "ALTERNATE_SCREEN_TITLE": "MAIN_TITLE"
    }
    

    And also a messages.json file that contains the following data:

    {
      "MAIN_TITLE": "Welcome",
    }
    

    Here’s how these files would be loaded and accessed in the manager:

    let manager = MessageManager.shared
    try manager.loadMessages(withPrefix: "PREFIX_", jsonPath: "messages.json")
    try manager.loadSynonyms(withPrefix: "PREFIX_", jsonPath: "synonyms.json")
    
    // All of these calls return "Welcome"
    manager.message(forKey: "PREFIX_MAIN_SCREEN_TITLE")
    manager.message(forKey: "PREFIX_ALTERNATE_SCREEN_TITLE")
    manager.message(forKey: "PREFIX_TITLE")
    
    // All of these calls return `nil`
    manager.message(forKey: "MAIN_SCREEN_TITLE")
    manager.message(forKey: "ALTERNATE_SCREEN_TITLE")
    manager.message(forKey: "TITLE")
    

    Note

    Synonym keys are case-insensitive. Any existing synonym is overwritten by any synonym in the given file with a duplicate key.

    Declaration

    Swift

    public func loadSynonyms(
        withPrefix prefix: String, jsonPath: String, bundle: Bundle? = nil) throws
  • Loads synonyms from a given dictionary, where each pair is a synonym key mapped to a message key.

    Note

    Synonym keys are case-insensitive. Any existing synonym is overwritten by any synonym in the given file with a duplicate key.

    Declaration

    Swift

    public func loadSynonyms(_ synonyms: [String: String])
  • Returns a message value for a given message key or synonym key. Lookup prioritizes finding the key in the message table first, before looking in the synonym table. If no value could be found for the key from either the message table or synonym table, then nil is returned.

    Note

    Key lookups are case-insensitive.

    Declaration

    Swift

    public func message(forKey key: String) -> String?

    Return Value

    The message for the given key, if it exists in the message table or synonym table. If the key could not be found, then nil is returned.

  • Decodes a given string by replacing any keys of the form %{} found within the string with corresponding messages found inside this instance that use that key.

    Additionally, for any keys that are successfully replaced, this method recursively decodes those values, if those values contain references to more keys of the form %{}.

    For example:

    let messageManager = MessageManager.shared
    messageManager.loadMessages([
      "bky_name": "Blockly",
      "bky_description": "This is the %{bky_name} library."
    ])
    messageManager.decodedString("%{bky_name}")                     // "Blockly"
    messageManager.decodedString("%{bky_description}")              // "This is the Blockly library."
    messageManager.decodedString("%{non_existent_message}")         // "%{non_existent_message}"
    messageManager.decodedString("Learn to code with #%{bky_name}") // "Learn to code with #Blockly"
    

    Note

    Decoding a string with a key inside another key is not supported by this method (eg. "%{bky_{%bky_key2}key1}"). It’s recommended that this situation is avoided as the outcome of this cannot be guaranteed.

    Declaration

    Swift

    public func decodedString(_ string: String) -> String

    Return Value

    The decoded version of string.