Skip to content

Loops ​

The Repeater Field element repeats a Global Block (a Component in Oxygen) once per item. With VX, the items can be a field on the current entry: one card per team member, one image per gallery photo, one card per related Writer.

Build a loop ​

  1. Create a Global Block or Component for one item. Bind its elements to VX fields, such as Team > Name.
  2. Add a Repeater Field element where the list should appear.
  3. Choose your VX field as its source, and the block as what it repeats.

While you edit the block on its own, its fields show the first row. In the Repeater Field element, you see every row.

Choose the source ​

To getChooseInside the block
One card per repeater rowThe RepeaterTeam > Name is this row's name
One element per imageThe GalleryBind an Image element to the gallery, or a text element to its URL
One element per selectionCheckboxes or MultiselectThe field is this selection
One element per fileThe Files fieldBind the file's link and title yourself; nothing is bound for you
One card per related entryA relation that allows several itemsThe relation's fields, like Writers > Name, read the related entry

To show all gallery images in one element, bind a gallery control to the field directly.

When you loop over a relation of posts, each row is a real post. The builder's own fields, like the post title and featured image, read the related post inside the block, and so do VX fields from that post's own fieldsets. Only published posts make a row, and the same goes for fields read outside a loop.

Term relations work the same way with the builder's term fields. For relations to users, use the relation's own VX fields: Writers > Name.

Nesting ​

Put a Repeater Field element inside the block to nest loops: loop over team members, and inside each card, loop over that member's links. Each level keeps its own item.

Inside a repeater of a related entry, use the fields under the same path: Writers > Links > URL.

Don't nest two loops over the same field. The inner loop takes over.

Use the Post Loop Builder ​

The Post Loop Builder runs a real post query, with the builder's own layouts and pagination. VX adds two conditions to it, and to any other element with a Custom Query. Set the query's source to Post Types, then add one under Conditions:

ConditionYou chooseThe loop shows
Loop: Related entriesA field that links to several postsThe posts that field holds on the current entry, in the field's order
Loop: Order by fieldlow to high or high to low, then a fieldEvery post the query finds, sorted by that field

Loop: Related entries is how you get "other books by this writer" with a real post loop: add it, pick the field, and set the number of posts as usual. If the field holds nothing published, the loop lists nothing. Each post in the loop is the full related post, so the builder's fields and VX fields both read it. It shows one page of entries, up to that number, and the element's pagination stays hidden.

Loop: Order by field sorts on fields at the top level of a fieldset. Numbers sort as numbers, and everything else sorts as text. Posts with no value stay in the list: first in low to high, last in high to low. Pagination and Load More keep the order across pages.

Add both to sort related entries by a field.

The two conditions only change queries. In an element's display conditions, they have no effect.

Good to know ​

  • VX fields also work in a Post Loop Builder's block, where they read each post.
  • If the source has no items on a page, the element shows its When Empty block if you set one.
  • Static items take their position in the list, and every row still appears.
Technical details for LLMs
  • Loop sources come from the VX catalog: list nodes (repeaters, choices, plain lists), media lists and relations that allow several items. A field that already has a value entry takes a __loop suffix, as in vx_photos__loop.
  • Files, Field Table, Content sections and Recurring Date lists are sources too. A list inside a Content sections layout is a source of its own, and reads the current row of that field.
  • Inside a relation loop, the global post (or the current term) is the related entry for that row, and is restored when the loop ends.
  • Each row sets a VX loop frame, the same as the block editor's data loops. A field follows a frame only while the entry the row rendered on is still the current one, so a Post Loop Builder inside a repeater row reads each looped post.
  • The Post Loop Builder conditions are vx-loop-related and vx-loop-order. Each stores a field's slug in the element's query. A slug the current fieldsets don't offer lists nothing in the first, and changes nothing in the second.
  • Loop: Order by field reads the post meta under the field's key, as DECIMAL(20,6) for number fields.

Documentation for the VX Framework.