{tagcloud:item_ids:count:alias:count_field}

Description

Builds an HTML tag cloud (an unordered list with class tagcloud) from a set of items, weighting each tag by how often it is used. Every item becomes one list element with a CSS class tagcloud1 to tagcloud8: the shown tags, ranked by count, are spread evenly over the eight classes, tagcloud1 being the most used (style it largest). The class reflects rank, not the size of the count; with fewer than 8 tags some classes are skipped (3 tags get 1, 3 and 6), and tagcloud8 appears only when 8 or more tags are shown. You supply the tag items as a dash-separated id list (commonly built with the ids expression), an optional maximum number of tags to show (the highest-count tags win), the AA expression rendered as each tag label, and the field or expression that yields the usage count of each tag. The default label alias _#HEADLINK is not defined on most slices, and then each label prints literally as _#HEADLINK - so set your own (for example _#HEADLINE, or a bare field id such as headline........). Tags are listed in input order; only the class number is ranked by count, so the busiest tag is not necessarily first. The command outputs no styling itself - size the eight classes in your own CSS.

Parameters

item_ids required default (none)

Dash-separated list of the tag item ids, normally built with an ids expression. Each id becomes one tag in the cloud.

count optional default (all items)

Maximum number of tags to display. The highest-count tags are kept; the rest are dropped. Empty or 0 shows every supplied item.

alias optional default _#HEADLINK

The AA expression rendered as each tag label - usually an alias of the tag item, such as _#HEADLINE. Reference the tag item with its own alias (an underscore-hash alias), not a field-getter in braces: a field-getter binds to the surrounding item, not the tag. A bare field id (headline........, no braces) is also accepted and returns that field of the tag item. The default _#HEADLINK does not exist on most slices and then prints literally, so set your own.

count_field optional default a backlinks count expression

Field id or expression giving the usage count of each tag; the weight (class tagcloud1..8) is derived from it. Defaults to counting the backlinks of the tag, which is recomputed on every render unless you precount into a field.

Examples

virtual{tagcloud:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6}:4:_#HEADLINE:_#NUMBER__}
Expected(top-4 cloud: Theta tagcloud3, Kappa tagcloud1, Eta tagcloud7, Gamma tagcloud5)
Actual
  • Theta
  • Kappa
  • Eta
  • Gamma
The real-world shape: feed an ids expression that lists every keyword item, cap the cloud at the top 4 by count, label with the headline alias, weight by the numeric field. Against the 10-item Stable fixture the top 4 are Kappa 1000, Theta 255, Gamma 100, Eta 99; they render in fixture order Theta, Kappa, Eta, Gamma.
test{safe:{tagcloud:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7::_#HEADLINE:_#NUMBER__}}
Expected<ul class="tagcloud"> <li class="tagcloud6">Alpha</li> <li class="tagcloud3">Beta</li> <li class="tagcloud1">Gamma</li></ul>
Actual<ul class="tagcloud"> <li class="tagcloud6">Alpha</li> <li class="tagcloud3">Beta</li> <li class="tagcloud1">Gamma</li></ul>
Three items (the Stable fixture: Alpha=14, Beta=42, Gamma=100). The count_field argument supplies the weight of each tag from the numeric field, the alias argument supplies the label. Tags appear in input order; the class is ranked by count, so Gamma (highest) gets tagcloud1, Beta tagcloud3, Alpha tagcloud6. HTML output, shown illustratively.
test{safe:{tagcloud:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7::<span>_#HEADLINE</span>:_#NUMBER__}}
Expected<ul class="tagcloud"> <li class="tagcloud6"><span>Alpha</span></li> <li class="tagcloud3"><span>Beta</span></li> <li class="tagcloud1"><span>Gamma</span></li></ul>
Actual<ul class="tagcloud"> <li class="tagcloud6"><span>Alpha</span></li> <li class="tagcloud3"><span>Beta</span></li> <li class="tagcloud1"><span>Gamma</span></li></ul>
The alias is any AA expression rendered per tag, so you can wrap each label in your own markup (here a span; an anchor with {go:} works the same). The class still comes from the count rank.
test{safe:{tagcloud:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7:1:_#HEADLINE:_#NUMBER__}}
Expected<ul class="tagcloud"> <li class="tagcloud1">Gamma</li></ul>
Actual<ul class="tagcloud"> <li class="tagcloud1">Gamma</li></ul>
With count 1 only the tag with the highest count is kept, and it gets tagcloud1. The labels are the tag items' own _#HEADLINE alias. Wrapped in safe so the page shows the markup as text.
test{safe:{tagcloud:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7-fb3df1343ef9a7d789af1f26aa5f8849-ae1da231f3e5bc16496834a0711aa042:3:_#HEADLINE:_#NUMBER__}}
Expected<ul class="tagcloud"> <li class="tagcloud6">Gamma</li> <li class="tagcloud3">Theta</li> <li class="tagcloud1">Kappa</li></ul>
Actual<ul class="tagcloud"> <li class="tagcloud6">Gamma</li> <li class="tagcloud3">Theta</li> <li class="tagcloud1">Kappa</li></ul>
Five items, count=3 keeps only the three highest counts (Kappa=1000, Theta=255, Gamma=100); Alpha and Beta drop out. The kept tags still appear in input order (Gamma, Theta, Kappa) with classes by rank: Kappa tagcloud1, Theta tagcloud3, Gamma tagcloud6.
test[{tagcloud:}]
Expected[]
Actual[]
With no item ids there is nothing to weight, so the command returns an empty string (the brackets are literal text around it). It is also empty when none of the ids exists. A count of 0 or empty shows all tags.
virtual{tagcloud:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7:::_#NUMBER__}
Expected(three li elements all labelled with the literal text _#HEADLINK)
Actual
  • _#HEADLINK
  • _#HEADLINK
  • _#HEADLINK
Leaving the alias empty falls back to the documented default _#HEADLINK, an alias that does not exist on most slices (including this fixture), so every label prints the literal text _#HEADLINK. Always pass an alias that exists on your tag slice, such as its headline alias.
test[{tagcloud:notanid:::_#NUMBER__}]
Expected[]
Actual[]
A token that is not a real item id matches no items, so the cloud is empty. tagcloud never emits an empty ul - it returns nothing at all.