PHPFront logo
v1.0.0 now
PHPFront Online Documentation now available! PHPFront is available on Composer: composer require ox-harris/phpfront Contact us to place an ad here...

Repeats

When you supply an indexed array (array with numeric keys) as $data to an element, you are targeting its children. Now, where the number of items in $data exceeds the number of children in element, PHPFront will repeat a child (or all the children) one or more times to fully render data.

Intrestingly, you can even affect the repeat behaviour to create patterns and grids. That is what this chapter covers.

PHPFront implements Repeat-Last by default. So you do not always need to bother yourself with repeat functions.

Compare Auto Population and Associative Population in the chapter Assigning Data.

Understanding Repeats

Concepts

Let us first explain the key terms, using the sample HTML table below. 

    
    
      <!-- Colours Table -->
      <table id="users_table">
        <tr class="row-1"><td></td></tr>
        <tr class="row-2"><td></td></tr>
        <tr class="row-3"><td></td></tr>
      </table>
  • X-Axis – the line-up of direct children of the element. In this case, we have <tr> elements on this aixs
  • Y-Axis – the line-up of children in each direct child of the element - the element's grand-children. In this case, we have <td> on this aixs
  • Repeat-Function (Repeat-Fn) – the particular algorithm or pattern to follow when repeating on the X or Y axis.
    • Repeat-Function-X (Repeat-Fn-X) - for repeating on the X axis
    • Repeat-Function-Y (Repeat-Fn-Y) - for repeating on the Y axis
  • Modifier - a keyword added to a function to modify its behaviour.

Below, we will describe the behavior of each function with their respective modifiers.
We will also be using the #users_table table for most of the examples that follow. (Some examples may ommit the <td> childnodes for simplicity.)

In the examples below, the #users_table has 3 <tr> childnodes, but an array of 9 rows of content has been supplied.

Repeat-First

Description: Simply repeat the first element next to itself as many times as needed.
Modifiers: none

In the result below, the first row .row-1 is what is repeated. 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-1">...</tr>
          <tr class="row-1">...</tr>
          <tr class="row-1">...</tr>
          <tr class="row-1">...</tr>
          <tr class="row-1">...</tr>
          <tr class="row-1">...</tr>
          
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
        </table>

Repeat-Last

Description: Simply repeat the last element next to itself as many times as needed.
Modifiers: none

In the code below, the last row .row-3 is what is repeated. 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          
        </table>

Repeat-Middle

Description: Simply repeat the middle element next to itself as many times as needed.
Modifiers: Left

In the example below, the exact middle row .row-2 is what is repeated. 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          
          <tr class="row-3">...</tr>
          
        </table>

Where the total number of existing elements is even, there will be two elements at the exact middle point. PHPFront picks the right-most element, by default. The modifier, left, is used to choose the left-most element.

Repeat-Nth

Description: Simply repeat the element at the specified nth position next to itself as many times as needed.
Modifiers: none

In the example below, our repeat function is repeat_nth(2). This uses .row-2 as the repeat element. 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-2">...</tr>
          
          <tr class="row-3">...</tr>
          
        </table>

Repeat-All

Description: Repeat all existing elements as a set, and as many times as needed.
Modifiers: Alternate, Once

In the example below, our repeat function is repeat-all. Notice that the set of original rows is what is repeated. 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
        </table>

With the modifier alternate: 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-3">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-1">...</tr>
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
        </table>

With the modifiers alternate,once: 

      
      
        <!-- Colours Table -->
        <table id="users_table">
          
          <tr class="row-1">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-3">...</tr>
          
          <!-- REPEATED ELEMENTS -->
          
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          <tr class="row-3">...</tr>
          
          <tr class="row-3">...</tr>
          <tr class="row-2">...</tr>
          <tr class="row-1">...</tr>
          
        </table>

Setting Repeat Functions

Globally

The PHPFront::setRepeatFunctions() function is used to set the general functions for all repeats. 

      
        
        PHPFront::setRepeatFunctions($repeat_fn[, $repeat_fn_y]);

This function accepts one required parameter:
$repeat_fn - a repeat function name.
Then there is one optional parameter:
$repeat_fn_y - a repeat function name specifically for use on the y-axis. If not specified, $repeat_fn is used.

Repeat-function names are given as strings and are case-insensitive. Modifiers are added with comma-separations: repeat_fn,modifier.

Set repeat functions to null (empty sting) to disable repeats.

Locally on Elements

Repeat functions can be included in Compound Arguments assigned to elements. It will be specified in the @params list of runtime parameters.
This will override the global repeat function on the target element. 

      
        
        PHPFront::assign($element_selector, array('@params' => array('repeat_fn' => $repeat_fn[, 'repeat_fn_y' => $repeat_fn_y])));

See the Chapter Adding Special Rendering Attributes on setting this runtime property on element attributes.

Grids and Patterns

A grid is an arrangement of elements on the X and Y axis. PHPFront can help you automatically create grids - both large and small - all from one or two initial elements. And it sees this as a very small task. You could even define the pattern you want using any of the repeat functions and their modifiers.

Let us create a grid using the dry HTML table: #users_table. (Assume that it now has 4 rows and 3 columns. We have also added different levels of opacity on all 4 rows so you can recognize rows easily, because the order in which they appear will not always be the same. [Check the source]) We are going to pull data from the database table named Users and assign it to our HTML table as-is, without having to loop over the array.


The HTML table named '#users_table' (Show Source) 
      
      
        <! - - Colours Table - - >
        <table class="test_table" style="width:35%">
          <tr class="row-1" style="opacity:0.45"><td style="background-color:lavender"></td><td style="background-color:lavenderBlush"></td><td style="background-color:pink"></td></tr>
          <tr class="row-2" style="opacity:0.65"><td style="background-color:lavender"></td><td style="background-color:lavenderBlush"></td><td style="background-color:pink"></td></tr>
          <tr class="row-3" style="opacity:0.85"><td style="background-color:lavender"></td><td style="background-color:lavenderBlush"></td><td style="background-color:pink"></td></tr>
          <tr class="row-4" style="opacity:1"><td style="background-color:lavender"></td><td style="background-color:lavenderBlush"></td><td style="background-color:pink"></td></tr>
        </table>

PHP Code (Show Database)
Database Table named 'Users'
Id First_name Last_name Username Age Gender Country City
1 John Doe johndoe 25 Male USA Unknown
2 Michael Sanderson msand 35 Male CANADA Unknown
3 Daniel Sway dansway 45 Male USA Unknown
4 John Spoon johndoe 55 Male BRAZIL Unknown
5 John2 Doe johndoe2 30 Male USA Unknown
6 Michael2 Sanderson2 msand2 40 Male CANADA Unknown
7 Daniel2 Sway2 dansway2 50 Male USA Unknown
8 John2 Spoon2 johndoe2 60 Male BRAZIL Unknown 
    
      
      // Get data from this table with the PDO class (PHP Database Object) instantiated somewhere in our app.
      // Fetch all rows
      $query = $this->PDO->query('SELECT id, first_name, last_name, username, age, gender, country, city FROM users');
      $data = $query->fetchAll();
      
      // We set a global repeat function
      $PHPFront->setRepeatFunctions('repeat-all,alternate');
      
      // We assign $data to our table element
      $PHPFront->assign('#users_table', $data);

Result (Show Source)

With repeat_fn_x: repeat-all,alternate, repeat_fn_y: repeat-all,alternate: 

      
      
        <! - - Colours Table - - >        
        <table id="users_table" class="test_table" style="color:white">
          <tr class="row-1" style="opacity:0.45"><td style="background-color:lavender">1</td><td style="background-color:lavenderBlush">John</td><td style="background-color:pink">Doe</td><td style="background-color:pink">johndoe</td><td style="background-color:lavenderBlush">25</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">USA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-2" style="opacity:0.65"><td style="background-color:lavender">2</td><td style="background-color:lavenderBlush">Michael</td><td style="background-color:pink">Sanderson</td><td style="background-color:pink">msand</td><td style="background-color:lavenderBlush">35</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">CANADA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-3" style="opacity:0.85"><td style="background-color:lavender">3</td><td style="background-color:lavenderBlush">Daniel</td><td style="background-color:pink">Sway</td><td style="background-color:pink">dansway</td><td style="background-color:lavenderBlush">45</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">USA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-4" style="opacity:1"><td style="background-color:lavender">4</td><td style="background-color:lavenderBlush">John</td><td style="background-color:pink">Spoon</td><td style="background-color:pink">johnspoon</td><td style="background-color:lavenderBlush">55</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">BRAZIL</td><td style="background-color:lavenderBlush">Unknown</td></tr>
    
          <tr class="row-4" style="opacity:1"><td style="background-color:lavender">5</td><td style="background-color:lavenderBlush">John2</td><td style="background-color:pink">Doe2</td><td style="background-color:pink">johndoe2</td><td style="background-color:lavenderBlush">30</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">USA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-3" style="opacity:0.85"><td style="background-color:lavender">6</td><td style="background-color:lavenderBlush">Michael2</td><td style="background-color:pink">Sanderson2</td><td style="background-color:pink">msand2</td><td style="background-color:lavenderBlush">40</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">CANADA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-2" style="opacity:0.65"><td style="background-color:lavender">7</td><td style="background-color:lavenderBlush">Daniel2</td><td style="background-color:pink">Sway2</td><td style="background-color:pink">dansway2</td><td style="background-color:lavenderBlush">50</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">USA</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        
          <tr class="row-1" style="opacity:0.45"><td style="background-color:lavender">8</td><td style="background-color:lavenderBlush">John2</td><td style="background-color:pink">Spoon2</td><td style="background-color:pink">johnspoon2</td><td style="background-color:lavenderBlush">60</td>    <td style="background-color:lavender">Male</td><td style="background-color:lavender">BRAZIL</td><td style="background-color:lavenderBlush">Unknown</td></tr>
        </table>
1 John Doe johndoe 25 Male USA Unknown
2 Michael Sanderson msand 35 Male CANADA Unknown
3 Daniel Sway dansway 45 Male USA Unknown
4 John Spoon johnspoon 55 Male BRAZIL Unknown
5 John2 Doe2 johndoe2 30 Male USA Unknown
6 Michael2 Sanderson2 msand2 40 Male CANADA Unknown
7 Daniel2 Sway2 dansway2 50 Male USA Unknown
8 John2 Spoon2 johnspoon2 60 Male BRAZIL Unknown

With repeat_fn_x: repeat-all,alternate, repeat_fn_y: repeat-first:

1 John Doe johndoe 25 Male USA Unknown
2 Michael Sanderson msand 35 Male CANADA Unknown
3 Daniel Sway dansway 45 Male USA Unknown
4 John Spoon johnspoon 55 Male BRAZIL Unknown
5 John2 Doe2 johndoe2 30 Male USA Unknown
6 Michael2 Sanderson2 msand2 40 Male CANADA Unknown
7 Daniel2 Sway2 dansway2 50 Male USA Unknown
8 John2 Spoon2 johnspoon2 60 Male BRAZIL Unknown

With repeat_fn_x: repeat-all, repeat_fn_y: repeat-last:

1 John Doe johndoe 25 Male USA Unknown
2 Michael Sanderson msand 35 Male CANADA Unknown
3 Daniel Sway dansway 45 Male USA Unknown
4 John Spoon johnspoon 55 Male BRAZIL Unknown
5 John2 Doe2 johndoe2 30 Male USA Unknown
6 Michael2 Sanderson2 msand2 40 Male CANADA Unknown
7 Daniel2 Sway2 dansway2 50 Male USA Unknown
8 John2 Spoon2 johnspoon2 60 Male BRAZIL Unknown

With repeat_fn_x: repeat-all, repeat_fn_y: repeat-middle:

1 John Doe johndoe 25 Male USA Unknown
2 Michael Sanderson msand 35 Male CANADA Unknown
3 Daniel Sway dansway 45 Male USA Unknown
4 John Spoon johnspoon 55 Male BRAZIL Unknown
5 John2 Doe2 johndoe2 30 Male USA Unknown
6 Michael2 Sanderson2 msand2 40 Male CANADA Unknown
7 Daniel2 Sway2 dansway2 50 Male USA Unknown
8 John2 Spoon2 johnspoon2 60 Male BRAZIL Unknown

Summary

  • Repeat will take place when an indexed array is assigned to target an element's children and when the items in the array outnumbers the children.
    • ,
  • Repeat Functions can be set globally with the PHPFront::setRepeatFunctions() function; and locally on individual elements by including it in the @params list of Compound Arguments assigned them. Recall
  • There are six repeat functions: repeat-first, repeat-last, repeat-middle, repeat-nth, repeat-all, and shuffle-data.

We've done a very nice job covering this chapter!

Back to Working with PHPFront

See Also