Skip to content

Adding to Existing Project

Jump to bottom
Chris Bohnert edited this page Oct 28, 2022 · 5 revisions

Adding Email Core Components to an Existing Project

This wiki explains how to integrate the Email Core Components into an existing AEM project.

Overview

Integrating the Email Core Components into an existing project consists of four steps:

  1. Add Core Email Components dependencies to all package.
  2. Add proxy components for the Email Core Components.
  3. Add an email clientlib to include the Email Core Component styles.
  4. Add sample content.

This wiki provides example code for each step and assumes basic familiarity with AEM development projects. The code is based on the AEM Project Archetype.

Add Core Email Components Dependencies to all Package

You first add the dependency in your pom.xml file.

...
    <core.email.components.version>0.18.0</core.email.components.version>
  </properties>
...
      <dependency>
         <groupId>com.adobe.cq</groupId>
         <artifactId>core.email.components.core</artifactId>
         <version>${core.email.components.version}</version>                    
       </dependency>

       <dependency>
         <groupId>com.adobe.cq</groupId>
         <artifactId>core.email.components.content</artifactId>
         <version>${core.email.components.version}</version>
         <type>zip</type>
       </dependency>
...

Then the Email Core Components must be added to your project's all package. You do this by including the necessary lines in your all/pom.xml file.

...
                     <embedded>
                             <groupId>com.adobe.cq</groupId>
                             <artifactId>core.email.components.core</artifactId>
                             <target>/apps/myemailsite-packages/application/install</target>
                         </embedded>
                         <embedded>
                             <groupId>com.adobe.cq</groupId>
                             <artifactId>core.email.components.content</artifactId>
                             <type>zip</type>
                             <target>/apps/myemailsite-packages/application/install</target>
                         </embedded>
...
        <dependency>
             <groupId>com.adobe.cq</groupId>
             <artifactId>core.email.components.core</artifactId>
         </dependency>
         <dependency>
             <groupId>com.adobe.cq</groupId>
             <artifactId>core.email.components.content</artifactId>
             <type>zip</type>
         </dependency>
...

Add Proxy Components for the Email Core Components

AEM best practice require the creation of proxy components so your project does not point directly to the Email Core Components themselves. You can find more about this proxy pattern in the Core Components documentation.

You do this by adding the necessary .content.xml files representing each component. The following is an example of the Title Component under the path ui.apps/src/main/content/jcr_root/apps/<yoursite>/components/email/title/.content.xml, but would need to be replicated for every Email Core Component.

<?xml version="1.0" encoding="UTF-8"?>
 <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ~ Copyright 2022 Adobe
   ~
   ~ Licensed under the Apache License, Version 2.0 (the "License");
   ~ you may not use this file except in compliance with the License.
   ~ You may obtain a copy of the License at
   ~
   ~     http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Unless required by applicable law or agreed to in writing, software
   ~ distributed under the License is distributed on an "AS IS" BASIS,
   ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   ~ See the License for the specific language governing permissions and
   ~ limitations under the License.
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
     jcr:description="Title Component for the Core E-Mail Components Library"
     jcr:primaryType="cq:Component"
     jcr:title="Title"
     sling:resourceSuperType="core/email/components/title/v1/title"
     componentGroup="My E-Mail enabled Site - E-Mail"/>

Add an Email clientlib to Include the Email Core Component Styles

AEM's mechanism for providing the CSS necessary for its content pages is the clientlib. You must add a clientlib for the Email Core Components to your project.

In the file ui.apps/src/main/content/jcr_root/apps/<yoursite>/clientlibs/clientlib-email/.content.xml

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
     jcr:primaryType="cq:ClientLibraryFolder"
     allowProxy="{Boolean}true"
     categories="[myemailsite.email]"
     embed="[core.email.components.container,core.wcm.components.tabs.v1,core.email.components.experiencefragment,core.email.components.teaser,core.email.components.image.v1.image,core.email.components.text.v1.text,core.email.components.segmentation.v1.segmentation]"/>

Add your CSS and JS to the following files:

  • ui.apps/src/main/content/jcr_root/apps/<yoursite>/clientlibs/clientlib-email/css.txt.
  • ui.apps/src/main/content/jcr_root/apps/<yoursite>/clientlibs/clientlib-email/js.txt

Add Some Sample Content

Finally, you need to add some sample content that makes use of the Email Core Components via your proxy components.

ui.content/src/main/content/META-INF/vault/filter.xml

Make sure that you update your vault filter to include the Email Core Components.

<?xml version="1.0" encoding="UTF-8"?>
 <workspaceFilter version="1.0">
     <filter root="/conf/myemailsite" mode="merge"/>
     <filter root="/content/myemailsite" mode="merge"/>
     <filter root="/content/campaigns/myemailsite" mode="merge"/>
     <filter root="/content/dam/myemailsite/asset.jpg" mode="merge"/>
     <filter root="/content/experience-fragments/<yoursite>" mode="merge"/>
 </workspaceFilter>

ui.content/src/main/content/jcr_root/conf//settings/wcm/policies/.content.xml

Create the necessary policies for your components.

...
<wcm jcr:primaryType="nt:unstructured">
         <foundation jcr:primaryType="nt:unstructured">
             <components jcr:primaryType="nt:unstructured">
                 <responsivegrid jcr:primaryType="nt:unstructured">
                     <policy_email_structure
                         jcr:primaryType="nt:unstructured"
                         jcr:title="Core Email Components Examples - Structure"
                         sling:resourceType="wcm/core/components/policy/policy"
                         components="[group:My E-Mail enabled Site - E-Mail]">
                         <jcr:content jcr:primaryType="nt:unstructured"/>
                     </policy_email_structure>
                 </responsivegrid>
             </components>
         </foundation>
     </wcm>
...
 <email jcr:primaryType="nt:unstructured">
                 <page jcr:primaryType="nt:unstructured">
                     <policy
                         jcr:description="Includes the required client libraries."
                         jcr:primaryType="nt:unstructured"
                         jcr:title="E-Mail Page"
                         sling:resourceType="wcm/core/components/policy/policy"
                         clientlibs="[myemailsite.email]">
                         <jcr:content jcr:primaryType="nt:unstructured"/>
                     </policy>
                 </page>
             </email>
...

ui.content/src/main/content/jcr_root/conf//settings/wcm/template-types/email/.content.xml

Create template types using the components.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
           jcr:mixinTypes="[mix:lockable]"
           jcr:primaryType="cq:Template"
           ranking="{Long}1">
     <jcr:content
         jcr:primaryType="cq:PageContent"
         jcr:title="Email"
         acMapping="mapRecipient"/>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/template-types/email/initial/.content.xml

Create initial content for your template types.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
           jcr:primaryType="cq:Page">
     <jcr:content
         jcr:primaryType="cq:PageContent"
         sling:resourceType="<yoursite>/components/email/page"/>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/template-types/email/policies/.content.xml

Create policies for your template types.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
           jcr:primaryType="cq:Page">
     <jcr:content
         jcr:primaryType="nt:unstructured"
         sling:resourceType="wcm/core/components/policies/mappings">
         <root
             cq:policy="wcm/foundation/components/responsivegrid/content-default"
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/core/components/policies/mapping"/>
     </jcr:content>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/template-types/email/structure/.content.xml

Add structure to your template types.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
           jcr:primaryType="cq:Page">
     <jcr:content
         jcr:primaryType="cq:PageContent"
         sling:resourceType="core-email-components-examples/components/page">
         <root
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/foundation/components/responsivegrid"/>
     </jcr:content>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/templates/email-content/.content.xml

Add content to your templates.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:rep="internal"
     jcr:mixinTypes="[rep:AccessControllable]"
     jcr:primaryType="cq:Template">
     <jcr:content
         cq:lastModified="{Date}2022-06-02T16:21:11.920+02:00"
         cq:lastModifiedBy="admin"
         cq:templateType="/conf/<yoursite>/settings/wcm/template-types/email"
         jcr:primaryType="cq:PageContent"
         jcr:title="Email Template"
         status="enabled"/>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/templates/email-content/_rep_policy.xml

Update the template policy.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:crx="http://www.day.com/crx/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:rep="internal"
     jcr:primaryType="rep:ACL">
     <allow
         jcr:primaryType="rep:GrantACE"
         rep:principalName="everyone"
         rep:privileges="{Name}[jcr:read]"/>
     <allow1
         jcr:primaryType="rep:GrantACE"
         rep:principalName="content-authors"
         rep:privileges="{Name}[crx:replicate]"/>
     <allow2
         jcr:primaryType="rep:GrantACE"
         rep:principalName="template-authors"
         rep:privileges="{Name}[jcr:versionManagement,rep:write,crx:replicate,jcr:lockManagement]"/>
     <allow3
         jcr:primaryType="rep:GrantACE"
         rep:principalName="version-manager-service"
         rep:privileges="{Name}[jcr:versionManagement,rep:write]"/>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/templates/email-content/initial/.content.xml

Define initial content for the templates.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
     xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:template="/conf/<yoursite>/settings/wcm/templates/email-content"
         jcr:primaryType="cq:PageContent"
         sling:resourceType="myemailsite/components/email/page"
         acMapping="mapRecipient"
         acTemplateId="mailAEMContent"
         acTemplateLabel="Email delivery with AEM content">
         <root
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/foundation/components/responsivegrid">
             <container
                 jcr:primaryType="nt:unstructured"
                 sling:resourceType="myemailsite/components/email/container"
                 layout="3-3">
                 <col-0
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
                 <col-1
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
                 <col-2
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
             </container>
         </root>
     </jcr:content>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/templates/email-content/policies/.content.xml

Add policies for your templates.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
     xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:lastModified="{Date}2022-06-02T15:52:20.366+02:00"
         cq:lastModifiedBy="admin"
         cq:policy="<yoursite>/components/email/page/policy"
         jcr:primaryType="nt:unstructured"
         sling:resourceType="wcm/core/components/policies/mappings">
         <root
             cq:policy="wcm/foundation/components/responsivegrid/policy_email_structure"
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/core/components/policies/mapping">
             <container
                 jcr:primaryType="nt:unstructured"
                 sling:resourceType="wcm/core/components/policies/mapping">
                 <col-0
                     cq:policy="wcm/foundation/components/responsivegrid/policy_column"
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/core/components/policies/mapping"/>
                 <col-1
                     cq:policy="wcm/foundation/components/responsivegrid/policy_column"
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/core/components/policies/mapping"/>
                 <col-2
                     cq:policy="wcm/foundation/components/responsivegrid/policy_column"
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/core/components/policies/mapping"/>
             </container>
         </root>
     </jcr:content>
 </jcr:root>

ui.content/src/main/content/jcr_root/conf//settings/wcm/templates/email-content/structure/.content.xml

Add structure to your email templates.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
     xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:template="/conf/<yoursite>/settings/wcm/templates/email-content"
         jcr:primaryType="cq:PageContent"
         sling:resourceType="myemailsite/components/email/page"
         acMapping="mapRecipient"
         acTemplateId="mailAEMContent"
         acTemplateLabel="Email delivery with AEM content">
         <root
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/foundation/components/responsivegrid"
             editable="{Boolean}true"/>
     </jcr:content>
 </jcr:root>

ui.content/src/main/content/jcr_root/content/campaigns/.content.xml

Add folder to hold your campaign content.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:rep="internal"
     jcr:mixinTypes="[rep:AccessControllable]"
     jcr:primaryType="sling:Folder"/>

ui.content/src/main/content/jcr_root/content/campaigns//.content.xml

Add content to your campaign folder.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:allowedTemplates="[/libs/cq/personalization/templates/.*,/libs/mcm/templates/brand,/apps/.*/templates/newsletter.*,.*/designimporter/templates/.*,/libs/commerce/templates/promotion,/libs/commerce/templates/voucher,/apps/.*/templates/.*newsletter.*,/libs/mcm/campaign/templates/ac-email.*,/conf/core-email-components-examples/settings/wcm/templates/email-template]"
         cq:lastModified="{Date}2022-03-09T08:32:21.308Z"
         cq:lastModifiedBy="noor"
         cq:template="/libs/mcm/templates/brand"
         jcr:primaryType="cq:PageContent"
         jcr:title="E-Mail enabled Site - Campaigns"
         sling:resourceType="mcm/components/brandpage">
         <par
             jcr:primaryType="nt:unstructured"
             sling:resourceType="foundation/components/parsys"/>
     </jcr:content>
     <master/>
 </jcr:root>

ui.content/src/main/content/jcr_root/content/campaigns//master/.content.xml

Add content to the language master.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:cloudserviceconfigs="[/etc/cloudservices/campaign/ac-dev]"
         cq:lastModified="{Date}2022-03-07T14:00:00.308Z"
         cq:lastModifiedBy="stein"
         cq:template="/libs/cq/personalization/templates/ambit"
         jcr:primaryType="cq:PageContent"
         jcr:title="Master Area"
         sling:resourceType="cq/personalization/components/ambitpage">
         <par
             jcr:primaryType="nt:unstructured"
             sling:resourceType="foundation/components/parsys"/>
     </jcr:content>
     <core-email-spender/>
 </jcr:root>

ui.content/src/main/content/jcr_root/content/campaigns//master/core-email-spender/.content.xml

Add content for the email spender.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:lastModified="{Date}2016-05-16T19:18:14.325+02:00"
         cq:lastModifiedBy="admin"
         cq:targetEngine="cq_contexthub"
         cq:template="/libs/cq/personalization/templates/campaign"
         jcr:primaryType="cq:PageContent"
         jcr:title="My E-Mail enabled Site - Campaign"
         sling:resourceType="cq/personalization/components/campaignpage"
         priority="1">
         <par
             jcr:primaryType="nt:unstructured"
             sling:resourceType="foundation/components/parsys"/>
         <cq:ActivitySettings jcr:primaryType="nt:unstructured"/>
     </jcr:content>
     <ordervalue75to100/>
     <ordervalueover100/>
     <e-mail-test-page/>
 </jcr:root>

ui.content/src/main/content/jcr_root/content/campaigns//master/core-email-spender/email-page/.content.xml

Add content for the email spender page.

<?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
     jcr:primaryType="cq:Page">
     <jcr:content
         cq:lastModified="{Date}2022-03-10T21:07:32.411Z"
         cq:lastModifiedBy="admin"
         cq:template="/conf/<yoursite>/settings/wcm/templates/email-content"
         jcr:primaryType="cq:PageContent"
         jcr:title="E-Mail Test Page"
         sling:resourceType="<yoursite>/components/email/page"
         acMapping="mapRecipient"
         acTemplateId="mailAEMContent"
         acTemplateLabel="Email delivery with AEM content">
         <root
             jcr:primaryType="nt:unstructured"
             sling:resourceType="wcm/foundation/components/responsivegrid">
             <container
                 jcr:primaryType="nt:unstructured"
                 sling:resourceType="myemailsite/components/email/container"
                 layout="3-3">
                 <col-0
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
                 <col-1
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
                 <col-2
                     jcr:primaryType="nt:unstructured"
                     sling:resourceType="wcm/foundation/components/responsivegrid"/>
             </container>
         </root>
     </jcr:content>
 </jcr:root>

Wiki Home

Clone this wiki locally