Loop

Loop Helpers

These are a collection of plugin methods meant to ease usage of loops or implement specific kinds of loops,

Halfway

The is_halfway method checks to see if you are halfway through an expressionengine looping tag pair. For it to work, it needs to be provided the {count} and {total_results} or equivalent tag pair variables within the loop. Internally, it is merely checking if an integer is halfway rounded up through the total.

Return Value

A boolean in the form of either the string y for true, or n for false.

Usage Example

{exp:channel:entries channel="some_channel"}
	{if '{exp:surgeree:is_halfway count="{count}" total="{total_results}"}' == 'y'}
		<!-- This entry marks the halfway point of this loop. -->
	{/if}
{/exp:channel:entries}

Years

A looping tag returning all of the years for which there are entries. Very useful for generating archive links based on calendar year. This tag pair will only produce output once for each year in which an entry exists for a given channel.

Parameters

• exclude_current_year: The string 'y' or 'n', determining whether or not the current date's year is excluded from output.
  • Default: 'n'
• channel: Which channel to inspect.
• status: Statuses of entries to restrict the search to, pipe (|) separated. For instance, if only closed entries exist for 2010, and status="open" is declared, 2010 will not appear in the output.
  • Default: All statuses.

Tag Pair Variables

• {year} is the full 4-digit string representation of a year for which entries exist.

Usage Example

Given a channel "blog" with 1 entry from 2008, 4 entries from 2010, 3 from 2011, the following snippet

{exp:surgeree:years channel="blog"}
	<li>{year}</li>
{/exp:surgeree:years}

will output:

<li>2008</li>
<li>2010</li>
<li>2011</li>

Loop

Essentially a for loop implementation allowing you to simply output some string a set number of times. Increment has a different meaning, and will essentially integer divide the number of iterations to determine the actual number of iterations. This is useful when you know you want to do that integer division but don't want to calculate it in the template.

Parameters

• iterations: The number of iterations desired, of which the final iterations will be divided by the increment.
• increment: The number by which to increase the iteration counter after each loop. This is really only useful if you know you are going to be passing a value to iterations that you wish you be cut in half, for example.

Tag Pair Variables

• {current}: The current iteration of the loop. Note that this will always increase by 1 for every completed loop, starting with 1. The increment parameter has no effect here.
• {total}: The total number of times the loop will iterate. Note that this is the actual number of iterations the loop will go through, not the raw value of iterations.

Usage Example

The following snippet

{exp:surgeree:loop iterations="8" increment="4"}
	{current} - {total}
{/exp:surgeree:loop}

will produce:

1 - 2
2 - 2

Loop Fill

A loop designed to allow padding of a parent loop based on what number you want to make the parent's total divisible by.

Parameters

• total: The total number of rows that have been output. This will typically be {total_results} or the equivalent.
• make_divisible_by: This is the number to make the total rows + rows output by this tag pair divisible by. If you want the output never to be odd, this might be 2.

Tag Pair Variables

• {current}: Equivalent of {count} for this tag pair.
• {total}: Equivalent of {total_results} for this tag pair.

Usage Example

In the following snippet, a carousel is being populated with slides from a matrix field, but needs to output dummy slides to make the number of slides in each page of the carousel equal.

{some_matrix_field}
<!-- Slide content -->
	{if row_count == total_rows}
		{exp:surgeree:loop_fill total="{total_rows}" make_divisible_by="10"}
			<!-- Dummy/filler slide content -->
		{/exp:surgeree:loop_fill}
	{/if}
{/some_matrix_field}

Inside the matrix field, we place an if statement to detect when the end of the matrix loop has been reached. We then pass the total number of rows the matric field output to the loop-fill plugin method, telling it to fill append additional content until the total number of slides is divisible by ten. If the matrix field outputs 13 slides, the above will output 7 dummy slides, making the total 20.