Formatting captions

[simonwinter]

The old version of the site, uses some a number of different elements we don't have:

• Each transform has it's own associated formatter
• Each indicator has "units" passed to the chart.
• Each transform has a "name".

[simonwinter]

Language Config Keys:

So we have the following unique keys in the config across all the indicator yaml files:

• "subject"
• "subject-quantity"
• "singular"
• "captions"
• "subject-short"
• "feature-accessor"
• "feature-label"
• "labels"
• "feature-as-subject-label"
• "subject-accessor"

[simonwinter]

EDIT: TL;DR

Basically each indicator needs a labels section in the language config where the key is the transform. Look to retail-trade.yml as an example.

---

Chart captions are currently calculated like so:

1. Get the indicator
2. Get the transform

Each transform on each chart on an indicator can have a caption & possibly a formatter:

"timeseries": {
    "type": "timeseries",
    "title": "Change in GDP per capita, for the year to $yearEndMonth$",
    "transforms": [
        {
            "name": "absolute",
            "caption": "GDP per capita"
        },
        {
            "name": "indexed",
            "caption": "GDP per capita indexed to $firstYear$",
            "formatter": "indexed"
        }
    ],
    "order": [
        "area",
        "year"
    ]
}

If a caption exists for a transform on an indicator, then that becomes the text that is formatted. If a formatter exists, there is some reducing to find the formatting option to pass to the formatter function:

switch (currentTransform.name) {
    case "indexed":
        fstr = "indexed";
        break;
    case "regionalPercentage":
    case "nationalPercentage":
    case "rate":
        fstr = "percentage";
        break;
    case "absolute":
        fstr = indicator.get("model.units");
        break;
    default:
        fstr = "count";
}

3. We now have the text & formatter required to pass to the formatting function to generate the caption:

The function outputs text + a formatter:

...
text: text ? text[0].toUpperCase() + text.slice(1) : "",
formatter: function(d) {
    return formatting(fstr, d);
}

function formatting(units, value) {
  switch (units) {
    case "million dollars":
        return moneyFormatter(value) + " M";
    case "dollars":
        return moneyFormatter(value);
    case "percentage":
        return percentageFormatter(value) + " %";
  }
    return commasFormatter(value);
}

...

Eventually, the caption of the chart is based upon the transform:

function(transform) {
    if (this.get('transforms').indexOf(transform) === -1) {
      if (transform === "absolute") {
        transform = "original";
      } else if (transform === "regionalPercentage") {
        transform = "feature-percentage";
      } else if (transform === "rate") {
        transform = "annual-rate";
      } else {
        return "";
      }
    }
    let l = textSubstitution(this.get("indicator.labels")[transform], this);
    return l[0].toUpperCase() + l.slice(1);
  }

where textSubstitution is:

function textSubstitution(s, bw, addCompareArea) {
    var y = bw.get('year.name'),
        fy = bw.get('indicator.firstYear.name'),
        yem = bw.get('indicator.yearEndMonth'),
        su = bw.get('indicator.subject'),
        a = bw.get('area.name'),
        sa = bw.get('area.name'),
        f = bw.get('feature.name'),
        fl = f || bw.get('indicator.topFeatureLabel'),
        fp = f ? bw.get('feature.parent') : "",
        d = bw.get('detail.name'),
        dl = d || bw.get('indicator.topDetailLabel'),
        ft = bw.get('indicator.featureText'),
        p = bw.get("prevYear"),
        ca = bw.get("compareArea.name");
    if (present(addCompareArea) && present(ca)) {
        a = "<span class='active'>" + a + "</span><span class='compare'> (and " + ca + ")</span>";
    }
    if (ft) {
      var fs = bw.get('feature.id');
      fl = ft[fs];
    }
    if (f) {
        s = s.replace(/[\[\]]/g, '');
    } else {
        s = s.replace(/\[.+?\]/g, '');
    }
    if (d) {
        s = s.replace(/[\{\}]/g, '');
    } else {
        s = s.replace(/\s?\{.+?\}/g, '');
    }
    s = s.replace(/\$year\$/g, y)
        .replace(/\$firstYear\$/g, fy)
        .replace(/\$yearEndMonth\$/g, yem)
        .replace(/\$subject\$/g, su)
        .replace(/\$area\$/g, a)
        .replace(/\$selectedArea\$/g, sa)
        .replace(/\$compareArea\$/g, ca)
        .replace(/\$prevYear\$/g, p)
        .replace(/\$feature\$/g, fl)
        .replace(/\$featureType\$/g, fp)
        .replace(/\$detail\$/g, dl);
    return s.trim();
}