Modify workspace with resource replace variants - SysAdmin
Modifying module assets using replace variants.
Using resource replace variants you can adjust the standard workspace structure. Here you'll see the replace variants for workspace pages, workspace containers, widget configurations and widgets. Additional changes using templates and changes made by user's workspace.
To adjust a module asset for your installation you can create a resource replace variant with the desired behavior. censhare then uses the replace variant instead of the module asset. This allows changes even if module assets themselves are going to be overwritten in the next update. Typical cases where you would apply this include changes to transformations, templates, asset list views or to the standard workspace structure.
Introduction
censhare uses modules assets (among other tools) to expand functionality. New or changed module assets are automatically created and updated after a server start or when a server action is initiated in the admin client. This simplifies the update process for a running system.
As such, it makes little sense to make changes directly in the standard module asset that is delivered with the system. It may end up being overwritten by censhare in the next update. Using resource replace variants you can still adjust the system to suit your needs.
If a variant exists for a module asset, censhare uses the variant and not the module asset as a resource. To change a module asset, create a replace variant with the desired configuration. This allows you to modify transformations, templates, asset list views or assets in the standard workspace structure to suit your needs.
Using resource replace variants you don't just overwrite module assets, but rather all of the resource assets. A resource asset contains a resource key. It is therefore addressed as a resource and the functionality defined in the asset is used as a result. Otherwise, a resource asset would behave just like any other asset.
If censhare accesses an asset as a resource, it will check whether the asset contains a "Resource replace variant" relation. If this is the case, censhare won't use the resource asset, but rather its replace variant as the resource. In doing this you overwrite the functionality of the resource asset with that of its variant.
Changes to the resource asset, therefore, have no effect as long as the replace variant exists. Only if you delete the relation or the variant will the resource assets once again dictate behavior.
You can create multiple resource replace variants for a resource asset and then configure it to have different roles. censhare then selects the appropriate replace variant based on the role.
As of version 2017.1, the system no longer allows resource replace variants to be created from resource replace variants.
Creating replace variants
From a single asset
First search for the module asset from which you would like to create a replace variant. In the asset menu, click the "Variants" entry and then select the "Resource replace variants" option.
censhare then creates a duplicate of the resource asset, selects the UUID (Universally Unique Identifier) as the resource key of the duplicate and links it with the resource asset using a "Resource replace variant" relation. If necessary, you can modify the variant's resource key. However, it must be unique within the system. If you select a name that already exists, you will be shown an error message because it doesn't fulfill the requirement (constraint error).
Creating an individual resource replace variant is a good option if you wish to just change a certain system behavior and nothing else. For example, if you wish to change the color of an information element when displaying asset lists. Or if you want to modify individual assets in the standard workspace structure.
Notes regarding the standard workspace structure
Be careful when assigning asset types as well as asset-type and MIME-type filters for resource replace variants. Filters can cause the asset page to not be displayed in all situations. This applies to all users if no roles are defined for the replace variant. When assigning roles, only users for this role are affected.
The reason for this is that the resource replace variant completely replaces the asset of the standard workspace structure. If the filter excludes certain asset pages for the replace variant, there is no replacement definition for an asset page that can then assume that view.
From an asset structure
More comprehensive configurations can also be specified using asset structures. An example of this is asset views that determine the entire view of a list entry, or the standard content structure. The latter defines the structure of XML documents for the content editor.
For asset structures, you first need to create a resource replace variant from the master asset of the structure. Then you need to create duplicates of all the assets under the master asset. Then you link these back to the original asset structure with the variant of the master asset.
You can potentially also use individual assets from the original structure in the variant of the asset structure because their behavior remains the same. But this depends on the situation you are in.
To generate duplicates, censhare Web provides you with the "Duplicate" asset action. If the action is successful, the browser will show the message "Duplicate successfully generated" in the upper right of the window with a link to the new asset. In the "Resource" widget on the "Overview" tab, you need to enter the resource key.
In the variant structure, you need to link every duplicate with the same relation type used in the original asset structure in this location.
Using roles
When opening a resource asset via resource key, censhare checks whether resource replace variants are available. If a replace variant exists with the master user role, censhare uses this replace variant. Otherwise, censhare checks whether there is a replace variant without a user role and evaluates this. Other replace variants with user roles are not taken into consideration. If there are only replace variants with unrelated user roles, censhare uses the resource asset, for example, the associated asset from the standard workspace structure.
Example:
Replace variant without role: all users see the change.<br/>
Replace variant 1 with role and replace variant 2 without role: users with the appropriate roles see replace variant 1, all others see replace variant 2.
Replace variant 1 with role 1 and replace variant 2 with role 2: Users with role 1 see replace variant 1 and users with role 2 see replace variant 2. All other users see the original, for example, the asset of the standard workspace structure.
Note: If multiple replace variants have the same role for one resource asset, it is not certain which replace variant censhare will select.
Unlike workspace templates, censhare does not save the role in the resource replace variant asset itself, but rather in the relation to the module asset. In particular, when creating the standard workspace structure this has the advantage that censhare does not always need to read all of the replace variants. This allows censhare to more quickly recognize whether roles are defined for a replace variant and whether one of those matches with the master user role.
Configuring roles
To define a role for a resource replace variant, you can open the change dialog for the relation in both the resource asset and in the replace variant.
In the resource asset, you go to the "Resource variants" widget and then to the replace variant for the "Resource variant" widget. In the list, select the action "Edit relation metadata" option for the asset.
In the "Replace variant role" field select the desired role. Use the "+" button to add multiple roles.
Note: In the "Resource" widget on the "Details" tab of a resource replace variant there is also a "Role" field. Do not use this field for configuring the role for a resource replace variant!
It is not evaluated here and is only available for reverse compatibility reasons. The role definitions for resource replace variants are only set in the link itself between resource assets and replace variants!
Searching for replace variants
You can look for resource replace variants that are created by censhare and not by the "system user". To do this, go to the expert search:
"Created by" != "System user"
+
Relation
Direction: "Parent relation",
Type: "Variant/Resource variant/Resource replace variant"
Note: There are also resource replace variants created by the system, but these are of no interest here.
Proceed as follows to search for all resource replace variants with a certain user role in the expert search:
"Replace variant role"= USER ROLEThe search for resource replace variants without roles is similar in the expert search:
"Replace variant role"= "not null"
Using the column view you can easily recognize whether there are replace variants available for a workspace asset. Search for the workspace asset and click on it. The next column shows all of the relations as well as all of the replace variants below it in their own section. For every replace variant, censhare also lists whether there are definitions for these roles too.
Modifications after a system update
After a system update, censhare doesn't automatically update resource replace variants. If a change is made to a module asset for which you already defined a resource replace variant, then you have to manually modify this.
To do that, search for all module assets with a resource replace variant. The change date of the module asset here needs to correspond with the date of the system update. Then compare the module asset and the resource replace variant and transfer the changes.
Visibility of the changes
In order to make changes visible via the resource replace variants, in most cases, you need to refresh the website or restart the application like the editor. If that doesn't work, update the censhare 5 Web configuration. This is done using the server action "Update web application configuration".
For changes made to the standard workspace structure, the process is a bit different. censhare always generates the workspace for a user when that user logs in. To do that, censhare goes through the standard workspace structure, among other things, and checks whether it has resource replace variants. In the end, censhare stores an internal representation of the workspace. This allows the user to continue working if changes are made to the standard workspace structure and only sees the changes after he/she logs in/out.
Updating censhare Web
In the admin client click the "Server actions" button and select the option "Update web application configuration". In the dialog that appears, select the option "Client configuration" in the "Configuration" field.
Note: If a user logs in while the server is carrying out the action "Update web application configuration", the login may last longer than usual. It can also last longer if a user opens an application at that moment.