data:repeater
AJAX
ajax:delayedload ajax:event ajax:navigation ajax:region
Data
data:calendar data:column data:eventrepeater data:postrepeater data:productbrandrepeater data:productcategoryrepeater data:productrepeater data:repeater
DESCRIPTION
ATTRIBUTES
as
classRow
dataFilter
dataGroupBy
dataJoins
dataLimit
dataOrder
dataSearch
dataSourceSupportsOrdering
dataSourceSupportsPaging
dataStart
emptyMessage
exportable
height
id
keyAs
paging
pagingRows
populateAt
width
onPopulateServer
EXAMPLES
Linking with PHP
Linking with Components
Debugging the data
DataStart and DataLimit Attributes
DataFilter Attribute
DataOrder Attribute
data:table data:template data:tree
Forms
forms:address forms:captcha forms:checkbox forms:checkboxgroup forms:codeeditor forms:combobox forms:datepicker forms:dialogbox forms:editbox forms:fileupload forms:form forms:hidden forms:money forms:officeuseregion forms:option forms:password forms:paymentmethod forms:radiobutton forms:radiobuttongroup forms:row forms:searchbox forms:signature forms:slider forms:spinbox forms:submitbutton forms:submitimage forms:submitlink forms:successcontent forms:textarea forms:timepicker
Layout
layout:gallery layout:productgallery layout:rotator layout:stepper layout:stepperpanel layout:tablist layout:tablistitem
Logic
logic:dependency logic:else logic:if logic:include logic:parse logic:variable
Navigation
navigation:breadcrumbs navigation:item navigation:primary navigation:secondary
Personalisation
personalisation:firstname personalisation:fullname personalisation:lastname personalisation:other
Standard
standard:audio standard:embed standard:icon standard:image standard:link standard:script standard:tooltip standard:video
Templates
templates:button templates:card templates:column templates:fancybox templates:faq templates:flexlayout templates:header templates:row templates:section templates:styles templates:teammember templates:testimonial
Regions
regions:content regions:contentadditional regions:security regions:togglable
Third Party
thirdparty:googlemap thirdparty:googlemapmarker

<data:repeater> </...>

Repeaters are similar to a foreach loop.
Allows iteration over a set of data, rendering HTML.

Related Tutorials

Content

any
Defines the template for each repetition of the repeater. Access the datasource content through the variable named in the as attribute to render the content in the datasource.

Attributes

as
string
The name of the variable to be registered for each row. For example, as="myvar" will let you reference $myvar inside the control.
classRow
string
The CSS class for rows (<tr> tags).
dataFilter
array
A Filter Array, if datasource is a function that supports a Query Array.
dataGroupBy
array
An array of fields to group by, if datasource is a function that supports a Query Array.
dataJoins
array
Array of tables to join with, if datasource is a function that supports a Query Array.
dataLimit
int
The maximum number of results to return, if datasource is a function that supports a Query Array.
dataOrder
array
Sets the order by which the data is sorted

The parameter is a two-dimensional array consisting of column names and the direction of the order.

For example, the following would sort contacts by their last name ascending and in the event of two contacts having the same last name, their first name descending

[['contact_last_name', 'asc'], ['contact_first_name', 'desc']]
dataSearch
string
Filter results if they match this string, if datasource is a function that supports a Query Array.
dataSourceSupportsOrdering
bool
Sets whether the DataSource supports the order parameter.

When set to true, an order parameter will be appended to the data. The order parameter is an array containing values similar to: [['contact_id', 'desc'], ...].
dataSourceSupportsPaging
bool
Sets whether the DataSource supports the paging parameters.

When set to true, two parameters will be appended to the call to the DataSource which represent the start and limit values of pagination.
dataStart
int
The number of results to skip, if datasource is a function that supports a Query Array.
emptyMessage
string
The message shown when there are no rows in the data control.
exportable
bool|string
If true, an 'Export Data' link will appear beneath the control which will save a CSV file to the client of all the data in the control. Default = false.
height
string
Height

Sets the height of the element. The default units are pixels. include the percentage symbol % to user percentage values.
id
string
Give this control a unique id. Can be accessed in the client DOM (eg, document.getElementById('myid') or in the server DOM using [? $myid ?] or [? $('myid') ?]).
keyAs
string
The name of the variable to be registered for each row's key.
For arrays of entities from the database (for example getAll()), the keys will be incrementing integers starting at 0.
paging
bool
Whether to enable paging for this control. With paging enabled, the initial number of results will be limited to the value of pagingrows, and a 'Show More' button will appear.
Each click of the button will append pagingrows more rows. Default = false.
pagingRows
int
Use in conjunction with paging, to control the initial number of rows to be shown, and the number of rows loaded when 'Show More' is clicked. Default = 25.
populateAt
string
Sets when to populate from the datasource. Not required for most tasks, but can resolve timing issues on very complicated pages.
Default = 'init'. Other possible values: 'render'.
width
string
Width

Sets the width of the element. The default units are pixels. include the percentage symbol % to user percentage values.
onPopulateServer
callable
Called after the data control has populated from the datasource / component

Tutorials


Dynamic navigation which is populated with post articles.

This article explains how to create dynamic navigation which is automatically populated by post articles. This can be useful for creating small sidebar menus of recent posts, or footer navigation which lists post article titles.

How it Works

The navigation will be populated with the titles of all post articles of a certain post category. The <data:repeater> will be used to retrieve the post articles, with the data source being set to a call to the Oncord API. The <data:repeater> is similar to a for loop which will repeat everything inside the tag until there are no more items left to return from a data source.  

Basic Implementation

  • Navigation code
  • Preview
  • CSS styling
<div class="sideBar"> <h4 class="title"><a href="/blog/">Blog</a></h4> <ul> <data:repeater as="post" datalimit="4" datasource="\Components\Website\Posts::getAllForCategory(1)"> <li><a href="[? $post['post_content_url'] ?]">[? $post['post_title'] ?]</a></li> </data:repeater> </ul> </div>

The Data Repeater

The data repeater specified above uses the following attributes, for a list of all attributes please see the API here.

as="post" - This attribute determines the name of the variable to be registered for the repeating element. In this case the variable has been given the name "post" and is therefore referenced as $post.

datalimit="4" - This attribute defines the maximum number of rows the data repeater will return. In this case it was decided that there needed to be a maximum of four articles displayed.

datasource="\Components\Website\Posts::getAllForCategory(1)" - This attribute defines the data source of the repeater. In this example all articles where the category id=1 will be returned. To find a post category id navigate to the post categories page of the dashboard, then click a category to open the category edit page. On this page there is a tab labelled "Developer Info", which lists the post category ID.

<div class="sideBar"> <logic:variable as="categoryName" value="[? \Components\Website\Posts\Categories::get(1) ?]" /> <h4 class="title"><a href="[? $categoryName['page_id'] ?]">[? $categoryName['post_category_title'] ?]</a></h4> <ul> <data:repeater as="post" datalimit="4" datasource="\Components\Website\Posts::getAllForCategory(1)"> <li><a href="[? $post['post_content_url'] ?]">[? $post['post_title'] ?]</a></li> </data:repeater> </ul> </div>

When loading a large amount of data, instead of increasing page load time you can opt to display a "Show More" button.

Pagination is a technique used to assist in loading and displaying a large amount of data. The best known example of pagination is used on Google: 

As of March 2016, Oncord no longer supports pagination. Instead, a "Show More" button is displayed which reveals more content:

Click here to view the media release for the positives of this approach.

To implement this feature, you can simply add the attribute paging="true" to a <data:repeater> tag, and pagingrows="5" to control the number of elements to display before displaying the "Show More" button.

An Example: Posts

The following code is used to display a list of Posts associated with a Post Category:

<data:repeater datasource="\Components\Website\Posts::getAllForCategory(1)" as="post"> <data:template component="\Components\Website\Posts" templatetype="list" /> </data:repeater>

Introduce the Show More button by adding the attributes  paging="true" and pagingrows="5" to the <data:repeater> tag as shown below:

<data:repeater paging="true" pagingrows="5" datasource="\Components\Website\Posts::getAllForCategory(1)" as="post"> <data:template component="\Components\Website\Posts" templatetype="list" /> </data:repeater>

The Data Repeater

The data repeater specified above uses the following attributes, for a list of all attributes please see the API here;

as="post" - This attribute determines the name of the variable to be registered for the repeating element. In this case the variable has been given the name "post" and is therefore referenced as $post.

datalimit="4" - This attribute defines the maximum number of rows the data repeater will return. In this case it was decided that there was no need to have a maximum number of posts, so it was left out.

datasource="\Components\Website\Posts::getAllForCategory(1)" - This attribute defines the data source of the repeater. In this example all articles where the post category id=1 will be returned. To find a post category id, navigate to the post categories page of the dashboard, and then click a category to open the category edit page. On this page there is a tab labelled "Developer Info", which lists the post category ID.

paging="true" - This attribute enables the "Show More" paging feature.

pagingrows="5" - This attribute defines the number of rows to display before displaying the "Show More" button.



    Oncord's UI Controls API includes a pre-built rotator, which helps reduce development time, while providing users with an improved experience updating content via the visual editor.  

    Some notable features of the Oncord rotator:

    • May be placed and configured via the visual page editor. 
    • Supports html content and other Oncord UI controls such as sections, not just images. 
    • Supports YouTube videos, where videos are stopped between slides.
    • Customize the rotator controls with your own images or icons.
    • Supports responsive content. 
    • Customize the transition time and effect to be used between slides (slide or fade). 
    • Show multiple content items per slide (eg. 4 testimonials per slide). 

    Introducing The Rotator UI Control


    You can add a rotator to a website page or design through use of the <layout:rotator> UI Control.

    Alternatively, a rotator can be added to the page via the visual editor. Click "Insert" on the left-hand side of the screen while editing a website page, and drag-and-drop a "Rotator" element into position on the page.

    In order to take advantage of all the features and possibilities of the rotator UI control, take note of all the "Attributes" available in the API reference here. 

    The <layout:rotator> control can handle any standard content. Each direct child of the rotator will be turned into its own slide.

    <layout:rotator id="featured_rotator"> <standard:image width="100%" height="500" maintainaspect="crop" src="https://images.unsplash.com/photo-1543575172-e1033f739205?ixid=Mnw2ODg1fDB8MXxzZWFyY2h8NXx8YWJzdGFjdHxlbnwwfHx8fDE2MzE1MTQxMjQ&" /> <standard:image width="100%" height="500" maintainaspect="crop" src="https://images.unsplash.com/photo-1544438825-f1222acc39dc?ixid=Mnw2ODg1fDB8MXxzZWFyY2h8Mjd8fGFic3RhY3QlMjBzbGlkZXxlbnwwfHx8fDE2MzE1MTQyMTg&" /> </layout:rotator>

    Custom Next / Previous Links


    The rotator includes standard next / previous controls, however you can alternatively add custom links instead.

    Place your custom navigation elements within links that are assigned with unique IDs.

    Add the attributes moveNextId and movePreviousId to the <layout:rotator> control, where the IDs that you provide correlate to the IDs used by your next / previous buttons. 

    Set the attributes arrowVariant="none" minimapVariant="none", to remove Oncord's default rotator navigation elements.

    • HTML
    • CSS
    <div class="banner"> <layout:rotator id="featured_rotator2" movenextid="featured_rotator_next" movepreviousid="featured_rotator_previous" arrowVariant="none" minimapVariant="none"> <standard:image width="100%" height="500" maintainaspect="crop" src="https://images.unsplash.com/photo-1543575172-e1033f739205?ixid=Mnw2ODg1fDB8MXxzZWFyY2h8NXx8YWJzdGFjdHxlbnwwfHx8fDE2MzE1MTQxMjQ&" /> <standard:image width="100%" height="500" maintainaspect="crop" src="https://images.unsplash.com/photo-1544438825-f1222acc39dc?ixid=Mnw2ODg1fDB8MXxzZWFyY2h8Mjd8fGFic3RhY3QlMjBzbGlkZXxlbnwwfHx8fDE2MzE1MTQyMTg&" /> </layout:rotator> <!-- Buttons for changing between different slides --> <div class="rotatorNavigation"> <span class="leftArrow"> <a id="featured_rotator_previous" href="#"><standard:icon library="fontawesome" iconstyle="solid" iconname="chevron-left" size="4" style="width: 50px; height: 50px; color: #FFFFFF" /></a> </span> <span class="leftArrow"> <a id="featured_rotator_next" href="#"><standard:icon library="fontawesome" iconstyle="solid" iconname="chevron-right" size="4" style="width: 50px; height: 50px; color: #FFFFFF" /></a> </span> </div> </div> </templates:section>

    Logic is used to show content based on a test. Repeaters are used to list elements like Products, Pages, or Contacts.

    Logic IF

    The <logic:if> control performs a test, and renders everything inside the tag if the test is true. The test is defined within the test="true" attribute, and is often an API call.  

    The following examples are usually defined in the website design to show content dynamically: 

    IF the current visitor is logged in, show "you are logged in".

    <logic:if test="\Components\Customers\Contacts::currentIsLoggedIn()"> <p>You are logged in.</p> </logic:if>


    IF the current page is the "About Us" page, show a heading.

    <logic:if test="\Components\Website\Pages::currentPageId() == '/about-us/'"> <h2>About Us</h2> </logic:if>

    Logic ELSE

    The <logic:else> control defines an alternate region to show in the case that an IF test fails. Extending the above examples: 

    IF the current visitor is logged in, show "you are logged in".
    ELSE show "You are not logged in":

    <logic:if test="\Components\Customers\Contacts::currentIsLoggedIn()"> <p>You are logged in.</p> </logic:if> <logic:else> <p>You are not logged in.</p> </logic:else>


    IF the current page is the "About Us" page, show a heading.
    ELSE show a message "Another Page".

    <logic:if test="\Components\Website\Pages::currentPageId() == '/about-us/'"> <h2>About Us</h2> </logic:if> <logic:else> <h2>Another Page</h2> </logic:else>


    The ELSE tag must be defined after an IF tag. 

    You can add additional Else tags with test conditions to be checked if the previous test fails:

    <logic:if test="\Components\Website\Pages::currentPageId() == '/about-us/'"> <h2>About Us</h2> </logic:if> <logic:else test="\Components\Website\Pages::currentPageId() == '/services/'"> <h2>Services</h2> </logic:else> <logic:else> <h2>Another Page</h2> </logic:else>

    Loops: The Data Repeater Control

    <data:repeater> is commonly used to list elements like Products, Pages, or Contacts.

    The Data Repeater repeats everything inside the tag, for each item in a given data source.

    The "as" attribute defines the name of the variable, and the "datasource" attribute usually defines an API call to retrieve a Page, Product or Contact.

    The following example will list all Posts:

    <data:repeater as="post" datasource="\Components\Website\Posts::getAll()"> <h1>[? $post['post_title'] ?]</h1> [? $post['post_content_short'] ?]; </data:repeater>


    Or, to show all contacts in a specific Group:

    <data:repeater as="contact" datasource="\Components\Customers\Groups::getContactsInGroup('/group-id-here/')"> <h1>[? $contact['contact_first_name'] ?]</h1> </data:repeater>

    DataLimit and DataStart Attributes 

    The DataLimit attribute can be used to limit the number of records displayed. For example, you may wish to only show three Posts: 

    <data:repeater as="post" datalimit="3" datasource="\Components\Website\Posts::getAll()"> <h1>[? $post['post_title'] ?]</h1> [? $post['post_content_short'] ?]; </data:repeater>


    The DataStart attributes may be used in addition to the DataLimit attribute to show from a record, to a record. As an example, the following code will only show all Posts, starting at the Third Post:

    <data:repeater as="post" datastart="2" datasource="\Components\Website\Posts::getAll()"> <h1>[? $post['post_title'] ?]</h1> [? $post['post_content_short'] ?]; </data:repeater>


    Note:     DataLimit is an array index, so the first record is at index 0:

    [0 => "First Post"]
    [1 => "Second Post"]
    [2 => "Third Post"]

    Advanced: Ordering & Filtering

    Click here to read more about how to use the DataFilter attribute to filter records (eg. show all products, greater than $100 in value).

    Click here to see an example illustrating how to order records (eg. by value or alphabetically). 

    Examples

    Linking with PHP

    How to call functions in Server Code from the data repeater.

    HTML:

    <data:repeater datasource="getAllItems()" as="item"> [? $item ?]<br /> </data:repeater>

    PHP:

    <?php function getAllItems() { return ['one', 'two', 'three']; } ?>

    Run Example

    Linking with Components

    You can link the data repeater to components within the system to iterate over data. Refer to the documentation of the component for function calls and field names.

    HTML:

    <h1>Posts</h1> <data:repeater datasource="\Components\Website\Posts::getAll()" as="post"> [? $post['post_title'] ?]<br /> </data:repeater> <h1>Post Categories</h1> <data:repeater datasource="\Components\Website\Posts\Categories::getAll()" as="category"> [? $category['post_category_title'] ?]<br /> </data:repeater> <h1>Products</h1> <data:repeater datasource="\Components\Commerce\Products::getAll()" as="product"> [? $product['product_title'] ?]<br /> [?? formatCurrency($product['product_price'] ??] </data:repeater>

    Debugging the data

    You can always output the data contained in the registered variable by using varDump().

    HTML:

    <data:repeater datasource="\Components\Website\Posts::getAll()" as="post"> [? varDump($post) ?] </data:repeater>

    DataStart and DataLimit Attributes

    Allows you to show from a record, to a record. Behaves like the LIMIT clause in SQL.

    HTML:

    <h1>Show the First Post</h1> <data:repeater datasource="\Components\Website\Posts::getAll()" as="post" datalimit="1"> [? $post['post_title'] ?] </data:repeater> <h1>Show the First Three Posts</h1> <data:repeater datasource="\Components\Website\Posts::getAll()" as="post" datalimit="3"> [? $post['post_title'] ?] </data:repeater> <h1>Show the Second and Third Post</h1> <data:repeater datasource="\Components\Website\Posts::getAll()" as="post" datastart="1" datalimit="2"> [? $post['post_title'] ?] </data:repeater> <br /><br /> datastart="1" datalimit="2" behaves the same as SQL's LIMIT 1 2

    DataFilter Attribute

    Allows you to specify conditions in your query. Behaves like the WHERE clause in SQL.

    HTML:

    <h1>Returns all products greater than $100 in value</h1> <data:repeater datasource="\Components\Commerce\Products::getAll()" as="product" datafilter="[? [['product_price_base', '&gt;', 100]] ?]"> [? $product['product_title'] ?] </data:repeater>

    DataOrder Attribute

    Allows you to specify conditions in your query. Behaves like the ORDER clause in SQL.

    HTML:

    <data:repeater datasource="\Components\Website\Posts::getAll()" as="post" dataorder="[? [['post_date', 'desc']] ?]"> [? varDump($post) ?] </data:repeater>