You must upload templates to Workbench before they are available to users in Experience Manager.
All deployment template applications include a
set_templates script in the
control directory to update Experience Manager
templates. You run the script after you locally modify JSON template files and
you want the templates available in Experience Manager. The script also imports
locales and thumbnail files.
This script requires that the templates you modify are stored locally
in
<app dir>\config\import\templates\.
To send updated templates to Experience Manager:
Template errors are detailed in the
ifcr.log file.
The
ifcr.log file is located in:
If any templates fail validation, the upload is canceled, and the previous templates remain in Workbench.
Some templates may be successfully uploaded to Workbench, but still contain errors that lead to unexpected behavior in Experience Manager.
The most common scenario is when a property is associated with an editor that has constraints, such as a choice editor that can only accept certain string properties. If the default value of the property does not meet the editor's constraints, the editor may discard the value and display the following messsage in the Content Details Panel when a user adds the cartridge to a page:
Some fields or cartridges within this cartridge may have been updated or removed. Your content has been converted to the new cartridge. To accept these changes click OK and Save All Changes from the List View. To reject these changes, click Cancel. For more information, see "Troubleshooting pages" in the Oracle Workbench Help.
To avoid this message, ensure that all property defaults are valid options in the associated property editor.
During the development and testing phase of your application deployment, you may need to make adjustments to your templates and update them in Experience Manager.
When Experience Manager populates the Content Detail Panel for a content item, it checks the content configuration of the loaded page against the template. If the template has been changed such that it is no longer compatible with the content, Experience Manager displays a warning and attempts to upgrade existing content to fit the new template definition.
Note
Existing configurations are not upgraded to the new template until a content administrator edits and saves the affected content item in Experience Manager.
Experience Manager does the following to ensure that the content and template are in sync:
If a property has not changed its name or type, the existing values are migrated to the new template.
If new properties are added to a template, any corresponding property editors become available in Experience Manager when a content administrator edits a content item based on the updated template. If you specify default values for the new properties, they are applied when a content administrator edits and saves the content item using the updated template.
If properties are removed from a template, the corresponding property editors no longer display in Experience Manager when a content administrator edits a content item based on the updated template. The properties and their values are deleted from the page configuration.
If the type of a property has changed (for example from string to list) within a template, the corresponding property editor (if one is specified) becomes available in the Experience Manager when a content administrator edits a content item based on the updated template. The existing value for the property does not display in Experience Manager until the content administrator saves the new value, replacing the previous value.
If a content item or content item list property has changed to specify a different content type, then any existing cartridge in that section is ejected and its configured properties deleted.
If the default value of an existing property has changed, it is only applied to new content items that are created based on the updated template. In existing pages, the previously saved value of the property (even if it is an empty string) is preserved regardless of whether it was originally a default or user-specified value.
Some editors may implement specific update-handling logic in cases where an existing value does not meet the editor's constraints.
Note
Changing the
name of a property is equivalent to removing the
property with the old name and adding a property with the new name. Avoid
changing the names of properties that are being used by existing pages. To
change the display name of a property on Experience Manager, use the
label attribute instead.
Because existing content is not automatically updated to the new templates, and default values are never updated in existing pages, any changes that you make to your rendering code to reflect changes to a template should be backward-compatible. You can trigger the content upgrade process manually by accessing all affected content, but this approach is not recommended.
For this reason, you should avoid making changes to existing templates that are being used in production. You should limit updates to templates to the early stages of application development when you have little or no legacy content to support.
If you need to view or edit an existing template on a local
machine, you can run the
get_templates script to download templates from
Experience Manager to the local
<app
dir>\config\cartridge_templates
<app
dir>\config\import\templates\ directory.
To get templates from Experience Manager:
