Creating and Using MODx Chunks

Chunks are the easiest to use of the MODX components. They're simply "chunks" of content that you want to insert on various pages of your site.

Let's create a simple "Under Construction" chunk that you can put on any pages that you're still working on but that you want to appear in the site. (You could just leave them unpublished, but let's assume that you want people to know there is something in the works for those pages.)

First, create a new document following the instructions on the Getting Started page. After saving the document, right-click on that document in the Resource tree at the left side of the Manager screen and select Edit document. After the document loads, scroll down to the document's content window. Somewhere in the document's content area, put the following chunk tag:

MODX Evolution: {{UnderConstructionChunk}}

MODX Revolution: [[$UnderConstructionChunk]]

Make sure the Published? and Show in Menu checkboxes are checked and save the document.

Now, click on the Elements tab at the top of the Manager screen and select Manage Elements. Next, click on the Chunks tab on the right side of the screen. Click on New chunk. Put UnderConstructionChunk in the Chunk name field. Remember that chunk names are case-sensitive so be sure to use the same case you used in your chunk tag on the page. If you get the case or spelling wrong, nothing at all will appear on the page in place of the chunk tag.

You can put a description in the description field but, for this chunk, it probably isn't necessary since the name makes it fairly obvious. Notice the category field. It's blank because you don't yet have any categories. If you use a lot of different chunks, it's nice to have them sorted into categories. You can put something like "Standard Chunks" in the New Category field so you can see the effect after you save it. You'll notice that the chunk appears under that heading in the list and the drop-down category list now contains that category so you can assign it to other chunks when you create them. You can change easily change the category later any time you edit the chunk.

Notice the Lock chunk for editing checkbox. It does just what it says. It will have no effect for you, since you are the site admin, but other users, even if they are managers, won't be able to edit the chunk.

If you want to use the Rich text editor to edit your chunk, scroll down to the bottom and select TinyMCE in the drop-down box. In the Chunk code field, enter your "under construction" text. With TinyMCE selected as the editor, you can use the toolbar at the bottom of the window to style your chunk. You can create a heading, designate bold or italic text, create lists, insert horizontal rules, etc. Just highlight the text and click on the appropriate icon in the toolbar. You can also add images and create links to other documents using the toolbar. Notice the little broom icon. Sometimes invisible extraneous HTML code will be scattered around in your chunk after you've done a bunch of editing. When you click on the broom icon TinyMCE will attempt to clean that up.

When you have the chunk the way you want it, click on Save. You've just finished creating your first chunk. Look at the page you put the chunk tag on by right-clicking on it in the Resource tree and selecting Preview. You should see the chunk content where you placed the tag. If it's not there, you most likely misspelled the name of the chunk, left out the curly braces around it (two on each side), or put in an extra space somewhere. If you're sure it's right and you still don't see the chunk content, try clicking on Clear cache on the Site tab and holding down the shift or control key while clicking on your browser's refresh button to make sure you're seeing the new version of the page rather than a cached one.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray