Field vs Input

Inputs, or Input Types, control how a piece of content is managed and displayed in the front-end. From a user perspective, it's a certain type of content.

Using these Input Types, the site builder (that's probably you) can define Fields. A Field has a name ("Introduction"), an icon and an input type attached to it. The input type enables certain properties (such as templates) that affect how the user interacts with it, or how it is displayed in the front-end.

A single input type can be reused in multiple configurations (for example with different templates) by defining multiple fields with the input type.

Chunk

The Chunk input type is used to insert a pre-defined MODX chunk into the content. The chosen chunk will be loaded into the canvas dynamically to give a preview of what was added.

If the chunk has properties attached to it, they will be shown below the preview, allowing the user to insert bits of content into the chunk.

The chunk input type has no template. If your chunk relies on certain styling, you will probably need to use a plugin to register a CSS file in the manager to style it nicely in the manager.

Code

The Code input is a syntax highlighted code editor. It is powered by Ace and is complemented with a drop down to change the highlighted language.

Through the input properties it is possible to customise what languages can be chosen in the drop down (defaulting to HTML, CSS, JavaScript and PHP) and which one is the default (HTML).

The template for the Code input determines how the code is displayed to the front-end. Two common scenarios are:

Inserting a code block into the markup to display the code. In this case, it's important to properly escape the code. In this case enable the Encode Entities property, which will make sure the `` placeholder is properly escaped (including MODX tags) for display.

Actually interpreting the code. For example, if you need to insert some custom HTML and want to use the syntax highlighter in doing so. Simply add a template that just contains the `` placeholder.

The contentblocks.code.theme setting allows you to change the theme that is used for the syntax highlighting. You can try different themes here.

Gallery

While not quite as full featured as MoreGallery, the built-in Gallery input for ContentBlocks is quite nice. It allows you to limit the number of images editors can add and is fully template-able as you would expect.

The template property is used for each individual image (placeholders: [[+idx]], [[+url]] and [[+title]]), while the wrapper template is used to wrap the images (placeholder: [[+images]]).

Heading

The heading input is a simple one, but extremely useful. It combines a drop down for different levels, with a text input. The default template outputs a simple heading tag, however with a bit of creativity it's possible to make them more useful.

Horizontal Rule

Possibly one of the easiest input types ever, this input type inserts a simple visual horizontal rule (<hr>) into the canvas. Make sure to add a <hr> (or similar markup) to the template. No preview of this input type, sorry.

Image (+ Image with Title)

The Image input offers a super streamlined image upload, as well as the ability to select images previously uploaded to the server using the regular MODX File Browser.

Similar to how Redactor works, you can configure a bunch of settings to influence how uploaded images are handled. These are:

contentblocks.image.source: the Media Source to upload images to.

contentblocks.image.upload_path: the path (relative to the root of the media source) to upload images to. You can use placeholders as well: [[+year]], [[+month]],[[+day]], [[+user]], [[+username]], [[+resource]] (ID).

contentblocks.image.sanitize: when enabled, the image name will be sanitised before upload. This is done with regex and the pattern and replacement can be tweaked with the contentblocks.sanitize_pattern and contentblocks.sanitize_replace settings.

contentblocks.image.hash_name: when enabled, the image name will be hashed (a simple md5 hash) before upload.

contentblocks.image.prefix_time: when enabled, a unix timestamp will be prefixed to the image name before upload to ensure it's unique.

The image with title input type is exactly the same as the image, except that it adds a title field under the image to add a title/alt attribute.

The image is available through the [[+url]] placeholder in the template, and when using the image with title you can also use the [[+title]] placeholder.

List (+ Ordered List)

Need to make complex lists? The List (and Ordered List) input type have you covered. It is built to be keyboard friendly and supports pretty much infinitely nested lists.

Quote

The Quote input type combines a simple textfield with a smaller input field to add the author. This works great with a <blockquote> and <cite> tag for semantic markup. The textarea grows automatically to accommodate longer quotes.

Rich Text

The rich text input uses the installed rich text editor, such as Redactor or TinyMCE, to provide the richtext editing experience your clients are already used to. If no supported rich text editor is installed, a simple textarea is shown instead.

Snippet

The snippet input provides an interface for choosing and configuring snippets. While still pretty technical, it is more accessible to editors than MODX tags. The properties are based on the properties defined by the snippet and a list of them is shown in the Add Property drop down.

If enabled on the Field properties tab, there is also the option to call snippets uncached, otherwise all snippets are assumed cached as they should be.

It is possible to filter the available snippets based on name/IDs as well as categories by configuring the properties as such.

Table

Docs to be added.

Texarea & Textfield

Docs to be added.

Video

The Video input allows the user to either paste in a YouTube URL, or to search public YouTube videos for a video to include in the content. In both ways the Video ID is stored in the [[+value]] placeholder, allowing you to set up the embed code as desired.