Skip to main content

UI Assets Overrides

All the assets served to the UI of Hanami can be overriden. For this, one would need to add to their customer.yml file something like this:

local:
  assets:
    folder: /opt/hanami/ext

Like this, files in the /opt/hanami/ext folder will be put in the folder serving UI assets. This could override any file in there even index.html, but we recommend to not blindly override any random file. Instead, we procure here a list of usual overrides that serves dedicates purposes.

i18n files​

By default, Hanami loads 2 files when rendering the application in a given language. For example when the application is in English, it loads assets/i18n/en.json and assets/i18n/en.customer.json. Those files are holding most of the labels used in the application, structured in deep string maps that serves as keywords to map to labels. For example part of en.json looks like this:

{
  "global": {
    "cancel": "Cancel",
    "close": "Close",
    "collection": "Collection",
    "copy_uri": "Copy URI",
    "created": "Created",
    "delete": "Delete"
  },
  "some_other_key": {
    "that_can_go": {
      "super_deep": "foo",
      "something": "else"
    }
  }
}

Which means that, when the interface is trying to find a label for the key some_other_key.that_can_go.super_deep, it will print the label foo. And for some_other_key.that_can_go.something, it will print else.

Now considering en.customer.json. By default, it is served as an empty json {} and so will not have any impact. But let's say that we configured the override by using the opt/hanami/ext folder, then one could add there /opt/hanami/ext/assets/i18n/en.customer.json that would look like this:

{
  "some_other_key": {
    "that_can_go": {
      "super_deep": "bar"
    }
  }
}

With this, when the interface will try and display a label for some_other_key.that_can_go.super_deep, it will print the label bar. And since we are doing a deep merge of the 2 maps, some_other_key.that_can_go.something will still be printed as else.

Customer specific keywords​

If you need to add new keywords to the translation map, we advise to put them under a dedicated customer to be sure to not accidentally override keywords used elsewhere in the application. Then a typical en.customer.json file would look like this:

{
  "customer": {
    "my_custom_key": "Hello World"
  }
}

This is especially useful when configuring other Hanami features that make use of translation labels, like workflow actions or footer links labels (see below).

UI Config file​

An other file that is loaded on start is assets/config.json, and by default it is an empty json {}. Put properties can be added to it to configure some features.

When overriding assets/config.json, one could set some properties as below:

{
  "footer": {
    "links": [
      {
        "labelKey": "customer.footer.google",
        "url": "https://google.com"
      },
      {
        "labelKey": "customer.footer.send_feedback",
        "url": "mailto:feedback@domain.com"
      }
    ]
  }
}

Thanks to this, 2 links will be displayed in the footer of the application. Please notice also that we are just making use of label keys here, so you would need to also put the proper labels in an i18n override file.