Compatibility

Crownpeak aims to ensure that individual FirstSpirit versions are largely compatible with one another and that customers will only incur migration costs when switching to a newer major version; even then, such expenses will be low. When switching within a particular major version, there should never be any migration costs at all.

The “Compatibility” area has been introduced so that new, useful functions, which could also have a significant impact on user prompting and/or involve modifications to the data structure/data management, and which could potentially result in migration costs should there be a change in version, can be integrated into FirstSpirit within a major version nevertheless.

Here the customer can decide for himself whether to accept the potential migration expenses in order to benefit from the new functionality; he can also specify the time when the function will be changed over.

FS_CATALOG: Nesting of language-dependent input components

In earlier FirstSpirit versions, it was technically possible to configure FS_CATALOG and all internal forms in a language-dependent manner (corresponds to useLanguages="yes"; this is the default setting for all input component types). However, this often led to problems with regard to translation processes, the usability of the input components for editors in general, maintainability in development, and also performance restrictions. For example, content entered by the editor (particularly when combined with the use of the translation help tool) potentially may not be able to be output (e.g., generation) or edited retrospectively in nested, language-dependent FS_CATALOG constructs.

We therefore recommend using language-independent components within a language-dependent FS_CATALOG component. As a result of this, section templates that are supposed to be used within an FS_CATALOG component potentially had to be created twice – once in a language-independent way (for use in a language-dependent FS_CATALOG component) and once in a language-dependent way (for use in all other cases).

For projects newly created with FirstSpirit version 5.2R5 or higher, the use of language-dependent input components on levels within a language-dependent FS_CATALOG component is disabled by default. FirstSpirit automatically treats language-dependent input components in templates used inside an FS_CATALOG component that is also language-dependent as if they were language-independent, thereby dispelling the disadvantages of the old behavior.

The old behavior is not recommended and will probably stop being supported in future. Migration is recommended.

For projects that have been carried over from a previous version to FirstSpirit version 5.2R5 when the server was upgraded or that have been imported from a server with a previous FirstSpirit version to a server with FirstSpirit version 5.2R5, the old behavior will continue to be supported until further notice.
To prepare projects from previous versions of FirstSpirit for use with the new behavior, FirstSpirit provides two compatibility settings that allow gradual migration.

Data storage between the old and new behavior is different. If language-dependent components within a language-dependent FS_CATALOG component are used in a project, the FS_CATALOG component data must be checked and backed up or amended if necessary before the new behavior can be used throughout the entire project. If this is not checked and backed up, a change can lead to data loss in the project: If content is already present in an FS_CATALOG component or in internal forms of this component, once the FS_CATALOG component is saved, the content will be retained in the language in which the editor had just been editing (fallback option: master language); if content was available in other languages, it will be removed.

Both compatibility settings have the following effects:

• Compatibility setting “inactive”: In a language-dependent FS_CATALOG input component, internal input components that are configured in the respective template as language-dependent are treated as if they were language-independent (new behavior).
• Compatibility setting “active”: In a language-dependent FS_CATALOG input component, internal input components that are configured in the respective template as language-dependent are treated as if they were language-dependent (old behavior).

The compatibility for individual FS_CATALOG components can be deactivated in templates via a parameter (forbidPolyglotDataHierarchy). This makes it possible to apply the new default behavior for individual FS_CATALOG input components, while other FS_CATALOG components for which this parameter has not been set are still treated as being compatible with previous FirstSpirit versions.

If all FS_CATALOG components in the project correspond to the new behavior, the compatibility setting can be deactivated throughout the entire project and in the "FS_CATALOG: Nesting of language-dependent input components" area:

Enabled (compatibility setting “active”, "old" behavior): The use of language-dependent input components within a language-dependent FS_CATALOG component is permitted.
This can lead to problems related to data access (see above), so this setting is not recommended. It is solely intended to safeguard backward compatibility with older projects.
This is the default setting for projects that were created using a version before 5.2R5. You can switch to the recommended “Disabled” setting (see below) by clicking on the Disable button.

Disabled (compatibility setting “inactive”, “new” behavior): This option can be used to force monolingual input throughout an entire project for language-dependent input components within a language-dependent FS_CATALOG component. Internal templates are interpreted as language-independent (useLanguages="no") automatically. The content of these internal input components can then automatically be input and saved in one language only.
This is the default setting for projects created with FirstSpirit version 5.2R2 or higher. This setting is recommended.

Even if a switch to "Disabled" is recommended, this can lead to data loss in the project: If content is already present in an FS_CATALOG component or in internal forms of this component, once the FS_CATALOG component is saved, the content will be retained in the language in which the editor had just been editing (fallback option: master language); if content was available in other languages, it will be removed. Therefore, the consequences experienced in the project should be checked carefully in advance.

For more information, see also

• FirstSpirit release notes for version 5.2R5
• CATALOG (→FirstSpirit Online Documentation)

ExternalSync/ContentTransport: use mapping based schema merge

The FirstSpirit “External Synchronization” and FirstSpirit “Content Transport” functionalities can be used to export project content and properties of a FirstSpirit project (source project) and import them in other FirstSpirit projects (target projects). For more information see Introduction (→Documentation “External Synchronization”) and documentation about FirstSpirit ContentTransport.

If the project languages differ between the source and target project, then by default when Database schemata are transported, language-dependent table columns that are missing in the target are not added, and language-dependent column contents that only exist in the target are overwritten.

This behavior can be influenced using the “ExternalSync/ContentTransport: use mapping based schema merge” option:
With Enable when importing a database schema

• missing, language-dependent table columns are added to the database schema of the target project,
• the mapping from input component to table column is performed and
• language-dependent column contents that only exist in the target are not overwritten.

This is the recommended setting.

Prerequisites and notes:

• Only table columns for which a mapping also exists in the source project are created (and mapped) in the target project.
• Only table columns for languages that do not exist in the source project are created (and mapped) in the target project.
• Only table columns are created (and mapped) in the target project if they are language-dependent in the source project (activated option “Generate for all languages” when creating a table column).
• The functionality uses the FirstSpirit naming scheme for language-dependent columns as a basis, scheme: column_name+_language_abbreviation (for example “Column_EN”, “Column_DE”, “Column_FR” etc.). For projects that do not use this schema, this can potentially lead to unexpected behavior.
• The master language of the target or source project is used (as a fallback) as the basis for the mechanism.
• Structure and contents of external databases must not be changed: Therefore, no mapping takes place in the case of external databases.

Activating this option is an optimization compared to the default behavior. At the same time, however, it is a significant change in software behavior (e.g. compared to previous releases). A change or activation should be executed and tested on a test system beforehand. Potentially existing project solutions that imitate the functionality of this feature may have to be adapted or removed. Otherwise, unexpected behavior may occur (e.g., data loss or scripts failing).

Which option is currently active for the project can be seen in the text on the left (Enabled or Disabled):

Enabled: (recommended) If this option is enabled, when importing a database schema in the target, missing language-dependent database columns will be added and language-dependent column contents that only exist in the target will not be overwritten.

Deaktiviert: (not recommended) This is the current default setting. If this option is activated, missing, language-dependent database columns will not be added and language-dependent column contents that only exist in the target will be overwritten when importing a database schema in the target.

Changing the setting is possible by clicking on the button (“Disable” or “Enable”) and must be confirmed by a confirmation prompt.

Simplified example

• Source project: language DE
• Target project: languages DE, EN

1) Initial situation:
Source project: database schema contains a table with one column (DE):

In the corresponding table template, the column is mapped to DE:

2) Export
In the source project, e.g. via “Content Transport” / “Add Database Schema” create feature with above database schema.

3) Import
In the target project, e.g. via “Content Transport” / “Install Feature” import the feature from 2).

4a) Result with disabled “ExternalSync/ContentTransport: use mapping based schema merge” option
Database schema in target project contains only table column DE (not EN):

There is no mapping in the EN language:

4b) Result with enabled “ExternalSync/ContentTransport: use mapping based schema merge” option
Database schema in target project contains table column EN:

The table column EN is correctly mapped to the EN language:

Find out more about databases in FirstSpirit here:

• Chapter Database schemata (→FirstSpirit Online Documentation)
• Chapter Database connection

Detect images as a file

Images and files in FirstSpirit

The FirstSpirit Media Store is designed to manage all media used in a project. These could be:

• images (Picture type) in any graphic format (e.g., PNG , JPG, WebP) or
• other media formats (File type) (e.g., PDF, MP3, or video files).

Using unsupported graphic formats

FirstSpirit does not support all available graphic formats.

Following successful upload, unsupported graphic formats are not created in the project's Media Store as Picture type media; instead, they are created as File type media.

These can be used and referenced in FirstSpirit but functionalities such as image cropping or the preview image are not available for unsupported graphic formats.

Compatibility mode – Detect images as a file

With existing media, the type does not automatically switch from File to Picture:
If a graphic format (e.g., SVG) is supported in a newer version of FirstSpirit, the assignment of the existing media will remain the same in the projects for compatibility reasons.

For existing projects, the compatibility setting “Detect images as a file” is set with the corresponding file extension (e.g.,: “svg”) when you update to a new FirstSpirit version.

The following then applies to the project:

• The graphic formats now supported are still managed as File type media in this project.
• Newly created media are also identified as File type media in this project.

For all new projects, the compatibility setting remains empty. The following applies here:

• With newly created media, an SVG is now automatically identified as Picture type media and a preview image is calculated.

If the compatibility mode set automatically is not required for a project, the configuration can be changed here manually.