New Project Guide

AEM Project Archetype

Start by generating a vanilla project using the AEM Project archetype.

For example:

mvn -B archetype:generate \
 -D archetypeGroupId=com.adobe.aem \
 -D archetypeArtifactId=aem-project-archetype \
 -D archetypeVersion=39 \
 -D appTitle="My Asset Share" \
 -D appId="my-asset-share" \
 -D groupId="com.myassetshare"

Add Asset Share Commons as a dependency

In the <dependencies> section of your project’s parent pom.xml (root of the project) add the following dependencies:

When deploying to AEM as a Cloud Service

<!-- parent pom.xml -->
<dependencies>
   ...
   <dependency>
    <groupId>com.adobe.aem.commons</groupId>
    <artifactId>assetshare.all</artifactId>
    <version>3.8.18</version>
    <classifier>cloud</classifier>
    <type>zip</type>
  </dependency>

  <!-- Optional dependency to code against Asset Share Commons APIs -->
  <dependency>
    <groupId>com.adobe.aem.commons</groupId>
    <artifactId>assetshare.core</artifactId>
    <version>3.8.18</version>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.adobe.aem.commons</groupId>
    <artifactId>assetshare.core.cloud</artifactId>    
    <version>3.8.18</version>
    <type>jar</type>
  </dependency>
  ...
<dependencies>

When deploying to AEM 6.5.x

<!-- parent pom.xml -->
<dependencies>
   ...
   <dependency>
    <groupId>com.adobe.aem.commons</groupId>
    <artifactId>assetshare.all</artifactId>
    <version>3.8.18</version>
    <type>zip</type>
  </dependency>

  <!-- Optional dependency to code against Asset Share Commons APIs -->
  <dependency>
    <groupId>com.adobe.aem.commons</groupId>
    <artifactId>assetshare.core</artifactId>
    <version>3.8.18</version>
    <type>jar</type>
  </dependency>
  ...
<dependencies>

Embed Asset Share Commons in All module

Include Asset Share Commons 2.x’s all project as an embedded in your AEM Maven project’s all/pom.xml.

When deploying to AEM as a Cloud Service

  1. Add the Asset Share Commons all project with cloud classifier as a <dependency>.

     <dependencies>
     ...
     <dependency>
         <groupId>com.adobe.aem.commons</groupId>
         <artifactId>assetshare.all</artifactId>
         <classifier>cloud</classifier> <!-- MUST ADD FOR AEM AS A CLOUD SERVICE  -->
         <type>zip</type>
     </dependency>
     ...
 </dependency>

  2. Add the assetshare.all dependency with cloud classifier to your all/pom.xml’s <embeddeds> list as a container.

     <plugins>
     <plugin>
         <groupId>org.apache.jackrabbit</groupId>
         <artifactId>filevault-package-maven-plugin</artifactId>
         ...
         <configuration>
             <allowIndexDefinitions>true</allowIndexDefinitions>
             ...
             <embeddeds>
                 <embedded>
                     <groupId>com.adobe.aem.commons</groupId>
                     <artifactId>assetshare.all</artifactId>
                     <classifier>cloud</classifier> <!-- MUST ADD FOR AEM AS A CLOUD SERVICE  -->
                     <type>zip</type>
                     <target>/apps/<my-app>-packages/container/install</target>
                 </embedded>
                 ...

When deploying to AEM 6.5.x

  1. Add the Asset Share Commons all project as <dependency>.

     <dependencies>
     ...
     <dependency>
         <groupId>com.adobe.aem.commons</groupId>
         <artifactId>assetshare.all</artifactId>
         <!-- OMIT CLASSIFIER FOR AEM 6.5  -->
         <type>zip</type>
     </dependency>
     ...
 </dependency>

  2. Add the assetshare.all dependency to your all/pom.xml’s <embeddeds> list as a container.

     <plugins>
     <plugin>
         <groupId>org.apache.jackrabbit</groupId>
         <artifactId>filevault-package-maven-plugin</artifactId>
         ...
         <configuration>
             <allowIndexDefinitions>true</allowIndexDefinitions>
             ...
             <embeddeds>
                 <embedded>
                     <groupId>com.adobe.aem.commons</groupId>
                     <artifactId>assetshare.all</artifactId>
                     <type>zip</type>
                     <target>/apps/<my-app>-packages/container/install</target>
                 </embedded>
                 ...

(Optional) Custom development using Asset Share Commons APIs

  1. Optionally, include the assetshare.core as a dependency in your AEM project’s core/pom.xml if you plan developing Java code against Asset Share Commons’ APIs.

When deploying to AEM as a Cloud Service

```
<dependencies>
    ...
    <dependency>
        <groupId>com.adobe.aem.commons</groupId>
        <artifactId>assetshare.core</artifactId>
        <type>jar</type>
    </dependency>
    <dependency>
        <groupId>com.adobe.aem.commons</groupId>
        <artifactId>assetshare.core.cloud</artifactId>
        <type>jar</type>
    </dependency>	
    ...
</dependency>    
```

When deploying to AEM 6.5.x

```
<dependencies>
    ...
    <dependency>
        <groupId>com.adobe.aem.commons</groupId>
        <artifactId>assetshare.core</artifactId>
        <type>jar</type>
    </dependency>
    ...
</dependency>    
```

Update Dispatcher module

When generating a project via the archetype a Dispatcher module is created.

  1. Update the filter.any file to include the following filters.

  2. Make a copy of the default.farm, i.e asset-share-commons.farm at src/conf.dispatcher.d/available_farms/default.farm.
  3. Update the new farm to include the following headers to enable cache-able HTTP request headers)
  4. Update the symbolic link at dispatcher/src/conf.dispatcher.d/enabled_farms to point to the new farm.

Update the Frontend module

Asset Share Commons ships with two themes Light and Dark. These can be used directly. If you would like to customize the theme to match your brand’s colors perform the following steps:

  1. In your project remove the contents of the directory ui.frontend except for the ui.frontend/pom.xml file.
  2. Download the contents of either the Light or Dark. It is far easier to start from one of the sample themes.
  3. Copy the entire contents of the previous step into your project’s ui.frontend folder. Do not copy the pom.xml file from the Asset Share Commons repo.

  4. Open the file ui.frontend/clientlib.config.js. Make the following changes:

    1. Update the clientLibRoot to match your project:

       clientLibRoot: "./../ui.apps/src/main/content/jcr_root/apps/<my-app>/clientlibs"
    2. Update the name from semanticui-light to clientlib-site.
    3. Update the categories from asset-share-commons.semantic-ui-light to <my-app>-asset-share.theme.
  5. Make a change to the file ui.frontend/semanticui/site/globals/site.variables such as updating @primaryColor.

Update sample content

Asset Share Commons includes templates and a series of pages pre-configured. A Light and Dark set of content is included. These can be used as is. For more granular control, copy these templates and pages into your projects ui.content folder and modify to match your projects needs.

  1. In your project’s ui.content module remove the folder at: ui.content/src/main/content/jcr_root/conf/<your-app>/settings/wcm.
  2. Replace the wcm folder with Asset Share Common’s wcm folder.
  3. If using the Light theme as a base, under wcm/templates remove the Dark theme templates ( or vice-versa).
  4. Remove the content under: ui.content/src/main/content/jcr_root/content/<your-app>/us/en and replace with either the Light set of pages or Dark set.
  5. Perform a find+replace across files, to modify any references to /conf/asset-share-commons/settings/wcm with /conf/<your-app>/settings/wcm. There should be 30 references across 30 files to update.
  6. Open the policies file at ui.content/src/main/content/jcr_root/conf/<your-app>/settings/wcm/policies/.content.xml.
  7. Find and replace any references to asset-share-commons.semantic-ui-light and replace with the category used for your custom clientlib from the ui.frontend module i.e <my-app>-asset-share.theme. There should be 3 references.
  8. Perform a find+replace across files and modify any references to /content/asset-share-commons/en/light with /content/<your-app>/us/en.

Example project

An example project has been created for the WKND Brand:

WKND Asset Share

You can view the source code for the project here.