# Configuration Changes

Configuration changes are config files in the 4ALLPORTAL filesystem that are usually postfixed with _c. They modify parts of a complete configuration, that is a dependency of the current 4App. You can thus remove, move, or add some elements while most elements remain exactly the same (e.g. add a new component to a default layout, or remove a search field from an object renderer).

Currently, change files are supported for layouts and object_renderer.

# How Do Changes Apply?

Change files always refer to a complete configuration file and cannot exist on their own. They will apply to the next full configuration.

Like all default and custom configuration files, changes, too, built the runtime content. Here, they are stored next to full configuration files in a module's or global/default folder and apply as soon as a layout or object renderer is requested.

For the order and hierarchy, please refer to our fallbacks documentation.

Please note: This behaviour changes with Core Engine version 4.0 and (multiple) changes will take the 4App order into account (more details).

# Create a Change

All configuration files for which you can define a change are based on XML. There can be only one change file for a base configuration. One change file can define multiple changes, though.

To create a change, first put an XML file in the corresponding folder of your custom folder. Use the filename of the default configuration and postfix it with a _c.
In case there already is a change file by default, copy it to your custom folder to alter it.

Examples:

For default object renderer default.4aprenderer in modules/user/object_renderer/search in 4App Core Engine
Create a change default.4aprenderer_c in modules/user/object_renderer/search in your custom folder

For default layout default.4aplayout_c in modules/file/layouts/main in 4App DAM
Copy the change default.4aplayout_c to modules/file/layouts/main in your custom folder

Specific Changes

A regular change like this will apply in every use case. You can also create specific attribute changes that will apply for roles, object types or client types only.

Details on layout changes. Details on attribute fallbacks.

# Define Changes Using XPath

A change XML consists of a selector, which corresponds to the XPath syntax (opens new window), an action and extended attributes.

<?xml version="1.0" encoding="UTF-8"?>
<changes>
  <!-- Remove element -->
  <change xpath="//component[@id='securityView']" type="remove"/>

  <!-- Replace element with body -->
  <change xpath="//const[@key='moduleName']" type="replace">
    <entry key="moduleName" class="string">user</entry>
  </change>
</changes>

The first change removes the element selected by xpath from the corresponding base configuration.
The second change replaces the selected element of the base configuration with the XML elements inside the <change> elements.

<?xml version="1.0" encoding="UTF-8"?>
<changes>
  <!-- Add/insert an element at position 0 in wrapper "const" -->
  <change xpath="//const" type="add" at="first">
    <entry key="moduleName" class="string">user</entry>
  </change>

  <!-- Add/insert an element at position 2 in wrapper "const" -->
  <change xpath="//const" type="add" at="2">
    <entry key="moduleName" class="string">user</entry>
  </change>
</changes>

In this example, the two changes add elements at the defined positions to the corresponding base configuration.

# XPath Elements

Element	Value	Description
xpath	XPath String	The xpath is used to select one or multiple elements or attributes to execute the change action on. (Help: XPath (opens new window))
type	`add` `remove` `replace` `move`	Action to execute on the chosen elements. `add`: Adds the following tree to the selected elements. Attribute `at` specifies where to add if the target(s) already contain elements. `remove`: Removes all elements selected by `xpath`. `replace`: Replaces the elements selected by `xpath` with the elements from the change body. `move`: Moves all selected elements (only one selected element would make sense) to the target xpath selected element.
at	Integer `first` `last`	For type `add` only. A selected element can have multiple children. This attribute specifies where to add the body elements from the change body. The first position is index 1. All values less than 1 or greater than the last index, are (like first or last) interpreted as first or last element (-500 to 1).
target	XPath String	The xpath is used to select one element as target for type `move`.

When adding or replacing, all XML tags within the change tag are copied one-to-one into the tree. So please make sure to insert your change into the correct tag, e.g.:

insert child elements (components) into a children tag
insert parameters into the parameter tag
insert field renderers into the field rederer list tag

Otherwise, these elements would be ignored.

Please note: There can be only one change file for each base configuration. Still, this can contain several changes.
Changes are processed in sequence and can therefore also build on each other. E.g., if an element of type A is added first and after that all elements of type A are deleted, the newly added element would also be deleted.

# Multiple Changes From Version 4.0

In version 3.x, multiple changes are not supported. That means, a _c file in a 4App or the custom folder disables the same _c file in another 4App.

The system behavior of applying configuration changes will change from version 4.x and multiple changes are supported.

Example:

We have a file layouts/main/mylayout/default.4aplayout_c in a 4App.

In 3.x, the same file in the custom folder or another 4App would completely disable the first file.
In 4.x, both files would apply in the defined 4App order and complement each other.

# Changes Order From Version 4.0

From 4.0, the system takes the 4Apps' order into account. Changes will apply one after the other in the 4App order, which is defined in the App management.
Between 4allportal-core (first in order) and custom (always applied at last) may be any number of 4Apps doing "changes" with change files.

4allportal-core
modules/user/layouts/main/default.4aplayout
4allportal-another-app
modules/user/layouts/main/default.4aplayout_c
custom (Customer config folder)
modules/user/layouts/main/default.4aplayout_c

In this example, the file without the _c postfix is the base layout defining the default main layout for the module User.
4App 4allportal-another-app and custom alter this layout by using a change file, postfixed with _c.
The first change may add a component by default, where the custom change removes a part of it.

Please also refer to our fallbacks documentation.

Attention: This function changes the behavior in some cases and should be considered potentially breaking. Before upgrading to version 4.x, please review all your custom change files, currently layouts and object_renderer).

← Conditional operations Create a Database Index →