Merge pull request #897 from adobe/develop

v2.5.4

core/src/main/java/com/adobe/aem/commons/assetshare/components/assetkit/AssetKit.java

@@ -26,10 +26,26 @@
 import java.util.Collection;
 @ProviderType
 public interface AssetKit extends Component {
+    /**
+     * Returns the assets that are part of this Asset Kit.
+     * The assets are returned as as AssetModels, so ComputedProperties can used to display relevant data.
+     * @return a Collection of AssetModels
+     */    
     Collection<? extends AssetModel> getAssets();
+
+    /**
+     * Returns true is the component is ready to display. This is used to determine if the component's Page Editor edit box should display or not.
+     */
     boolean isReady();
 
     @ConsumerType
+    /**
+     * A Filter is used to filter the assets that are part of the Asset Kit.
+     * 
+     * This acts as an OSGi service interface that can be implemented with a service.ranking > 10000 to override default filtering behavior.
+     * The Asset Share Commons provided filter removed the "banner image asset" from the asset kit listing (AssetKitFilterImpl.java).
+     * If the logic for defining the banner image changes a custom Filter would need to be developed.
+     */
     interface Filter {
         Collection<? extends AssetModel> filter(Collection<? extends AssetModel> assets);
     }

core/src/main/java/com/adobe/aem/commons/assetshare/util/assetkit/AssetKitHelper.java

@@ -27,7 +27,11 @@
 
 import javax.jcr.RepositoryException;
 import java.util.Collection;
+
 @ProviderType
+/**
+ * A helper class for working with the Asset Kit. Typically use in custom ComponentUpdater implementations or custom AssetKit component Sling Models.
+ */
 public interface AssetKitHelper {
     /**
      * Gets a collection of assets that at or exist under the paths provided.

core/src/main/java/com/adobe/aem/commons/assetshare/util/assetkit/ComponentUpdater.java

@@ -26,11 +26,33 @@
 import javax.jcr.RepositoryException;
 
 @ConsumerType
+/**
+ * A component updater is used to update the components on an asset kit page based on the asset kit's payload.
+ */
 public interface ComponentUpdater {
-
+    /**
+     * The name of the component updater. Displays in the Asset kit creator workflow dialog's dropdown.
+     * @return the name of the component updater. Ideally is unique across all component updaters, so you can tell which is which.
+     */
     String getName();
 
+    /**
+     * The id of the component updater. Used to identify the component updater in the workflow dialog.
+     * Must be unique across all component updaters.
+     * Defaults to the component's full class name. No need to change the default implementation.
+     * @return
+     */
     default String getId() { return this.getClass().getName(); }
 
+    /**
+     * Entry point for updating the @{code assetKitPage} based on the @{code assetKit} payload resource.
+     * 
+     * This can do anything, it can find and updated existing components created by the template's initial content, or it can create new resources under the page (or anywhere it has write access).
+     * 
+     * @param assetKitPage the asset kit page being updated.
+     * @param assetKit the resource (folder, collection) that represents the asset kit's contents.
+     * @throws PersistenceException
+     * @throws RepositoryException
+     */
     void updateComponent(Page assetKitPage, Resource assetKit) throws PersistenceException, RepositoryException;
 }

core/src/main/java/com/adobe/aem/commons/assetshare/util/assetkit/PagePathGenerator.java

@@ -5,8 +5,25 @@
 
 @ConsumerType
 public interface PagePathGenerator {
+    /**
+     * The name of the page path generator. Displays in the Asset kit creator workflow dialog's dropdown.
+     * @return the name of the page path generator. Ideally is unique across all page path generator, so you can tell which is which.
+     */    
     String getName();
 
+    /**
+     * The id of the component updater. Used to identify the component updater in the workflow dialog.
+     * Must be unique across all component updaters.
+     * Defaults to the component's full class name. No need to change the default implementation.
+     * @return the unique id of the page path generator.
+     */
     default String getId() { return this.getClass().getName(); }
+
+    /**
+     * Generates a page path based on the @{code prefix} and @{code assetKit} resource.
+     * @param prefix the JCR path prefix all asset kit pages will be created under. This is defined in the Asset Kit creator workflow dialog.
+     * @param assetKit the resource (folder, collection) that represents the asset kit's contents.
+     * @return the full JCR path of the asset kit page.
+     */
     String generatePagePath(String prefix, Resource assetKit);
 }

core/src/main/java/com/adobe/aem/commons/assetshare/util/assetkit/impl/componentupdaters/AssetKitComponentUpdaterImpl.java

@@ -24,17 +24,23 @@
 import com.day.cq.wcm.api.Page;
 import org.apache.sling.api.resource.PersistenceException;
 import org.apache.sling.api.resource.Resource;
+import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Modified;
 import org.osgi.service.component.annotations.Reference;
+import org.osgi.service.metatype.annotations.AttributeDefinition;
+import org.osgi.service.metatype.annotations.Designate;
+import org.osgi.service.metatype.annotations.ObjectClassDefinition;
 
 import javax.jcr.RepositoryException;
 @Component
+@Designate(ocd = AssetKitComponentUpdaterImpl.Config.class)
 public class AssetKitComponentUpdaterImpl implements ComponentUpdater {
-    private static String RESOURCE_TYPE = AssetKitImpl.RESOURCE_TYPE;
     private static String PROPERTY_NAME = "paths";
 
     @Reference
     private transient AssetKitHelper assetKitHelper;
+    private Config config;
 
     @Override
     public String getName() {
@@ -43,6 +49,24 @@ public String getName() {
 
     @Override
     public void updateComponent(Page assetKitPage, Resource assetKit) throws PersistenceException, RepositoryException {
-        assetKitHelper.updateComponentOnPage(assetKitPage, RESOURCE_TYPE, PROPERTY_NAME, assetKit.getPath());
+        assetKitHelper.updateComponentOnPage(assetKitPage, config.resource_type(), PROPERTY_NAME, assetKit.getPath());
+    }
+
+    @Activate
+    @Modified
+    protected void activate(Config config) {
+        this.config = config;
+    }
+
+    @ObjectClassDefinition(
+        name = "Asset Share Commons - Asset Kit Component Updater",
+        description = "Component updater that updates an Asset Kit component"
+    )
+    @interface Config {
+        @AttributeDefinition(
+            name = "Resource Type",
+            description = "The resource type of the component to update."
+        )
+        String resource_type() default AssetKitImpl.RESOURCE_TYPE;
     }
 }

core/src/main/java/com/adobe/aem/commons/assetshare/util/assetkit/impl/componentupdaters/BannerComponentUpdaterImpl.java

@@ -18,30 +18,37 @@
  */
 package com.adobe.aem.commons.assetshare.util.assetkit.impl.componentupdaters;
 
+import com.adobe.aem.commons.assetshare.components.assetkit.impl.AssetKitImpl;
 import com.adobe.aem.commons.assetshare.content.AssetModel;
 import com.adobe.aem.commons.assetshare.util.assetkit.AssetKitHelper;
 import com.adobe.aem.commons.assetshare.util.assetkit.ComponentUpdater;
 import com.day.cq.wcm.api.Page;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.sling.api.resource.PersistenceException;
 import org.apache.sling.api.resource.Resource;
+import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Modified;
 import org.osgi.service.component.annotations.Reference;
+import org.osgi.service.metatype.annotations.AttributeDefinition;
+import org.osgi.service.metatype.annotations.Designate;
+import org.osgi.service.metatype.annotations.ObjectClassDefinition;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import javax.jcr.RepositoryException;
 import java.util.Collection;
+
 @Component
+@Designate(ocd = BannerComponentUpdaterImpl.Config.class)
 public class BannerComponentUpdaterImpl implements ComponentUpdater {
     private static final Logger log = LoggerFactory.getLogger(BannerComponentUpdaterImpl.class);
 
-    private static String RESOURCE_TYPE =  "asset-share-commons/components/content/image";
-    private static String PROPERTY_NAME = "fileReference";
-
     @Reference
     private transient AssetKitHelper assetKitHelper;
 
+    private Config config;
+
     @Override
     public String getName() {
         return "Banner component (Asset Share Commons)";
@@ -54,10 +61,34 @@ public void updateComponent(Page assetKitPage, Resource assetKit) {
 
         assets.stream().filter(asset -> StringUtils.equals("banner", StringUtils.lowerCase(asset.getTitle()))).findFirst().ifPresent(asset -> {
             try {
-                assetKitHelper.updateComponentOnPage(assetKitPage, RESOURCE_TYPE, PROPERTY_NAME, asset.getPath());
+                assetKitHelper.updateComponentOnPage(assetKitPage, config.resource_type(), config.banner_asset_path_property(), asset.getPath());
             } catch (PersistenceException | RepositoryException e) {
                 log.error(String.format("Failed to update banner component on page [ %s ]", assetKitPage.getPath()), e);
             }
         });
     }
+
+    @Activate
+    @Modified
+    protected void activate(Config config) {
+        this.config = config;
+    }
+
+    @ObjectClassDefinition(
+        name = "Asset Share Commons - Banner Component Updater",
+        description = "Component updater that updates an Banner component"
+    )
+    @interface Config {
+        @AttributeDefinition(
+            name = "Resource Type",
+            description = "The resource type of the component to update."
+        )
+        String resource_type() default "asset-share-commons/components/content/image";
+
+        @AttributeDefinition(
+            name = "Banner asset property",
+            description = "The property name that holds the banner asset's path."
+        )
+        String banner_asset_path_property() default "fileReference";
+    }
 }