ContentBlocks

ContentBlocks is a powerful content manager for MODX allowing editors to create modular, multi-column content.



Frequently Asked Questions

We're collecting the questions we get most often into a list of FAQs. If your question is not in the list, please reach out to us via support@modmore.com and we would be glad to help.

How do I implement ContentBlocks into my template?

Just make sure the [ [*content] ] tag (minus the spaces) is included in your template - ContentBlocks will write the processed content to that field. 

Do you have an input type / block for ______ content?

We might! Check out the list of built-in input types, as well as the list of available installable input types.

Not what you're looking for? You can also write your own Custom Input!

How do I add options to a Chunk input?

If you want your editor to be able of passing in options to a chunk with the Chunk Input, there are two ways to do this.

  1. Adding (Default) Properties to the actual chunk element will show up below the input. To add properties, to to Elements > Chunks and edit the chunk. On the Properties tab, unlock the Default properties and add the options. Go back to the resource, add a chunk input and celebrate.
  2. Using Field Settings, you can add additional options to any field type. Simply go to the Content Blocks component, edit the field and add settings on the Settings tab. As of ContentBlocks 1.1 these can also be exposed in the canvas instead of hidden behind a modal.  

Does ContentBlocks support TinyMCE or CKEditor?

Yes, both TinyMCE and CKEditor (since 1.3.0) are supported, but we do recommend using Redactor - it's a perfect fit and very user friendly to use.

What is the difference between the Chunk and Chunk selector input type?

While they are very similar, the biggest difference between a Chunk and Chunk Selector input is who decides what chunk will be inserted into the canvas. 

With the Chunk input type, the administrator creating the ContentBlocks field chooses the chunk beforehand. With the Chunk Selector input type, it is the editor who can choose from a list of chunks; however the administrator can still limit the available chunks through the field properties. 

How can I escape MODX tags in a Code field?

This is a common question for people writing documentation for MODX or MODX tools. When you use a Code field you can preprocess the entered value in such a way that you don't have to manually escape MODX tags. 

Please see the following documentation for instructions on how to do that:

How can I debug the page its contents?

If you're having issues parsing a certain complex page, or perhaps you just want to know what ContentBlocks makes of a page before it is completed by the MODX parser, there's a simple trick. Simply right click the page in the resource tree, and choose Quick Update Resource

ContentBlocks does its parsing when the resource is saved, and it then puts the resulting markup in to the Content field. As we do not enhance Quick Update with the content canvas, this provides you a way to see exactly what is left dynamic, and what is parsed on save. 

Also see the Parsing & Templates document for more information about how ContentBlocks works under the hood.

Is it possible to enable or disable ContentBlocks when installed? System-wide, per Context, Resource or other factors?

Out of the box, ContentBlocks comes with a few options to decide when it is used and when it isn't. By default, it is enabled for all resources across your MODX site.

To enable or disable ContentBlocks system-wide, go to System (the cog icon in 2.3) and System Settings. In the first dropdown above the table, choose contentblocks to show all settings that belong to ContentBlocks. Under the Core area, you should see "Disabled" (with key contentblocks.disabled). Double click its value to edit it. Set to Yes to disable ContentBlocks, and set to No to keep ContentBlocks enabled by default. When set to Yes, so disabled by default, it is possible to selectively enable it on more specific entities, such as contexts. 

To enable or disable ContentBlocks in an entire context, create a new context setting for that context by right clicking the context in the tree, choosing Edit Context and clicking the Create New button on the Context Settings tab. Give it a key of contentblocks.disabled, set the Field Type to Yes/No and set a value of 0 (to enable ContentBlocks in that context) or 1 (to disable ContentBlocks in that context). 

To enable or disable ContentBlocks on a specific resource, simple edit that resource and navigate to the Settings tab. Near the bottom of the tab you will notice a Use ContentBlocks? setting. Simply set it to Yes or No and then save the resource. The page will reload.

To enable or disable ContentBlocks based on the template, see the next two FAQ entries that provide you with a plugin you can add to your MODX site to control template-based behaviour.

If none of these built-in options are specific enough for your usage, please get in touch with support@modmore.com. We may be able of providing you with a plugin to follow your business rules. 

How can I enable ContentBlocks only on specific templates?

This isn't possible out-of-the-box, but using a quick plugin you can manage this easily.

Simply create a new Plugin in your MODX installation with the following contents:

?php
$eventName = $modx->event->name; switch($eventName) { case 'OnDocFormPrerender': $disabled = true; $enabledTemplates = array(1, 3, 5); if ($modx->controller && isset($modx->controller->resource) && $modx->controller->resource instanceof modResource) { $resource = $modx->controller->resource; } if (in_array($resource->get('template'), $enabledTemplates)) $disabled = false; if ($disabled) { $resource->setProperty('_isContentBlocks', false, 'contentblocks'); } break; }

On the System Events tab, make sure OnDocFormPrerender is enabled.

In this example plugin, ContentBlocks is only enabled whenever template 1, 3 or 5 is used - for other templates it is turned off. Please note that this will bypass the "Use ContentBlocks" setting on each of the resources.

Note: this only works if the ContentBlocks plugin has a higher priority number on the OnDocFormPrerender event than your own plugin. You can quickly edit this by right clicking the system event, choosing Update Plugin Event, and double clicking in the Priority column.

How can I disable ContentBlocks on specific templates?

This isn't possible out-of-the-box, but using a quick plugin you can manage this easily.

Simply create a new Plugin in your MODX installation with the following contents:

<?php
$eventName = $modx->event->name;
switch($eventName) {
    case 'OnDocFormPrerender':
        $resource = $modx->controller->resource;
        $disabled = false;
        $disabledTemplates = array(1, 3, 5);
        if (in_array($resource->get('template'), $disabledTemplates)) {
            $disabled = true;
        }
        if ($disabled) {
            $resource->setProperty('_isContentBlocks', false, 'contentblocks');
        }
    break; 
}

On the System Events tab, make sure OnDocFormPrerender is enabled.

In this example plugin, ContentBlocks is turned off for template 1, 3 or 5. Please note that this will overwrite the "Use ContentBlocks" setting on resources with those templates.

Note: this only works if the ContentBlocks plugin has a higher priority number on the OnDocFormPrerender event than your own plugin. You can quickly edit this by right clicking the system event, choosing Update Plugin Event, and double clicking in the Priority column.

Can I use chunks inside Field or Layout templates?

You can, but because of the way templates are parsed, you will need to add properties to the chunk call to pass any data from ContentBlocks into the chunk. 

For example if you have a heading field that exposes a [[+level]] and [[+value]] placeholder, you would pass it to a chunk like this:

[ [$heading.tpl:tag? &level=`[[+level]]` &value=`[[+value]]`]]

To ensure you can once again use [[+level]] and [[+value]] placeholders inside the chunk.

Is it possible to use static fields and layouts, to edit them as files?

Currently this is not supported out of the box, unfortunately. It is possible - and we do this ourselves - to store your ContentBlocks configuration on the filesystem using Gitify, with the following additions to your .gitify file:

data:
  contentblocks_fields:
    class: cbField
    primary: name
    package: contentblocks
  contentblocks_layouts:
    class: cbLayout
    primary: name
    package: contentblocks
  contentblocks_templates:
    class: cbTemplate
    primary: name
    package: contentblocks

We do recommend using the ContentBlocks interface for managing fields and layouts (followed by doing Gitify extract to write the information to file) to ensure the syntax is correct. Right now we use a fair bit of JSON definitions for things like settings and properties, which, truth be told, may not be the most ideal format for direct manipulation. 

How can I group together fields?

Depending on what you're trying to do exactly, there are a few ways to group together fields. 

  1. For fixed groups of fields (when there always need to be exactly specific fields), the Repeater input is a great option. It was developed to allow repeating rows of fixed content, as the name indicates, but if you limit the number of rows to one in the field properties it is a great way to group a single row fields too. The repeater supports all ContentBlocks input types, including custom ones, so is a very powerful option.
  2. If you have an existing input type and you want to add one or a few extra inputs to it, you can also use Field Settings for that. Field Settings are easier to set up than a Repeater, but are limited in the setting types that are available, which cannot currently be extended. 
  3. If you want columns with content within columns, you should take a look at the Nested Layout input type. Compared to the Repeater, this is more of an open canvas than a fixed set of fields.

How can I load extra styles or a CSS file for ContentBlocks?

Getting fancy with realistic previews of what content might look like on the front-end, or want to make some changes to the design of the canvas or certain input types? 

ContentBlocks doesn't expose a convenience method for loading additional CSS files currently, but it's incredibly easy to do thanks to the power of plugins in MODX. Simple create a new Plugin and set it to fire on the OnDocFormRender system event. In the plugin content, all you have to do is call $modx->regClientCss with the url to your CSS file, like this:  

<?php
$url = $modx->getOption('base_url') . 'assets/path/to/style.css';
$modx->regClientCss($url);

(If you also use Redactor, you could also use the redactor.css setting - that will also inject the stylesheet into the manager page and would save you using the above plugin.)

As this will inject the CSS into the full manager page, you do need to be careful about scoping your CSS properly. The ContentBlocks canvas is wrapped in a .contentblocks-wrapper div, and each of the input types has its own .contentblocks-field-<input type> class. There are also lots of other classes that can be used to target styling.

If you end up making changes to the way ContentBlocks looks, we would love to hear about that and consider including them in the next release. 

Can I access the Layout or Column from within a field template?

Yes you can! The following placeholders are available in each field template:

  • [ [+layout_id:tag] ]: the ID of the containing layout
  • [ [+layout_column:tag] ]: the string reference of the column the field is inserted in

Some other placeholders available on each field that may be convenient include [ [+idx:tag] ] (an index for the fields in this particular column), [ [+unique_idx:tag] ] (an index that is guaranteed to be unique across fields and layouts on the page), [ [+layout_idx:tag] ] (an index for the layout position).

My select field or layout setting is using the display text as value, instead of the defined value. What's wrong?

Selectbox settings need field options to be defined as Displayed Text=value, which is subtly different from other instances where you can set options (such as Template Variables) in that it only has a single equals (=) sign. 

If your setting is configured with field options in the form of Displayed Text==Value, ContentBlocks doesn't recognise the value because of the two equals signs and it falls back to using your displayed text as value as well. If you configured it properly but it is still not saving the proper values, please let us know via support@modmore.com.

Why should I use ContentBlocks?

ContentBlocks radically changes the way you build websites in MODX, and perhaps even how you build websites in general. That is a very bold statement, so bear with us for a moment while we explain.

MODX already revolutionised the way content (the actual text being displayed to the user), the markup (your template), and the logic (snippets, plugins) are separated. This gives you great benefits, such as being able of implementing complex logic inside a template without having to write a single line of PHP, and having shared templates across pages so they look consistent. 

ContentBlocks adds another layer to that, where the content is split up into smaller pieces. We call these small pieces Fields and they accept small blocks of content (for example a paragraph, header, or an image), and by parsing that content through a template, it is turned  into a piece of content for the site visitor to see. A simple example is an image uploaded by the content editor, which is then parsed through a template to add the necessary markup for seeing it in the front-end. 

So why is that extra layer a good thing? Here's a few reasons or use cases why this might be very useful:

  • You can update the markup of all fields, across the entire website, without having to edit a single resource by hand. Think about what that means for a second. Working on a website redesign, and the current website uses ContentBlocks? Maybe you're switching from one CSS library to another, and perhaps this other library uses "button" instead of "btn" as class for your buttons. Just update the template on your button field, tell ContentBlocks to rebuild the content, and all buttons on your site are updated. 
  • That isn't just interesting for when you're redesigning a website. What about content-first design? Start by adding in content directly into your MODX site using a base set of fields, and as your design starts to get shape, you update the field templates to adjust the markup where necessary. The client can be involved in building their website from the start!
  • Need to extract certain parts of the content for use elsewhere? For example you need the first image in the content to add to your Facebook meta tags? Because the content (the image url) is separated from the markup (the <img> tag), you can just grab it with a simple snippet, which simply looks at the raw content. You can extend this to open up a full API so you can provide the data without markup to a native app.

What ContentBlocks also gives you is the ability to have multiple columns of content. This is an incredibly powerful tool in the complex sites we build nowadays on CSS grids. 

When my editor tries to insert a Chunk block, they get a permission denied popup.

The Chunk input type uses the core processors to load information about the chunk, and this checks for core permissions. If your editor user is a limited administrator account, you might be missing certain permissions. These are the permissions your editor will need:

  • view_chunk

Also, if you have restricted element access completely, these permissions may need to be enabled as well:

  • view
  • view_element
  • view_category

I'm getting an error that the layout does not exist. Now what?

If you get an error like the one pictured below, it means there is something wrong with your ContentBlocks configuration, or that a layout was removed even though it was still in use.

IMPORTANT: If you see the error and save the resource, the missing layout will be removed from the content. Copy the raw content to a safe place if you may need it later.

Do you see the error on a new resource, or a resource not previously edited in ContentBlocks? Then it's probably a configuration issue. Make sure that you have at least one layout by going to Extras > ContentBlocks. Take note of the ID of the layout (shown in brackets), and at System > System Settings find the contentblocks.default_layout setting. Set the value of that setting to a valid layout ID. While you're there, make sure the contentblocks.default_layout_part system setting has the key of a valid column in the layout.

Do you see the error on an existing resource that worked fine previously? In that case the used layout was most likely removed. Important: saving the resource while the error shows will remove the previous content that was stored in the layout. If you may need to restore the content to a different layout, make a copy of the provided raw content first!


navigateup

Disclaimer: Viewing non-Euro pricing

You are currently viewing prices in a non-Euro currency. Please be advised that these prices are estimates, based on data by Open Exchange Rates.

While we offer this currency converter hoping our users find it convenient, all purchases are made in Euro, and the final amount charged can vary depending on payment provider, day, time of day and a number of other factors outside of modmore's control. There are no guarantees on accuracy and modmore nor Open Exchange Rates can not be held liable for errors.

×