The wcm.io Maven Archetype for AEM is the best starting point to set up a new AEM application with (or without) wcm.io Support. By using a set of feature flags the new project can be adapted to your needs. Version 2.4.0 comes with some important new features.
AEM Support
The Archetype supports
AEM 6.3 with latest service pack
AEM 6.4 with latest service pack
AEM 6.5 with or without latest service pack
Introduction of WCM Core Components
When wcm.io Handler support is enabled (optionWcmioHandler=y), the project is set up using the brand-new wcm.io WCM Core Components. They provide the full power of the AEM Sites Core Components, enhanced with all features from wcm.io Handler.
With this you can use all the new features described in these related blog posts:
Updated Build/Deploy Scripts
The AEM Archetype provides two convenience scripts that build the whole application and deploy it to a local AEM Author and/or Publish instance. That does not only include the application packages and sample content, but also all system configuration, 3rdparty Packages and AEM Service Packs as required by the application:
build-deploy.sh- Build and deploy to author instancebuild-deploy-publish.sh- Build and deploy to publish instance
The major part of the configuration management and package deployment is based on wcm.io DevOps CONGA.
New in AEM Archetype 2.4.0 is that the Publish port number/URL is no longer spread across different scripts and files, but now maintained centrally in the Parent POM of the application. There is a publish Maven profile to switch to the publish URLs. This resulted in some reworks on the scripts to switch Maven profiles instead of Deployment URLs. Call the script with a help argument to see all supported parameters.
Example for URL definition in Parent POM:
<!-- AEM instance parameters --> <sling.url>http://localhost:4502</sling.url> <sling.publish.url>http://localhost:4503</sling.publish.url>
Deploy individual bundles or content packages
If you want to deploy only a single OSGi bundle you are currently working on to AEM you can use the following shortcut command on the command line:
mvn -Pfast cq:install- Install the current maven module to author instancemvn -Pfast,publish cq:install- Install the current maven module to publish instance
Internally this calls the install and sling:install goals.
New in AEM Archetype 2.4.0: This also works for individual content package projects, and internally calls install and wcmio-content-package:install.
The latest 3 versions of wcm.io AEM Mocks provide helpful new features. This blog article summarizes the most interesting ones.
Content Policies
If you are using Core Components and the Template Editor in AEM, you are also depending on Content Policies and have to test your component code with them. AEM Mocks 2.7.0 supports them in a easy way.
Example for creating a content policy on-the-fly using the AemContext:
// create a content policy with mapping for resource type
context.contentPolicyMapping("app1/componenty/component1",
"prop1", "value1",
"prop2", 123);
This creates a new content policy for the resource type app1/componenty/component1. If your Sling Model is adapted from a resource with this resource type and injects a content policy it will get the mapping provided with the lines above in the unit test. This makes it easy testing it with different variants.
Advanced image file format support in AEM Mocks
AEM Assets supports a wide range of image file formats, whereas in unit tests with AEM Mocks it was only possible to use GIF, PNG and JPEG in combination with the AEM Layer class.
AEM Mocks 2.7.0 provides also support for TIFF and SVG file formats if you configure additional Java ImageIO plugins in your project as test dependency.
Additionally there is a mock implementation of the AssetStore DAM service and an AssetHandler that supports the old and the new file formats.
Content Fragments
AEM Mocks 2.5.0 comes with a support for Content Fragments (CF) - structured and unstructured ones. Structured CF provide “key-value pairs” and unstructured ones only a text fragment. Both can contain variants.
The ContentBuilder provides convenience methods for creating CFs on-the-fly. Example for creating a structured CF:
ContentFragment cf = context.create().contentFragmentStructured("/content/dam/cf1",
"param1", "value1",
"param2", 123,
"param3", true,
"param4", new String[] { "v1", "v2" });
Example for creating an unstructured CF:
ContentFragment cf = context.create().contentFragmentText("/content/dam/cf2",
"<p>Text</p>", "text/html");
Besides this you can interact with the AEM ContentFragment API, adapting it from a DAM resource and reading and writing content to it or creating variations.
Granite ResourceCollectionManager and ResourceCollection
If you are writing code to test AEM workflow process step implementations it is useful that AEM Mocks 2.6.0 provides now mock implementations of ResourceCollectionManager and ResourceCollection.
wcm.io Media Handler and Link Handler are enhanced with a couple of new features helping to build the brand-new WCM Core Components (which are covered by a separate blog post). This post highlights the major features.
Content Policies
Media Handler 1.7.0 comes with support for content policies.
That means it is possible to define the list of allowed media format(s) and auto-cropping mode not only in the Java code or as component properties, but also via content policies assigned to the component. It comes with some predefined dialog snippets that can be used in the design dialogs:
It’s also possible to define advanced responsive image settings for Image HTML tags with sizes attribute or picture with sources elements via content policies or component properties.
See Media Handler Component Properties for a full list of supported properties and features.
TIFF and SVG file formats
With Media Handler 1.7.0 you can also use TIFF and SVG assets or files in your components.
TIFF files are fully supported with all transformations (e.g. cropping, rotation), but are always rendered as JPEG files for displaying them in the web browser.
SVG files provide unlimited scalability, transformations like cropping and rotation are not supported.
If you want to write unit tests using this new file formats, make sure to define additional Java ImageIO plugins in your project as test dependencies.
Image Maps
Media Handler 1.7.0 has now full support for Image Maps produced by the Image In-Place editor of AEM.
They are detected by the media handler and included in the generated markup with a reference to the image HTML element.
Links that are found within the image map area definitions are processed and validated using the Link Handler.
Clear Transformations Action
With the AEM Image In-Place Editor your can apply transformations like cropping and rotation to your image. It may happen that you apply a transformation that no longer fulfills the media format restrictions of your component, e.g. because the width/height is too small after the cropping. In this situation it’s no longer possible to change the cropping because the image is no longer displayed. An ugly workaround was to remove the image and select it again - but this is tedious.
Media Handler 1.7.0 provides a “Clear Transformation” action in it’s customized File Upload GraniteUI component that allows to “reset” the image to it’s initial state.
Workflow to generate Asset rendition metadata
If you are using the Media Handler, some extra metadata needs to be generated for all renditions of any Asset used with it. This metadata contains the real width/height in pixels of each rendition. By default this metadata is generated automatically by a background service, the "wcm.io Media Handler Rendition Metadata Service".
However, if you have assets in your system that were present before installing the media handler with the background service, or for any other reason need to repair/update the metadata of already existing assets you can now use an AEM Workflow with a custom workflow step. This is available since Media Handler 1.6.0.
Details: How to re-generate wcm.io Media Handler rendition metadata for asset folders using a Workflow
“Invalid” API extensions
Sometimes you want to set a non-null Media or Link variable reference to an “invalid” instance. This was difficult before and required constructing a media/link request or synthetic media/link resource that was resolved to an invalid link.
To make this easier both MediaHandler and LinkHandler now provide a invalid() method which directly returns an “invalid” instance.
Resolve links with type auto-detection
The link handler stores each link target usually in two properties - one for the link type (e.g. internal, external, media), and one for the link target reference (property name depending on link type). The Link Handler API expects a resource or link request with exactly this information.
AEM itself traditionally, and the same applies to the AEM Sites Core Components, stores the link target in a single field, leaving it up to the implementation to detect the type of the link from the nature of the string. The Link Handler now supports an additional method overload LinkHandler.get(<String>) which is able to resolve such a string, and detect the appropriate link type automatically.
Using this new feature it is also possible to apply a “compatibility mode” for components that were created - and used in production - without Link Handler and are later migrated to a Link Handler concept. By setting a component property like "wcmio:linkTargetUrlFallbackProperty": "link" the link handler falls back to auto-detecting the link target from a single property named "link" when no link type and link target properties following the Link Handler conventions are found in the resource. With this mode it’s no longer required to migrate the link properties in existing content when switching an existing component to the Link Handler.
wcm.io has a new module: the WCM Core Components. They are not a replacement the AEM Sites Core Components, but extend them in a natural way with the wcm.io Handler features.
Why WCM Core Components
Adobe provides AEM developers with a set of Core Components that should be the starting point for every AEM application. The team from Adobe did a fantastic job in creating them, and in the decision to create an Open Source community around them.
However, from the viewpoint of wcm.io-based AEM applications, the AEM Sites Core Components have some conceptual shortcomings that are currently “baked” into the API and the implementation that limit their usage and do not allow to re-use technical aspects:
The image (media) handling is only implemented in a black box “image component”, with a proprietary and non HTML-standard way to display the images in a responsive fashion. The only solution to re-use the “image” functionality in another component is to embed it, which is an awkward pattern with a lot of limitations.
The handling of internal and external links is inconsistent across the different components and does not allow to take central control of it. And it’s not possible to re-use this limited link handling support in custom components.
Detection of the current site root page is inconsistent across the components and the logic not reusable
The URL externalization is based on the “Day CQ Link Externalizer” service which has no proper multi tenancy support
More details about this conceptional limitations are covered in the adapTo() 2019 talk: Assets and Links in AEM Projects.
The WCM Core Components provide a solution for this problems by “weaving” wcm.io Handler support into the Core Components. The WCM Core Components can act as drop-in replacement for the AEM Sites Core Components: by updating the super resource types all components are wcm.io Handler-enabled.
If you start a new project the best starting point is the wcm.io Maven Archetype for AEM, which can bootstrap a new AEM application with a full setup for wcm.io Handler and the WCM Core Components included.
Component Overview
As shown in the component overview from AEM Sites Core Components 2.5.0 all components are supported. Only the “Sharing” component is excluded. In cases where multiple versions of core components exists only the latest (v2) version is supported.
The component overview marks the components that are enhanced by either URL, Link, Media or RichText Handler. The other components are untouched.
Wherever possible the enhancement was implemented in a way to extend and not overwrite existing functionality. That means if some new features are added to the AEM Sites Core Component there is a good chance this works out-of-the-box also for the WCM Core Components.
Usage
The usage is simple - you use the same “Proxy Component Pattern” that is required for the AEM Sites Core Components. But instead of their resource type, you use the resource type provided by the WCM Core Components. Example:
You want to use the title component with resource type
wcm-io/wcm/core/components/title/v2/titleCreate your own proxy component e.g. at
/apps/my-application/components/titlewithsling:resourceSuperType = wcm-io/wcm/core/components/title/v2/titleMake sure to reference only your project-specific resource type
my-application/components/titlein your application and content
Component Library
Following the example of the AEM Sites Core Components, the WCM Core Components also provide a component library that can be installed locally and used as a show-case for all core components. It’s also possible to try out the edit mode and the content policies.
See wcm.io WCM Core Component Library for further instructions.
Future Outlook
We will provide new releases for each new release of the AEM Sites Core Components, that introduces new features.
Furthermore we plan to get in touch with the AEM Sites Core Component team to work with them together to fine-tune and improve the APIs to make it easier to apply the wcm.io Enhancements to it and reduce the need to overlay scripts or duplicate logic.