11 Custom Messages - ecellar/remote-widgets GitHub Wiki

The eCellar Designer Widgets system comes with a complete set of English-language 10 Content files that contain individual messages for display to your site visitor. Messages are used for all wording that does not come from the winery’s database.

You may customize any message, add messages of your own and create translations for other languages.

All messages are contained in sets of JSON-formatted data, one set for each Widget name (widget names are used for grouping messages and HTML Templates in the Designer Widget system). Message sets are loaded as needed by the SPA.

The message sets are:

Account
Campaign
Cart
Checkout
Login
Products
Reservation
Signup

To customize messages, it will be helpful for you to understand how each message set is structured. In general, you will see something like this:

{
  "en": {
    "epub": {
      "products": {
        "CategoryDetailList": {
          "ViewCategoriesLink": "View Categories",
          "ViewProductsLink": "View Wines",
        },
        "CategoryWithProducts": {
          "AddToCartButton": "Add To Cart",
          "AddMoreToCartButton": "Add More To Cart",

etc…

The JSON begins with an opening bracket:

{ 

Followed by a locale code: (“en” is US English)

"en": {

Then a container name that is used internally:

"epub": {

Then a widget name, in lower case:

"products": {

And then one or more template names, with nested message keys and values:

"CategoryDetailList": {
  "ViewCategoriesLink": "View Categories",
  "ViewProductsLink": "View Wines",
},
"CategoryWithProducts": {
  "AddToCartButton": "Add To Cart",
  "AddMoreToCartButton": "Add More To Cart",

etc… ending with appropriate closing brackets.

Templates include placeholders that are configured to instruct the SPA to replace the placeholder with the value from a message key. For example, a template in the Products widget may include something like this:

{message:ProductDetail/AddToCartButton}

Which will result in the SPA loading the message “Add To Cart” from here …

{
  "en": {
    "epub": {
      "products": {
        "ProductDetail": {
          "AddToCartButton": "Add To Cart"
        }
      }
    }
  }
}

… because the message key is at this JSON path:

You will use the SPA addMessages initialization option to specify your custom messages. The option accepts an array of items and each item may be either a URL containing JSON data or a JSON object.

See the Initialization Options page for details.

To prepare your JSON data, first figure out which key(s) you want to create custom messages for, then create some JSON that adheres to the structure described above.

Worth noting: you can combined keys from different widgets into one JSON object. For example, this contains a key for a message in the “products” widget and a key for a message in the “cart” widget:

{
  "en": {
    "epub": {
      "products": {
        "ProductDetail": {
          "AddToCartButton": "Add-to-Cart"
        }
      },
      "cart": {
        "GeneralCart": {
          "Title": "Your Shopping Cart"
        }
      }
    }
  }
}

After creating your JSON, you have 2 options:

A. Pass the JSON to your addMessages option as one of its array items.

or

B. Save the JSON as a .json file, upload it to your site and pass the file’s URL to addMessages as one of it’s array items.

Or you can do both: it’s up to you. Do whatever works best for you. If you are only customizing a few messages, or testing some individual wording changes, you may want to pass a JSON object. If you have a lot of custom messages, you may find that it’s best to put them in one or more .json files.

Note: if you use files, the file names do not matter: the SPA just needs to know the URL for each one. You should probably use a .json extension, though, so that your web host will treat it as JSON.

If you are creating 09 Custom Templates you may find the need to add placeholders for messages that are not already in the 10 Content files. You may do so using the same technique that is describe above for custom messages, but instead of using key names that already exist, you can create your own.

Be sure that the key in your placeholder matches your newly created key. For example, if you have this in your template:

{message:ProductDetail/SpecialOffer}

Then you would want to have the same key in your JSON object:

{
  "en": {
    "epub": {
      "products": {
        "ProductDetail": {
          "SpecialOffer": "Order this weekend and receive two complimentary tickets to our harvest festival."
        }
      }
    }
  }
}

TIP: As a general practice, you should not put any custom wording directly into templates. Use placeholders and message keys to keep your markup and messages separated. If you keep your messages separate, they will also work with the SPA’s locale functionality.

By default, all messages in the SPA are in English. You may create a localized version of any message (or all messages, if you’re ambitious!) in the same way that you create customized English versions.

The only difference is that instead of using this in your JSON data:

“en”: {

You would use the localization code for your desired locale. For example, for the French version you would use:

“fr”: {

When the SPA renders messages, it will take the current locale into consideration. If a message key is not available for the current locale, it will display the “en” version.

For more information about locales, please read about the setLocale and addLocales options on our Initialization Options page.