Chunks in CMF MODX Revolution - what they are, why they are needed, how to use them

MODX Revolution CMF has "chunks" - special elements for storing layout code. In this tutorial we'll go over what chunks are in MODX Revolution, how they work and how you can use them for web development.

Note - I will try to give examples in MODX standard syntax, in Fenom and in PHP, so that you can form a solid understanding of MODX system and be able to work with any syntax, because on one project you can use all formats at once, because each of them has its own advantages and differences from the other.

What are MODX Revolution chunks?

Chunks are reusable blocks of code or content that can be dynamically inserted into other elements - other chunks, templates, snippets, TV fields, resource fields.

Think of them as building blocks, site-wide variables that allow you to separate a site's layout and design from its content. This separation provides flexibility, making it easier to maintain and update the site.

Imagine you need to display a list of article cards in 3 different places on the site - in the article directory, in the recommended articles block for an article, and in the useful articles block for a product. And everywhere will be the same card, conventionally:

<div class="article-card">
	<div class="article-card__title">Заголовок</div>
    <div class="article-card__text">Описание</div>
</div>

But if you specify the card code 3 times in the design of each of these lists, you will have to edit it in 3 (or more) different places when making changes to the design.

This is where chunks come in handy. We create 1 article card layout chunk, and specify it as a design element in 3 different lists. Then when we need to make changes, we will need to edit only 1 place instead of 3.

Chunk creation

Using the list of articles as an example - most likely an article will have a title and a small description, which will be different for each article. Such variables are called placeholders - you mark the places where any data will be inserted when the chunk is called.

Let's create a chunk tpl_article_card, which represents an article card in the list. And in it we need to mark places for variables. It looks like this in the standard syntax:

<div class="article-card">
	<div class="article-card__title">[[+pagetitle]]</div>
	<div class="article-card__title">[[+description]]</div>
</div>

And on Fenom:

<div class="article-card">
	<div class="article-card__title">{$pagetitle}</div>
	<div class="article-card__title">{$description}</div>
</div>

Chunks can contain HTML, CSS, JavaScript, but not PHP - this distinguishes them from snippets and plugins. The main task of chunks is to control the view, not the logic of data processing.

Passing placeholders (variables) to a chunk

Now let's talk more about placeholders. Each article should have a different title, picture, date - right? For this purpose we can pass placeholders - something like variables - to the chunk.

If we want to output just 1 chunk and pass some data to it, it will look like this in the standard syntax:

[[$chunk_name?
	&param1=`value`
	&param2=`value2`
]]

Fenom:

{'chunk_name' | chunk : [
	'param1'=>'value',
	'param2'=>'value'
]}
// OR
{$_modx->getChunk('chunkName', [
	'param1' => 'value',
	'param2'=>'value'
])}

PHP:

$html = $modx->getChunk('chunk_name',
	array(
		'param1' => 'value',
		'param2' => 'value'
	)
);

Here we have called one chunk, but often we need repetitive elements - the same list of articles. Let's try it on a concrete example - let's make a call to the pdoResources snippet, which will output all resources with template 1 (let's assume they are articles):

[[pdoResouces?
	&parents=`0`
	&where=`{ "template" : "1" }`
	&tpl=`tpl_article_card`
]]

pdoResources will retrieve from the database all resources matching the given conditions and try to organize each of them into a chunk, which we passed in the tpl parameter - the name tpl_article_card.

By default, all standard resource fields will be available there, except content, because there can be large amounts of text and for a standard list it is usually not necessary. But all this we can customize for ourselves. We can also include the necessary TV fields by specifying them with commas (without spaces) in the includeTVs parameter:

[[pdoResouces?
	&parents=`0`
	&where=`{ "template" : "1" }`
	&tpl=`tpl_article_card`
	&tvPrefix=``
	&includeTVs=`tv_name1,tvName2,myTVname3,...`
]]

Note - I also specify the tvPrefix parameter so that in our chunk we can use placeholders for TV equal to just the TV name. Otherwise we need to add the tv. prefix to them - and this is not always convenient if you will use the chunk in another snippet and pass data to it.

// chunk with placeholder TV - without tvPrefix
<p>[[+tv.tvName]]</p>
// chunk with TV placeholder - empty tvPrefix is specified
<p>[[tvName]]</p>

And we can use the same chunks we specified earlier:

<div class="article-card">
	<div class="article-card__title">[[+pagetitle]]</div>
    <div class="article-card__title">[[+description]]</div>
</div>

Fenom:

<div class="article-card">
	<div class="article-card__title">{$pagetitle}</div>
    <div class="article-card__title">{$description}</div>
</div>

Chunk usage scenarios

If you are already more or less familiar with MODX development and its ecosystem of elements - resources, chunks, templates, plugins, processors, connectors... In your head you probably involuntarily ask what is responsible for what and when to use it.

In the case of chunks - they should be used if you have some elements of the site, which can be used several times in different places - several times in one template, one time in several templates, etc. You feel like you're layout something that's already been layout - then it might make sense to wrap it in a chunk.

Popular scenarios

Site header: The header is likely to be contained in multiple templates, so chunking the site header allows you to easily manage elements such as the logo, navigation menu, and contact information across all pages.

Site footer: A site's footer often contains copywriting information, social media links, contact information, and other elements. Similar to the header, its use as a chunk is justified.

List Item Card: If you have a list of anything (articles, products, categories, jobs...) on your site, creating a chunk for a card for that item is almost a vital necessity. You can create a card template and use it for all items in the list, changing only the content of the chunk for each specific item.

At the same time, cards can have different display formats - for example, large, medium and small views of an article. Here we face a question - should we create 3 separate chunks, or one? And if one - how to change the view?

If the logic of the template is simple enough and is solved by simple CSS conditions - you can pass a CSS class to the playholder of the chunk:

<div class="article-card article-card__[[+cssClass:default=`normal`]]">
	<div class="article-card__title">[[+pagetitle]]</div>
    <div class="article-card__title">[[+description]]</div>
</div>

Fenom:

<div class="article-card article-card__{$cssClass ?: 'normal'}">
	<div class="article-card__title">{$pagetitle}</div>
    <div class="article-card__title">{$description}</div>
</div>

Or, if you are working with pdoTools, perform a sequence number check:

<!-- we'll put the first article on the big card -->
{if $idx == 1}
	{set $cssClass = 'big'}
{/if}
<!-- the cards in the sidebar will be small -->
{if $place == 'sidebar'}
	{set $cssClass = 'small'}
{/if}
<div class="article-card article-card__{$cssClass ?: 'normal'}">
	<div class="article-card__title">{$pagetitle}</div>
    <div class="article-card__title">{$description}</div>
</div>

Note that for placeholders that may not be passed in a chunk call - we add a default value:

// MODX
[[+cssClass:default=`normal`]]
// Fenom
{$cssClass ?: 'normal'}

Sidebar Blocks: Chunks can be used to create sidebar blocks that contain a variety of information such as banner ads, category navigation, or the latest news. These blocks can be inserted on different pages of the site.

Content Modules: Chunks can also be used to create content modules such as banners, promotions, or blocks with text information. Modules can be easily added or removed from different pages of the site.

Feedback Forms: If your site has multiple feedback forms (e.g. contact form, product order form), you can create a chunk for each form, making them easier to manage and modify.

Practical benefits of using chunks

Now that you have a good understanding of what MODX Revolution chunks are and how they function, let's take a look at the practical benefits they offer web developers, designers, and content managers:

Code reuse and consistency

Using Chunks optimizes your workflow by promoting code reuse. You no longer need to duplicate code across multiple pages, reducing the chance of errors and providing a consistent look and feel across the entire site.

Convenient updates

When it comes time to make changes or updates to your site's design or content, you only need to change the chunk once. Changes are automatically propagated to all pages that link to that chunk, saving you time and effort.

Improved collaboration

Chunks facilitate collaboration between developers, designers, and content creators. Developers can focus on creating reusable chunks, and designers and content managers can use these chunks to populate pages without needing technical knowledge.

Easy A/B testing

With the help of chunks, you can easily conduct A/B testing. You can create multiple versions of chunks with different designs or content options and quickly switch between them to analyze user preferences and improve site performance.

Faster load times

By reducing code redundancy, chunks can speed up page load times. This performance improvement can have a positive impact on user experience and SEO rankings.

How to use chunks in development

Now that you've seen the benefits of chunks, let's walk through the steps to start using them in MODX Revolution:

Creating a chunk

To create a chunk, log into the MODX Revolution manager, click on the "Elements" tab, and select "Chunks". Click on "New Chunk", give it a unique name and add the code or content you want.

Link to the chunk in templates

Once you've created a chunk, you can reference it in your templates, resources, snippets, TV fields, and other chunks - as we've described above. The invocation of the chunk will be replaced by the contents of the chunk when the page is rendered.

Easily update chunks

When you need to make changes to a chunk, simply edit it in the MODX manager. The changes will be automatically applied to all pages that use this chunk.

I hope this article was useful and will make it easier to understand chunks and website development on MODX. Have a nice mind!