Loop

Package Description

/**

 * Loop

 *

 * A looping snippet that loops through one or more arrays of placeholders to output several chunks at once (or separates with separators). 

 *

 * @author Oleg Pryadko (oleg@websitezen.com)

 * @copyright Copyright 2011, Oleg Pryadko

 * @version 1 - Jan 30, 2011

 * @license GPL (any version)

 *

 * To Do: allow on/ off switch of JSON-style vs. MODx-style arrays separate from the &ph placeholder

 *

 * PARAMETERS

 *

 * &tpl - Name of a chunk serving as a template for the loop

 * [NOTE: if not provided, will use separators instead]

 *

 * &loop - JSON array of values to loop through (with or without placeholders). If loop is left blank, defaults to numbers.

 *

 * &numbers - (boolean). Adds numbers as placeholder values (if loop is set, adds them in addition to existing placeholders).

 * &min - (if using numbers) Number to start with. Default is 0. Can be negative.

 * &max - (if using numbers) Number to end with. Default is 3. Can be negative.

 * &step - (if using numbers) Number to add with every iteration. Default is 1. Can be negative.

 * 

 * &ph (or placeholder) - (optional) single placeholder or comma-separated list of placeholders

 * [IMPORTANT: must be in the same order as &loop statement. If using numbers, put the numbers placeholder last.]

 * &phSimple - &ph alternative - use MODx-style separation in &loop option (option==value||another option==another value)

 *

 * &prefix - Prefix to use before numbers if no placeholder is set. Defaults to "loop_" (e.g. [[+loop_1]], [[+loop_2]], etc...)

 *

 * &static - Static placeholders that are the same in every loop. 

 * If phSimple is active, use MODx-style arrays (&static=`lastname==Simpson||color==yellow`). 

 * Otherwise, use JSON-style array (&static=`{"lastname":"Simpson","color":"yellow"}`)

 *

 * &separator - Separator to put between chunks. If no template (&tpl) is provided, separate content with this (default is "\n")

 * &separatorInner - If no template (&tpl) is provided, separate multiple placeholders with this (default is " ")

 * &idx - Placeholder to use for idx. Setting to 0 will disable. (default is "idx")

 * 

 * &toPlaceholder - Set placeholder

 * &default - If for whatever reason the result is empty, return this.

 * &debug - Print_r debug arrays

 *

 *

 * PLACEHOLDERS

 *

 * Loop adds an [[+idx]] placeholder, which holds the iteration number (starting from 1).

 * Use idx with the ":mod" output filter to add odd/ even logic to your templates.

 * 

 * When no placeholders (or not enough placeholders) are provided, Loop

 * makes its own placeholders by appending numbers to the prefix (starting from 0).

 * For example, if your prefix is "loop_" (the default prefix), you will get 

 * [[+loop_0]], [[+loop_1]], [[+loop_2]], etc....

 *

 *

 *

 * EXAMPLES

 *

 * Using &loop WITHOUT &ph (default MODx-style arrays):

 * - one placeholder only: [[Loop? &tpl=`loopTpl` &loop=`fistname==Homer==Marge==Lisa==Bart}`]]

 * - multiple placeholders: [[Loop? &tpl=`loopTpl` &loop=`firstname==Homer==Marge==Lisa==Bart||lastname==Simpson==Simpson==Simpson==Simpson||phone==1-555-123-4567==1-555-123-4567===="`]]

 * - using auto placeholders (results in [[+loop_0]], [[+loop_1]] and  [[+loop_2]] placeholders): [[Loop? &tpl=`loopTpl` &loop=`==Homer==Marge==Lisa==Bart||==Simpson==Simpson==Simpson==Simpson||==1-555-123-4567==1-555-123-4567===="`]]

 *

 * NOTE: if you don't specify a template with &tpl, Loop will DISABLE the first value as placeholder even if you don't specify &ph

 * So [[Loop? &loop=`==2==1` &separator=`=` &separatorInner=`+`]] will result in 1+=2+2=3+1, not 1+1=2+1 as normally expected without &ph

 * (If you are wondering where the other numbers are coming from, it is from the IDX. Use &idx=`0` to disable)

 *

 * Using &loop WITH &ph=`` (default MODx-style arrays):

 * - one placeholder: [[Loop? &tpl=`loopTpl` &ph=`firstname` &loop=`John==Joe==Lisa==Bart`]]

 * - multiple placeholders: 

 *     [[Loop? &tpl=`loopTpl` &ph=`firstname,lastname,phone` &loop=`John==Joe==Lisa==Bart||Simpson==Simpson==Simpson==Simpson||1-555-123-4567==1-555-123-4567`]]

 *     Note: the last two phone numbers are automatically filled in with an empty string

 *

 * JSON: Using &loop WITHOUT &ph AND &json=`1` (the alternative JSON-style arrays):

 * - one placeholder only: [[Loop? &tpl=`loopTpl` &loop=`{"fistname":"Homer,Marge,Lisa,Bart"}`]]

 * - multiple placeholders: [[Loop? &tpl=`loopTpl` &loop=`{"firstname":"Homer,Marge,Lisa,Bart","lastname":"Simpson,Simpson,Simpson,Simpson","phone":"1-555-123-4567,1-555-123-4567,,"}`]]

 * - one automatic placeholder ([[+loop_0]]):  [[Loop? &tpl=`loopTpl` &loop=`Homer,Marge,Lisa,Bart`]]

 * - custom prefix with multiple automatic placeholders ([[+customprefix_0]], [[+customprefix_1]] and  [[+customprefix_2]] ):  [[Loop? &tpl=`loopTpl` &prefix=`customprefix` &loop=`{"0":"Homer,Marge,Lisa,Bart","1":"Simpson,Simpson,Simpson,Simpson","2":"1-555-123-4567,1-555-123-4567,,"}`]]

 * - more complicated JSON: [[Loop? &tpl=`loopTpl` &name=`{"name":{"0":"Simpson, Homer","1":"Simpson, Marge","2":"Simpson, Lisa","3":"Simpson, Bart"},"phone":"1-555-123-4567,1-555-123-4567,,"}`]]

 * 

 * JSON: Using &loop WITH &ph AND &json=`1` (the alternative JSON-style arrays):

 * - one placeholder only: [[Loop? &tpl=`loopTpl` &json=`1` &ph=`firstname` &loop=`Sue,Joe,Mary,Bo`]]

 * - multiple placeholders (JSON seems to need numbers starting from zero to signify multiple arrays): 

 *     [[Loop? &tpl=`loopTpl` &json=`1` &ph=`firstname,lastname` &loop=`{"0":"Sue,Mary,Bilbo,Gandalf","1":"Smith,Brown,Baggins,Grey"}`]]

 *

 * Example using &numbers: [[!Loop? &tpl=`loopTpl` &ph=`name,number` &numbers=`1` &min=`3` &max=`0` &step=`-1` &loop=`Mary==Joe==Brian` &separator=`<br />`]]

 *

 *

 * USES

 * 

 * Great for generating complex FormIt, Register, and other custom forms with multiple option, text, or other fields. 

 * Call cached in the formit report to automatically output a list of form fields: [[Loop? &tpl=`formitReportRow` &ph=`name` &loop=`name==email==phone==message`]]

 * The formitReportRow chunk: <div>[[+name:ucwords]]: <strong>[[+[[+name]]]]</strong></div>

 * 

 * It's also useful for just about any other simple repetition need where using a custom snippet is overkill.

 * Can easily be combined with other snippets (put them in the template chunks or use them to generate parameters).

 * 

Usage/Installation Instructions

This is a transport package with a single snippet. It should automatically be installed for you.