Jump to main content Jump to doc navigation

modX::getChunk

Processes and returns the output from an HTML chunk by name.

getChunk actually sets the properties you pass (and that are picked up from default properties and/or a property set) as placeholders (preserving any with the same key and restoring those after processing is complete) and allows the modChunk class to process() them (along with any other tags, filters, etc.).

getChunk will execute the MODX parser, so you can use output filters and the $properties array can be multi-dimenstional (i.e. more than just simple key/value pairs). If this is more horsepower than you need, use modX.parseChunk instead.

Syntax

API Doc: modX::getChunk()

string getChunk (string $chunkName, [array $properties = array ()])

$properties is usually a standard associative array, e.g.

$properties = array('key' => 'value');

Which would cause the [[+key]] placeholders to be replaced by the 'value'.

However, $properties can also be a more deeply nested array such as the kind that might be returned from certain getObject or getCollection queries, e.g.

$properties = array(
    'user' => array('id' => 1),
    'document' => array('id' => 27)
);
// or:
$properties['user']['id'] = 1;
$properties['document']['id'] = 27;

// Corresponds to the following placeholders:
// [[+user.id]]
// [[+document.id]]

In cases where a multi-dimensional array is used, the placeholder syntax changes to use a dot for each node in the array, e.g. [[+user.id]] and [[+document.id]]

Examples

Simple Example

Lets process this chunk and output its value. We have this Chunk, called "WelcomeChunk":

<p>Welcome [[+name]]!</p>

We'll put this in our Snippet:

$output = $modx->getChunk('WelcomeChunk',array(
   'name' => 'John',
));
return $output;

So every key in the associative array passed to the getChunk method corresponds to an available placeholder inside the chunk, e.g. [[+name]]

This code outputs this:

<p>Welcome John!</p>

Nested $properties

In our Chunk:

<a href="http://site.com/profile?user_id=[[+user.id]]!">User Details</a>

In our Snippet:

$output = $modx->getChunk('UserLink',array(
   'user' => array('id' => 123)
);
return $output;

Used in a Snippet

Often, MODX Chunks are used as formatting string by Snippets. To that end, you can make good use of xPDO's toArray() method.

Imagine a Chunk named single_user:

Username: [[+username]]<br/>
Active?:  [[+active]]<br/>
<hr/>

Then in your Snippet:

$userlist = $modx->getCollection('modUser');

$output = '';
foreach ($userlist as $user) {
    $output .= $modx->getChunk('single_user', $user->toArray() );
}

return $output;

Parsing a String

Sometimes you need to parse a string using the MODX parser – this does not use getChunk, but it is related. Using the MODX parser is a bit slower than using a simple str_replace function, but it does let you use complex placeholders (e.g. to include another Chunk) and output filters etc. The trick is to create a temporary Chunk object, then run the process method on it.

// The formatting String
$tpl = 'Hello, my name is [[+name]]';

// Properties
$props = array('name' => 'Bob');

// Create the temporary chunk
$uniqid = uniqid();
$chunk = $modx->newObject('modChunk', array('name' => "{tmp}-{$uniqid}"));
$chunk->setCacheable(false);

$output = $chunk->process($props, $tpl);

See Also

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

  • modmore
  • STERC
  • Jens Wittmann – Gestaltung & Entwicklung
  • Fabian Christen
  • Digital Penguin
  • Dannevang Digital
  • Sepia River Studios
  • CrewMark
  • Chris Fickling
  • deJaya
  • Following Sea
  • Anton Tarasov
  • eydolan
  • Raffy
  • Lefthandmedia
  • Murray Wood
  • Snow Creative
  • Nick Clark
  • Helen
  • JT Skaggs
  • krisznet
  • YJ
  • Yanni
  • Richard

Budget

$366 per month—let's make that $500!

Learn more