# 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 apply to a full configuration file defined in tag <changes extends> (e.g. renderer <changes extends="metadata/default"> or layout <changes extends="default"> - more details).

# Changes Order

Changes (with the same file name) 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.

In the runtime folder, a corresponding number will be prefixed.

# Storage

Custom change files are stored in the custom folder. To apply correctly, the folder path of the requested layout/renderer needs to be exactly replicated in the custom folder. E.g., if a layout is requested from path modules/user/layouts/detail, the place to store your custom layout is custom/modules/user/layouts/detail.
Changes apply as soon as a layout or object renderer for that view is requested.

# Addressable Change Paths

A change file default.4aplayout_c stored in folder layouts/my_custom_layout creates an assignable layout my_custom_layout, even though only a change file is stored here (same for object renderers). Using <changes extends>, this change file is addressable.

# Fallbacks

Changes will apply to the configuration explicitly named in tag <changes extends>. In case the defined renderer/layout is not found in the defined path, the following fallbacks apply:

# Fallback For Object Renderer Changes

For object renderer changes, a folder-based fallback applies, starting from the renderer defined in <changes extends>.

Example:

File my_renderer.4aprenderer_c changes the renderer from here: <changes extends="metadata/test/my_renderer">. If my_renderer cannot be accessed, the fallback would be:

metadata/test/default
metadata/default
default

# Fallback For Layout Changes

For layouts, a folder-based fallback applies.

Example:

File default.4aplayout_c changes the layout from here: <changes extends="main/custom_layout">. If a layout cannot be accessed from this path, the layout following the folder-based fallback applies (more details).

Further Documentation

# Create a Change

Like full configuration files, changes, too, are based on XML. To create a change,

create a folder in your custom which replicates exactly the path, the configuration you want to change is requested from (e.g., custom/modules/user/layouts/detail)
in it, create an XML file and name it depending on your use case:

change the default: copy the configuration's filename and postfix it with a _c (e.g., default_c.4aplayout)
create a new layout/renderer, e.g., for a role specific display, and postfix it with a _c (e.g. custom_admin_detail.4aplayout_c)

define the parent configuration using <changes extends>, e.g., <changes extends="detail">, or <changes extends="metadata/default">
add your specific changes (details)

# Changes For Changes

In case there already is a change file by default, you do not need to add another _c. Just make your own change file with your changes from the default. Both changes will apply cumulative (changes order).

Example: For default layout change default.4aplayout_c in modules/file/layouts/main in 4App DAM, create a change default.4aplayout_c in modules/file/layouts/main to your custom folder. Your custom change will additionally apply to the default change.

# Parent Path and Syntax

A change XML consists of

required attribute extends which defines the path of the configuration you want to change (make sure to add all subfolders)
a selector which corresponds to the XPath syntax (opens new window)
an action
optional extended attributes

In the following example,

the first change removes the element selected by xpath from the base configuration
the second change defines the elements to be displayed instead

<?xml version="1.0" encoding="UTF-8"?>
<!-- Target path -->
<changes extends="metadata/default">
  <!-- 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>

In the second example,

both changes add elements at the defined positions to the base configuration

<?xml version="1.0" encoding="UTF-8"?>
<!-- Target path -->
<changes extends="metadata/default">
  <!-- 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>

# 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: Change files can contain several changes. They 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.

# Troubleshooting

# Former Behaviour Without Multiple Changes

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

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.

If you face problems with your configuration changes (if they do not apply or apply twice), an upgrade from 3.x to 4.x may be the reason (release note entry). Please review all your custom change files, currently layouts and object_renderer. Make sure that

all change files contain attribute extends
change files that were copied and altered do not contain double changes (they now apply cumulative)

# 3.x to 4.x Upgrade Tool

When upgrading from 3.x to 4.x, an upgrade tool automatically adds attribute extends to all custom change files. The base configuration name which must be set in this attribute is determined by looking for a parent layout/renderer name + the folder path.

If in some cases the automatic addition did not work, a log entry will be created with a corresponding warning. You may need to add attribute extends and the base configuration manually.

← Conditional operations Create a Database Index →