Skip to content
Documentation

Themer Loop Builder

New in 3.18.0. The Loop Builder is part of EMCP Themer. You design a post card once, as a Loop Item template, and the Loop Grid or Loop Carousel repeats it once per post. It works with Elementor and with the block editor, and the card and the grid do not have to use the same builder: an Elementor-built card can be repeated by the block, and the other way round.

The Themer module must be on (EMCP Tools → Modules, Content & design group, Themer). See Turning it on.

Free vs Pro

Section titled “Free vs Pro”
FreePro
Loop Items1Unlimited
Loop Grid and Loop Carousel, widgets and blocks, every option✓✓
Alternate templates on the Loop Grid widget✗✓

The Loop Item

Section titled “The Loop Item”

A Loop Item is a seventh Themer template type, next to Header, Footer, Single, Archive, Search and 404. Create one from EMCP Themer → Add New and choose Loop Item as the Template type, then build the card with your builder. Everything inside the card resolves against the post the card is showing, not the page the grid sits on:

  • The Themer widgets and blocks (Post/Page Title, Featured Image, Post Excerpt, Post Info, Author Box and the rest).
  • Dynamic data on any field: post title, URL, featured image, date, excerpt. See Dynamic data.
  • In a block-built card, core blocks such as Post Title, Post Featured Image, Post Excerpt, Post Date and Post Terms.

A Loop Item fills no page slot, so it takes no display conditions. Its edit screen shows Loop Item preview settings instead, which only affect what the editor shows while you design the card:

  • Preview post type: the post type to sample.
  • Preview post ID: the sample post (“0 = latest published”).
  • Canvas width: the width of the editing canvas, 200 to 1200 px (default 400).

Keep a card shallow. It renders once per post, so a card with 40 elements in a 24-post grid renders 960 elements.

Section titled “Loop Grid and Loop Carousel”
ElementElementor widgetBlock
Loop Gridemcp-loop-gridemcp/loop-grid
Loop Carouselemcp-loop-carouselemcp/loop-carousel

Both appear in the EMCP Themer category of the Elementor panel and the block inserter. They work in any page or template, not only inside Themer templates.

In the Elementor widget, the first setting is Loop Item: pick a published Loop Item (“Select a Loop Item” renders nothing). The description links to Manage Loop Items, or to Create one when none exists yet. The block has the same choice in its Loop Item panel. Only published Loop Items render; editors see an HTML comment when none is chosen.

Query sources

Section titled “Query sources”

The Query section’s Source decides where posts come from. Settings that do not apply to the chosen source are hidden, and ignored if they were set before you changed the source.

SourceLabelUse it forNeeds
postsPostsAny post type with filtersPost types (default Posts)
currentCurrent query (archive)Repeating the archive or search results the template is shown on, with that archive’s own pagingAn Archive or Search template (or any archive page)
relatedRelated to current postOther posts sharing terms with the viewed post, on a Single templateRelated by: the taxonomy to match (default Categories)
manualManual selectionA hand-picked list, shown in the order you list the IDsInclude IDs
productsProductsWooCommerce productsWooCommerce active

The settings each source shows:

  • Items per page (1 to 100, default 6): every source except Current query, which follows the archive’s own posts-per-page.
  • Skip first: posts, related and products. “Useful when a featured block above already shows the newest posts.”
  • Include terms and Exclude terms: posts and products.
  • Authors: posts.
  • Include IDs: every source except Current query (“Comma separated. With Manual selection this is also the display order.”). Exclude IDs: posts, related and products.
  • Exclude current post: posts and products (off by default), and related (on by default, so the viewed post never lists itself).
  • Ignore sticky posts: posts (on by default).
  • Date range: All time, Past day, Past week, Past month, Past quarter, Past year or Custom range (with After and Before).
  • Order by: Date, Last modified, Title, Menu order, Comment count, Random, Custom field (text) or Custom field (number) (with Custom field key); products add Price, Popularity (sales) and Average rating. Order: Descending or Ascending.
  • Products only: Hide out of stock, On sale only and Featured only.

Under Additional options, Nothing found message (default “No posts found.”) shows when the query is empty, and Item HTML tag sets each card’s wrapper: div, article, li or section.

Loop Grid

Section titled “Loop Grid”

Layout

Section titled “Layout”
  • Columns: 1 to 6, set per device (defaults 3 on desktop, 2 on tablet, 1 on mobile).
  • Masonry: “Cards keep their own height and fill the gaps.”
  • Equal height: not available with masonry.
  • First item spans: the number of columns the first card takes on desktop, for a featured post at the top. Never more than the column count (not with masonry).

Pagination

Section titled “Pagination”

Pagination offers None, Numbers, Previous / Next, Numbers + Previous / Next, Load more button and Infinite scroll.

  • Load type (numbers and previous/next): Page reload or AJAX. “AJAX replaces the cards without reloading the page and keeps the URL in step.” Load more and infinite scroll always load over AJAX.
  • Page limit: the most pages to offer; “0 shows every page.”
  • Shorten (numbers): shows fewer page numbers on each side of the current page.
  • Previous label and Next label, Button text for load more (default “Load more”), and Trigger offset (px) for infinite scroll: “How far before the end of the grid the next page starts loading.” (default 200).

How Current query pagination works. With Current query the grid pages through the archive itself. With Page reload it uses the archive’s own page links. With AJAX, EMCP takes a signed snapshot of the archive’s query when the page renders and replays it for each new page, so the cards match what a reload would show. If a plugin changes the archive’s query in a way the snapshot cannot reproduce, the grid falls back to page reloads by itself and leaves an HTML comment for editors saying so.

Style

Section titled “Style”

The Style tab has Items (padding, border radius, background, border and shadow for Normal and Hover, a Hover effect of None, Lift, Zoom or Shadow with its distance, scale and Transition duration (ms)), Layout (Gap between columns, Gap between rows, Max grid width), Entrance animation (None, Fade up, Fade in or Zoom in, with Duration (ms) and Stagger step (ms): “Delay added per item, so the cards appear one after another.”), Pagination, Load more button and Nothing found.

Section titled “Loop Carousel”

The carousel uses Swiper and the same Query section. Items per page is how many posts the carousel holds.

Layout

Section titled “Layout”
  • Slides per view: Auto (card width) or 1 to 10, per device (defaults 3, 2 and 1).
  • Slides to scroll: per device.
  • Gap between slides: per device.
  • Slide height: Fit each card or Equal height.
Section titled “Carousel settings”
  • Autoplay, with Autoplay delay (ms) (default 5000), Pause on hover and Stop on interaction (both on by default).
  • Infinite loop, Transition speed (ms) (default 500) and Direction (Left to right or Right to left).
  • Centered slides.
  • Peek next slides: None, Both sides, Left or Right, with Peek width. “Leaves room at the side so part of the next slide shows.”
  • Effect: Slide, Fade (one slide at a time) or Coverflow.
  • Keyboard navigation and Mouse wheel.
Section titled “Navigation”
  • Arrows (on by default), with Arrows position (Inside, Outside or Below), Previous arrow icon and Next arrow icon (SVG uploads only), and Hide arrows on mobile (“Below 768px, where swiping is the usual way to move.”).
  • Pagination: None, Dots, Fraction (1 / 5) or Progress bar, with Pagination position (Inside or Below).

Style

Section titled “Style”

Items, Active slide (a scale for the centered slide, shown with centered slides and the Slide effect), Arrows, Pagination and Nothing found.

The blocks

Section titled “The blocks”

The blocks have the same query sources and options in the block sidebar, grouped in panels: Loop Item, Query, then for the grid Layout and Pagination, and for the carousel Slides, Navigation and Behaviour, plus Additional (Nothing found message and Loop id (keeps page links stable)). Per-device values are separate settings, for example Columns (tablet) and Slides per view (mobile). The block editor shows a live server-side preview.

A few options exist only in the Elementor widgets: the arrow SVG uploads, Auto (card width) slides per view (the block takes numbers), the Style tab sections and Pro alternate templates.

Responsive behaviour

Section titled “Responsive behaviour”

Responsive values are desktop, tablet and mobile only. The carousel switches at fixed breakpoints (768 and 1025 px), so on a site with custom Elementor breakpoints its responsive values can differ from what the editor shows.

Nested loops

Section titled “Nested loops”

A card can contain another Loop Grid or Loop Carousel, for example a small related-posts row inside each post card. Each loop keeps its own settings and pages independently, even when identical loops repeat in many cards, and one loop’s styles never reach a loop nested inside it.

When AJAX pagination (AJAX numbers, load more or infinite scroll) brings in more cards, a loop nested in those new cards shows its first page without pagination, and a nested Current query loop shows its empty state, because the loading request has no archive to follow.

Alternate templates (Pro)

Section titled “Alternate templates (Pro)”

Pro adds Alternate templates to the Loop Grid widget: show a different Loop Item at chosen positions, for example a wide promotional card every third item. Each rule has:

  • Loop Item: the other published Loop Item to show.
  • Position: “Counting from the first card in the grid.” 1 to 100, default 3.
  • Repeat: “On: every multiple of the position. Off: that one card.” On by default.
  • Column span: 1 to 6. “Wider spans are capped at each device’s column count. On mobile a wide card takes one column.”

Rules apply in order and the last matching rule wins. With numbered or previous/next pagination every page starts again at position 1; with load more and infinite scroll the count carries on across the whole grid. If First item spans is above 1 and a rule targets position 1, the first-item span wins.

Carousels and the blocks have no alternates. On free the section shows a note instead of the rules.

Build a loop over MCP

Section titled “Build a loop over MCP”

The 9 Themer tools handle the Loop Item; the ordinary widget and block tools place the grid.

  1. Create the Loop Item with create-theme-template, type: "loop" and an optional preview:

    create-theme-template(
      title   = "Post card",
      type    = "loop",
      preview = { post_type: "post", post_id: 0, width: 400 }
    )
    # -> { template_id: 941, type: "loop", is_part: true, preview: {...} }

    It is created published. Change the preview later with update-theme-template. list-theme-templates with type: "loop" lists Loop Items. set-template-conditions refuses a Loop Item with loop_takes_no_conditions: conditions belong on the template that contains the grid.

  2. Build the card with the Gutenberg or Elementor tools against the returned template_id.

  3. Place the grid or carousel. In Elementor use add-free-widget with emcp-loop-grid or emcp-loop-carousel (both are in the curated widget catalog, category themer). Select values are strings (emcp_template_id: "941", emcp_columns: "3"), switchers are "yes" or "", and term references are taxonomy:term_id such as "category:3".

    In the block editor use add-block:

    add-block(post_id = 312, markup = '<!-- wp:emcp/loop-grid {"templateId":941,"source":"posts","postTypes":["post"],"perPage":9,"terms":["category:3"],"columns":3,"columnsTablet":2,"pagination":"numbers","ajax":true} /-->')

The setting names differ between the builders (emcp_per_page in the widget, perPage in the block; emcp_load_type: "ajax" in the widget, "ajax":true in the block). Call get-widget-schema with widget_type: "emcp-loop-grid" and full: true, or get-block-schema with name: "emcp/loop-grid", before writing settings.

Section titled “Related”