wcm.io

Basic concepts

The Configuration Editor is a template which is used inside the ‘/content’ tree. It allows to edit configurations for the inner-most context that is detected within the context tree (e.g. by defining sling:configRef properties). Where the configuration itself is stored depends on your system settings, by default it's stored in /conf.

You cannot define the contexts via the configuration editor, you have to set the sling:configRef manually or within the page properties of your content templates, or by defining custom context path strategies. But once your contexts are defined you can create a config editor page within each context and edit the configuration parameters.

The configuration editor supports only editing configuration for which configuration metadata is present. This is normally done by deploying configuration annotation classes with your applications.

See Apache Sling Context-Aware Configuration documentation for more details.

Installation

In production environments (including AEMaaCS), you should only deploy configuration editor bundle io.wcm.caconfig.editor together with your application. In this case you should define your own template definition for it which controls where editor config pages can created (see next section).

For testing purpose an AEM package (ZIP) is provided which contains the config editor bundle together with a template definition which allows all paths below /content. This package is only for convenience installations on local AEM instances, it is not compatible with AEMaaCS. Deploy only the bundle (JAR) on AEMaaCS.

wcm.io Context-Aware Configuration Editor Bundle (JAR)
wcm.io Context-Aware Configuration Editor AEM Package with Template Definition (ZIP)

In most cases the default persistence implementation provided by AEM out-of-the-box is not enough for the needs of AEM applications. wcm.io Context-Aware Configuration Extensions provide additional implementations and features.

Defining the editor template

The editor application contains an AEM template definition, but it is deactivated by default. Each application has to define it's own editor template with a fitting allowedPaths definition and title depending on the needs of the application.

Only the template has to be defined, the page component resource type can be referenced. Example:

{
  "jcr:primaryType": "cq:Template",
  "jcr:title": "Configuration Editor",

  "allowedPaths": "^/content(/.*)?$",

  "jcr:content": {
    "jcr:primaryType": "cq:PageContent",
    "sling:resourceType": "/apps/wcm-io/caconfig/editor/components/page/editor"
  }
}

Editor GUI

When opening the Configuration Editor an overview of all configurations is displayed for which some configuration data is present. By using the “Add” button you can enter new configuration data for other configurations where no data exists yet.

For a singleton configuration all configuration parameters are displayed and can be changed. With the “Save” button the changes are persisted, the “Delete” button removes the whole configuration.

For a configuration collection all existing collection items are displayed, and new ones can be added after entering a name. Single items or the whole configuration collection can be removed.

The editor is based on AngularJS and CoralUI.

Publish configurations

By default, Context-Aware configurations are stored below /conf and can thus not published by editors using the AEM Author GUI. The Editor provides an “publish this page” button, which published the editor page itself.

It is recommended to also deploy the wcm.io Context-Aware Configuration Extensions and activate the AEM Page persistence strategy. Then the reference provider also included in the extensions bundles detects changed and unpublished configuration pages below /conf when publishing the editor page, and allows to publish the configurations as well.

Using custom edit widgets

For each data type (string, number, boolean) the fitting edit widget is chosen automatically. Alternatively you can define custom widgets via extra properties on the @Property annotation.

@Property(label = "DAM Path", description = "Browse DAM assets.", property = {
    "widgetType=pathbrowser",
    "pathbrowserRootPath=/content/dam"
})
String damPath();

@Property(label = "Context Path", description = "Browse pages in the current site.", property = {
    "widgetType=pathbrowser",
    "pathbrowserRootPathContext=true"
})
String contextPath();

@Property(label = "Tags", description = "Picks tags.", property = {
    "widgetType=tagbrowser",
    "tagbrowserRootPath=/content/cq:tags"
})
String[] tags();

@Property(label = "Dropdown Param", description = "Parameter with dropdown list.", property = {
    "widgetType=dropdown",
    "dropdownOptions=["
        + "{'value':'option1','description':'First option'},"
        + "{'value':'option2','description':'Second option'},"
        + "{'value':'option3','description':'Third option'}"
        + "]"
})
String dropdownParam();

@Property(label = "Dropdown Dynamic Param", description = "Parameter with dynamic dropdown list.", property = {
    "widgetType=dropdown",
    "dropdownOptionsProvider=myproject.provider1"
})
String dropdownDynamicParam();

@Property(label = "String Text Area", description = "Enter multiple lines of text.", property = {
    "widgetType=textarea",
    "textareaRows=10"
})
String stringTextArea();

Validation

See Field Validation.

Filter configurations

On a system that hosts multiple tenants or websites it may be desirable to offer only a subset of context-aware configurations that are present in the system. This is possible by adding a Context-Aware Service that implements the interface ConfigurationEditorFilter.

Example:

@Component(service = ConfigurationEditorFilter.class)
public class ConfigurationEditorFilterImpl implements ConfigurationEditorFilter {

  @Override
  public boolean allowAdd(@NotNull String configName) {
    return !StringUtils.startsWith(configName, "unwantedConfigName");
  }

}

The control which context-aware configurations are available on which content subtree in the system set the appropriate service properties or bundle header names as described in Context-Aware Services.

Configuration Categories

You can assign a category to context-aware configurations to get a better overview if you have lots of them in your system. Once at least once category is assigned, the editor will display the category name, and a filter dropdown to filter the list by category.

Example for assigning a category:

@Configuration(label = "My Configuration",
    property = { EditorProperties.PROPERTY_CATEGORY + "=category1" })
public @interface MyConfig {
  ...

By implementing an OSGi service for ConfigurationCategoryProvider you can provide labels for the category names. It's also possible to assign categories programmatically with this service, or apply a default category to configuration definitions which do not have a category assigned.

To use this, you need to deploy the optional dependency io.wcm.sling.commons.

Disable Editor on Publish

You should disable the configuration editor on publish by applying an OSGi configuration like this:

[configurations runModes=publish]

  # Disable Configuration Editor on publish
  io.wcm.caconfig.editor.impl.EditorConfig
    enabled=B"false"