Change module assets using variants

Introduction

Using the resource variants you can adapt module assets, for example for showing assets in lists. You can add information elements (2) to existing (1) ones for the individual lines without changing the module asset itself.

censhare uses module assets to expand functionality, among other things. New or changed module assets are automatically created or updated after the server is booted or a server action is started in the admin client. This makes updating the running system easier. Therefore it does not make sense to make changes directly in the module asset. These will then be overwritten by censhare in the next update. Using "Resource replace variants" you can still adjust the system to meet 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, you need to create a variant with the desired configuration. This allows you to adapt transformations, templates, or asset list views to suit your needs, for example.

Using resource change variants, however, you don't just overwrite the module asset, but also every resource asset. A resource asset contains a resource key ( reference: -> resource key ) that is used to address the asset as a resource and take advantage of the asset's functionality. Otherwise, a resource asset will behave like any other asset.

If censhare accesses an asset as a resource it checks whether it has a "Resource replace variant" relation. If this is the case, censhare doesn't use the resource asset, but its variant as a resource. This will overwrite the functionality of the resource asset with the functionality of its variant, and not the resource asset, but its variant will determine the behavior of the system.

Changes to the resource asset thus have no implications as long as the replace variant exists. Only when you delete the relation or the variant will the resource asset determine the behavior.

Tip: There can only ever be just one resource replace variant for each resource asset.

After you have created a resource variant or changed the variant, the change is not always immediately visible. However, it is generally sufficient in censhare 5 Web to reload the current web page or to reopen the application again. In a few cases, you have to update the configuration for censhare 5 Web. For more information see the section "Updating censhare 5 web configuration".

Creating resource variants

From one individual asset

To create a variant from an individual resource asset, you first need to look for it in censhare. You can do that in censhare Web and in the Java client.

To search for a certain resource key ( reference: -> resource key ) in censhare Web you first have to use the advanced search. Click in the quick search field, then on the "Search action menu" button, and then select "Advanced search". First, create a parameter and select the "Resource key" field. In the search field for the parameter, enter the resource key, and click SEARCH. For more information see the article Advanced search.

Move the cursor to the list entry of the resource asset in the results list. The "Asset action menu" button will appear on the far right. Click that, then click the "Variants" entry and the "Resource replace variant" entry.

censhare will now create a duplicate of the resource asset, rename the resource key ( reference: -> resource key ) and link the duplicate with the resource asset via the "Resource replace variant" relation. If the previous resource key is called "KEY", then the variant has the resource key "KEY.variant". If necessary you can adapt the variant's resource key. However, it needs to be unique in the system. If you select a name that already exists, you will get an error message when you save because that condition is not met (constraint error).

In the Java client, open the search and go to the "Expert" tab. Here you click the + button and select "Resource key" as the asset field in the parameter. In the search field of the parameter enter the resource key ( reference: -> resource key ) you are looking for.

In the result list, click on the asset. Click the right mouse button and then in the menu that appears select the "Variants" entry and the option "Create resource replace variant". In the dialog that appears you can change the individual asset fields. censhare creates the variant and links it.

Once you have created the resource replace variant you need to reload the current page in censhare Web to activate the variant.

Creating an individual resource change variant is an option if you want to change the system behavior on a selective basis, for example, if you want to change the color of an info element when displaying asset lists. In this case, search for the associated snippet that displays the info element and create a variant. In the variant, adapt the template for displaying the info element. For more information see the article Configuring asset views in lists.

From an asset structure

Comprehensive configurations can be made via asset structures. Examples of this are asset views that determine the entire view of a list entry or of the standard content structure. The latter defines the structure of XML documents for the content editor.

For asset structures, you first have to create a resource change variant from the main asset structure. Then you have to create a duplicate of all assets under the main asset. You link these with the main asset variant just like you do with the original asset structure. You can also use individual assets from the original structure in the variant of the asset structure because their behavior stays the same. But this depends on the area of application. You can find an example for creating a whole structure in the section

For more information, see the section Creating your own view for configuring asset lists.

To create a duplicate, censhare Web provides you with the "Duplicate" asset action. If it works, the message "Duplicate successfully created" will appear on the upper right. Click the link "Open new asset" on the bottom right of the window. In the "Resources" widget on the "Overview" tab you now need to enter the resource key ( Follow the instructions for the resource key ). Click the "Edit" button and in the "Key" field enter the desired resource key.

In the Java Client, you first have to be in administration mode. To do that, click "censhare Client" in the menu bar and then select the "About censhare Client" option. Close the dialog by clicking OK while holding down the "alt" key. Now click the asset and click the command "Create duplicate". That option is in the context menu behind the "New asset" menu entry. A dialog will open. Here you need to create a resource key ( Follow the instructions for the resource key ). Go to the "Features" tab and click the + button in the "Features (internal)" section. Select the field name "Resource key" and enter the desired value. Click OK to create the duplicate.

You need to link every duplicate in the variant structure with the same relation type used in the original asset structure in this location.

Relation with a resource asset

You have created a resource asset and want to replace another one with it. In this case, you don't create a variant. Instead, you link the asset with the resource asset whose behavior you wish to overwrite.

In censhare Web, you use the asset action "Add relation" to do this. A list opens with the relation options. If you have selected the original resource asset click the "Resource replace variant" entry. If you want to create the relation from the changed resource asset, click the entry "Resource change variant from". Select CANCEL to exit the dialog or confirm the selection with CONTINUE. An asset chooser dialog will open for the related asset. Select the resource asset in question and confirm it with OK or exit with CANCEL.

In the Java client, drag the changed resource asset to the original resource asset. In the dialog that appears select the entry "Resource replace variant" and click the "Create" button.

Updating censhare 5 web configuration

Certain parts of the censhare application will need to call the server action "Update web application configuration" to apply changes. Please, use this server action, if a change is not visible at the latest reloading the page in the browser.

Click the button "Server actions" in the toolbar in the Admin Client and select the appropriate command. Select the "Client configuration" entry in the "Configuration" field and click OK or close the dialog with Cancel.

Tip: If a user logins while the Server is performing the "Update web application configuration" action the login process can last a little bit more. Similarly, it may take a little longer, if a user opens an application during this time.