In this tutorial, we’re going to dive a little bit deeper into what the repeater element is in Oxygen, and how to use it.
Alright, so let’s get started. Well first set up a simple reusable part in Oxygen.
Step 1 – Navigate to Oxygen > Templates, and click on Add New Reusable Part. Give it a name, something like ‘reusable test part’. Unless you’re creating something else that’s specific, such as a ‘blog archives element’. Then publish your new reusable part and then click on Edit With Oxygen.
Step 2 – Once the editor has loaded, add a new section, followed by the repeater element. Now let’s dive into the repeater element.
The repeater element is one of my favorite elements in Oxygen. It is a powerful component that let you create looped content, by using a post query, hence the name repeater.
In its basic form, the repeater element consists of a single div as the child element. Let’s select the repeater in the structure panel and head over to Primary.
Here we have a number of options. Let’s start with Query since this is at the heart of the repeater’s features.
Query Options
The default is the normal setting and is most commonly used. But we can also choose custom, manual, and advanced. We’ll briefly look at each one.
1. Custom
Custom is also a frequently used query option, it allows you to control a number of parameters as outlined below –
- Post type – Here we can select post or page, etc. Most often we’ll use post or page. Or we can manually specify the IDs of posts and pages (click here to learn how to find a post or page’s ID). IDs are ideal if you want to create a repeater to display specific posts or pages. For example, perhaps you’re building a featured content section for your homepage.
- Filtering – Under filtering, you can display posts or pages to appear in a specific category, tag, WooCommerce product category, tags, etc. You can also filter by author.
- Order – Under the order, you can display posts or pages by date, date last modified, title, comment, count, menu order, and more.
- Count – Under the count option, you can select how many posts or pages you want to have displayed in the repeater.
2. Manual
Manual allows you to add query parameters manually. It requires a little bit of advanced knowledge. The default is what you see in the parameter field.
author_name=admin&category_name=uncategorized&posts_per_page=2
If you’re familiar with WP Query, you can edit this parameter, or you should check out https://developer.wordpress.org/reference/classes/wp_query/ for more examples and usage.
3. Advanced
This feature is for more advanced users and WordPress Devs. That said, there are some presets built in that you can use.
The query editor, again an advanced feature, lets you build custom queries from scratch. We have some beginner-friendly tutorials on creating specific queries using the query builder here.
Going back to the Primary Options, we can also customize –
Layout
Here we can set the layout of our repeater elements. In most cases, you would leave this to vertical. However, on occasions that you might use horizontal would be if you’re trying to create a table using the repeater.
Pagination
If you’re trying to create a post archive using the repeater element, the pagination options let you customize the function, look, and style of the pagination.
Grid Layout
The grid layout option lets you specify the number of columns you would like to use, as well as set widths, alignments, rows, etc.
Preview Render
This option is useful if you need to boost the performance of your page. You don’t always need to preview all of the items in the repeater. Enabling single mode will only render the div you’re working on.