{rotator:ids:code:interval:speed:effect:li_code}

Description

Builds a rotator (a slideshow or carousel) that cycles through several content blocks in one spot on the page, switching automatically at a fixed interval. You give it a list of item ids and a small template; for each item it expands the template into one frame, stacks the frames in a div, shows the first, and emits a script that advances to the next frame on a timer. Inside the frame template, an alias such as _#HEADLINE resolves against the item being shown, not the surrounding page, so each frame can carry that item's own fields. The rotation is driven by AA_Rotator in the aa-jslib JavaScript library, which rotator requests automatically; hovering the rotator pauses it and moving away resumes it (jQuery library only). The interval is given in milliseconds and defaults to 3000 (three seconds). speed sets how fast each switch animates (the jQuery duration: slow or fast; empty or any other value uses the 400 ms default) and effect chooses how it switches (empty hides and shows the frame, fade cross-fades it). An optional sixth template, the li-code, builds a clickable list of switcher buttons under the frames so a visitor can jump to or hover over any frame. Items whose frame template expands to nothing are skipped, and an empty id list gives an empty string, and a single frame is shown but does not rotate. rotator reads live items and is recomputed on every request; the id of its div is a hash of ids, code, interval, speed and effect, so the same call always gives the same id; the sixth (switcher) template is not part of it, so two rotators on one page that differ only in it get the same id and clash. The asserted examples wrap the call in safe so the generated markup is shown as text; the example that builds the id list with a reader runs live on this page.

Parameters

ids required default (none - required)

Dash-separated long ids of the items to rotate, typically produced by the ids command. Each item gives one frame, in the order given. An empty list returns an empty string.

code required default (empty)

The frame template - an AA expression expanded once per item to build that frame. It is expanded against the item being shown, so aliases and field getters inside it read that item (for example _#HEADLINE or {headline........} give each item its own headline). An item whose template expands to an empty string is skipped.

interval optional default 3000

How long each frame stays visible before the next one, in milliseconds. Empty or zero falls back to 3000 (three seconds).

speed optional default (empty)

How fast each switch animates - the jQuery animation duration. Empty uses the jQuery default of 400 ms; slow is 600 ms and fast 200 ms; other values, numbers included, fall back to 400 ms (the value reaches jQuery as a string). The legacy AA JS library ignores speed and effect.

effect optional default (empty)

How frames switch. Empty hides the old frame and shows the new one (animated over speed); fade cross-fades between them (the frames are stacked absolutely so they overlap during the fade).

li_code optional default (empty)

Optional switcher template. When given, rotator also renders a list (ul.rot-switcher) of clickable buttons under the frames, one per frame, built by expanding this template per item just like code. Clicking or hovering a button jumps to that frame. Leave empty for no switcher.

Examples

test{safe:{rotator:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0:<div>_#HEADLINE</div>}}
Expected<div id="rot65f3e30c769f425d36e1c44d4cf04677" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div> <div class=rot-hide style="display:none; "><div>Beta</div></div></div></div><script>AA_Rotator('rot65f3e30c769f425d36e1c44d4cf04677', 3000, 2, '', '');</script>
Actual<div id="rot65f3e30c769f425d36e1c44d4cf04677" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div> <div class=rot-hide style="display:none; "><div>Beta</div></div></div></div><script>AA_Rotator('rot65f3e30c769f425d36e1c44d4cf04677', 3000, 2, '', '');</script>
The simplest rotator: two items, one frame template. The template <div>_#HEADLINE</div> is expanded per item, so frame one is <div>Alpha</div> and frame two is <div>Beta</div>. interval is omitted, so it defaults to 3000 ms. The div id is a hash of the parameters, so it is the same on every render.
test{safe:{rotator:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0:<div>_#HEADLINE</div>:8000}}
Expected<div id="rot41ea3dfca0cef224f685900c23762c7a" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div> <div class=rot-hide style="display:none; "><div>Beta</div></div></div></div><script>AA_Rotator('rot41ea3dfca0cef224f685900c23762c7a', 8000, 2, '', '');</script>
Actual<div id="rot41ea3dfca0cef224f685900c23762c7a" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div> <div class=rot-hide style="display:none; "><div>Beta</div></div></div></div><script>AA_Rotator('rot41ea3dfca0cef224f685900c23762c7a', 8000, 2, '', '');</script>
The third parameter is the interval in milliseconds. Here each frame shows for 8000 ms (eight seconds) before the next. Empty or 0 would fall back to the 3000 ms default.
test{safe:{rotator:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0:<div>_#HEADLINE</div>:5000:slow:fade}}
Expected<div id="rotca8d8b6bb05545a542e0155b65ac6f86" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" position:absolute;"><div>Alpha</div></div> <div class=rot-hide style="display:none; position:absolute;"><div>Beta</div></div></div><div class=rot-hight style="visibility:hidden"><div>Alpha</div></div></div><script>AA_Rotator('rotca8d8b6bb05545a542e0155b65ac6f86', 5000, 2, 'slow', 'fade');</script>
Actual<div id="rotca8d8b6bb05545a542e0155b65ac6f86" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" position:absolute;"><div>Alpha</div></div> <div class=rot-hide style="display:none; position:absolute;"><div>Beta</div></div></div><div class=rot-hight style="visibility:hidden"><div>Alpha</div></div></div><script>AA_Rotator('rotca8d8b6bb05545a542e0155b65ac6f86', 5000, 2, 'slow', 'fade');</script>
Parameters four and five are speed and effect. effect fade cross-fades between frames; with fade the frames are stacked absolutely so they overlap during the transition. speed slow animates each switch over 600 ms. Empty speed plus empty effect (the default) hides and shows the frames over the 400 ms jQuery default, with no fade.
test{safe:{rotator:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0:<div>_#HEADLINE</div>:6000:fast:fade:<span>_#HEADLINE</span>}}
Expected<div id="rot3351596787e059e9d7fc24a1f9907afe" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" position:absolute;"><div>Alpha</div></div> <div class=rot-hide style="display:none; position:absolute;"><div>Beta</div></div></div><div class=rot-hight style="visibility:hidden"><div>Alpha</div></div><ul class="rot-switcher"><li class="rot-active active" onclick="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=0;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe'); " onmouseover="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=0;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe');"><span>Alpha</span></li> <li class="rot-active" onclick="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=1;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe'); " onmouseover="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=1;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe');"><span>Beta</span></li></ul></div><script>AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe', 6000, 2, 'fast', 'fade');</script>
Actual<div id="rot3351596787e059e9d7fc24a1f9907afe" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" position:absolute;"><div>Alpha</div></div> <div class=rot-hide style="display:none; position:absolute;"><div>Beta</div></div></div><div class=rot-hight style="visibility:hidden"><div>Alpha</div></div><ul class="rot-switcher"><li class="rot-active active" onclick="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=0;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe'); " onmouseover="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=0;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe');"><span>Alpha</span></li> <li class="rot-active" onclick="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=1;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe'); " onmouseover="AA_Rotator.rotators['rot3351596787e059e9d7fc24a1f9907afe'].index=1;AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe');"><span>Beta</span></li></ul></div><script>AA_Rotator('rot3351596787e059e9d7fc24a1f9907afe', 6000, 2, 'fast', 'fade');</script>
The full six-parameter form, matching real production use. The sixth parameter, li-code, is a second per-item template that builds a switcher: a ul.rot-switcher with one li per frame (here labelled by _#HEADLINE). Visitors can click or hover a button to jump to that frame; the first button starts active.
virtual{rotator:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6}:<div>_#HEADLINE</div>}
Expected(one frame per item in the Stable slice, each <div>Headline</div>, rotating every 3 seconds)
Actual
Zeta
The real-world shape: feed the ids with an inner reader instead of hard-coded ids, so the rotator follows a whole slice (here every item in the Stable test slice). Add conditions to ids to rotate only selected items.
test{safe:{rotator:a65d19971986e750761f0efcd9a16b1b:<div>_#HEADLINE</div>}}
Expected<div id="rot4afaf829acad9c40232f745f18d8bcd3" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div></div></div><script>AA_Rotator('rot4afaf829acad9c40232f745f18d8bcd3', 3000, 1, '', '');</script>
Actual<div id="rot4afaf829acad9c40232f745f18d8bcd3" style="position:relative"><div class="rot-frames"><div class=rot-hide style=" "><div>Alpha</div></div></div></div><script>AA_Rotator('rot4afaf829acad9c40232f745f18d8bcd3', 3000, 1, '', '');</script>
A single id gives one frame. rotator still emits the frame and the script, with a frame count of 1, and AA_Rotator does nothing with fewer than two frames - the frame simply stays. An empty id list, or frames that all expand to nothing, give an empty string. Wrapped in safe so the page shows the generated markup as text.