FieldOverrides

Global field overrides

Here you can override field settings, specified in INI format (or optionally using PHP arrays, see later). Unlike the built-in feature it is possible to limit to certain pages or users, using selectors. This submodule can also be used to modify CKEditor toolbar or other settings with using special keywords (see below).

Syntax

The name of the sections (the text in square brackets) are only used as a description (or comment). Below that you can set key-value pairs, of which the key is usually a field property or a modifier (see later), the value is the value you would like to set. For the value, always use double quotes to avoid syntax errors.

Every key that is not recognized as a modifier or a special key (see below) will be used to set a field property.

To disable keys comment out lines using the ; character. Optionally you can use the ?enabled special key to entirely disable a section (see below).

Modifiers

Modifiers control the scope of the override, eg. to affect only pages with a given template or restrict to a user role.

• ?page: page ID or a selector to restrict field overrides to the matching pages
• ?field: field name or a selector to restrict overrides to the matching fields
• ?user: role name or selector to restrict overrides to the matching users
• ?enabled: if set to 0, the current ini section will be skipped.
• stop: by default all ini sections will be parsed. If "stop" is found, parsing will stop

Examples

[hide the featured_image field if page parent template is clients]
?page = "parent.template=clients"
?field = "name=featured_image"
collapsed = 4

Special keys

• toolbar_add: add these toolbar buttons to the existing ones (CKEditor)
• toolbar_remove: remove buttons specified here (CKEditor)
• formatTags_add: append the format tags to the existing ones (CKEditor)
• **formatTags_remove": remove format tags listed here (CKEditor)

Setting values for a specific language only

In case you need to override a field property only for one language (eg. set new German description only), use fieldname_lang_{LANGUAGE_NAME}. In the example mentioned before it would look like this:

[Set new German description for the excerpt field]
?field = "excerpt"
description_lang_de = "Kurze Einführung geht hier"

Load configuration from file (INI or PHP format)

In the "Asset Paths" section of the module you can set a file to load if you prefer file-based configuration instead writing code to the admin. It's also possible to load a PHP file instead where you can have more control over the output. Note that if you load a PHP file, the "Check" button in the Asset Paths section may fail as ProcessWire restricts loading PHP files from certain subdirectories.

PHP configuration example

When using a PHP file you will need to populate an array called $fieldverrides:

<?php namespace ProcessWire;

$fieldoverrides = array();

$fieldoverrides['hide the "body" field when editing page with ID 1026 for superusers'] = array(
    "?user"     => "roles=superuser",
    "?page"     => "id=1026",
    "?field"    => "body",
    "collapsed" => 4
);

if (!wire('user')->hasRole('superuser')) {
    $fieldoverrides['for non-superusers set image fields\' icon to "folder-o"'] = array(
        "?field" => "type=FieldtypeImage|FieldtypeImage|FieldtypeCroppableImage3",
        "icon"   => "folder-o"
    );
}

Examples for CKEditor overrides:

; for every user who is not SuperUser and with email ending with "@gmail.com"
; only if the CKEditor field name is "body"
; set toolbar buttons: Styles, Format, Bold, Italic, Undo, Redo
; remove CKEditor plugins "div" and "justify"
; allow only "h2", "h3", "p" tags in the Format dropdown
[CKEditor customizations for non-superusers]
?user = "roles!=superuser, [email protected]"
?field = "name=body"
toolbar = "Styles, Format, Bold, Italic, Undo, Redo"
removePlugins = "div, justify"
formatTags = "h2, h3, p"

[Remove CKEditor toolbar button "Italic" for editors]
?user = "roles=editor"
toolbar_remove = "Italic"

[Add undo-redo for user "matt"]
?user = "name=matt"
toolbar_add = "Undo, Redo"