@releng - 2.6.0 Pre-release - Update Documentation (#721)

- ./fragmentPath -> ./fragmentVariationPath
- getLocalizedFragmentPath -> getLocalizedFragmentVariationPath
- adds experience fragment component to main README
- adds 2.6.0 release to main README and VERSIONS
- improvements to experience fragment README
- improvements to experience fragment library page
- removes unused xf variation in component library
- JavaDoc fixes
- misc. text fixes
- validates in the XF Model that the path points to an XF variation
- adds the correct validator to the xf variation field

.circleci/config.yml

@@ -36,7 +36,7 @@ shared: &shared
     # run tests!
     - run: mvn clean verify -B -U
 
-    # store any dumps
+    # save any dumps
     - run:
         name: save any dumps
         command: |
@@ -51,7 +51,7 @@ shared: &shared
 
     # save test results
     - run:
-        name: Save test results
+        name: save test results
         command: |
             mkdir -p ~/test-results/junit/
             find . -type f -regex ".*/surefire-reports/.*" -exec cp {} ~/test-results/junit/ \;

README.md

@@ -42,28 +42,29 @@ You can also subscribe via Email [aem-core-components-dev+subscribe@googlegroups
 7. [Title](content/src/content/jcr_root/apps/core/wcm/components/title/v2/title)
 8. [Image](content/src/content/jcr_root/apps/core/wcm/components/image/v2/image)
 9. [Download](content/src/content/jcr_root/apps/core/wcm/components/download/v1/download)
-10. [Teaser](content/src/content/jcr_root/apps/core/wcm/components/teaser/v1/teaser)
-11. [Button](content/src/content/jcr_root/apps/core/wcm/components/button/v1/button)
-16. [List](content/src/content/jcr_root/apps/core/wcm/components/list/v2/list)
+10. [Experience Fragment](content/src/content/jcr_root/apps/core/wcm/components/experiencefragment/v1/experiencefragment)
+11. [Teaser](content/src/content/jcr_root/apps/core/wcm/components/teaser/v1/teaser)
+12. [Button](content/src/content/jcr_root/apps/core/wcm/components/button/v1/button)
+13. [List](content/src/content/jcr_root/apps/core/wcm/components/list/v2/list)
 14. [Content Fragment](content/src/content/jcr_root/apps/core/wcm/components/contentfragment/v1/contentfragment)
 15. [Content Fragment List](content/src/content/jcr_root/apps/core/wcm/components/contentfragmentlist/v1/contentfragmentlist)
-12. [Separator](content/src/content/jcr_root/apps/core/wcm/components/separator/v1/separator)
-13. [Sharing](content/src/content/jcr_root/apps/core/wcm/components/sharing/v1/sharing)
+16. [Separator](content/src/content/jcr_root/apps/core/wcm/components/separator/v1/separator)
+17. [Sharing](content/src/content/jcr_root/apps/core/wcm/components/sharing/v1/sharing)
 
 ### Container components
 
-17. [Container](content/src/content/jcr_root/apps/core/wcm/components/container/v1/container)
-18. [Carousel](content/src/content/jcr_root/apps/core/wcm/components/carousel/v1/carousel)
-19. [Accordion](content/src/content/jcr_root/apps/core/wcm/components/accordion/v1/accordion)
-20. [Tabs](content/src/content/jcr_root/apps/core/wcm/components/tabs/v1/tabs)
+18. [Container](content/src/content/jcr_root/apps/core/wcm/components/container/v1/container)
+19. [Carousel](content/src/content/jcr_root/apps/core/wcm/components/carousel/v1/carousel)
+20. [Accordion](content/src/content/jcr_root/apps/core/wcm/components/accordion/v1/accordion)
+21. [Tabs](content/src/content/jcr_root/apps/core/wcm/components/tabs/v1/tabs)
 
 ### Form components
 
-21. [Form container](content/src/content/jcr_root/apps/core/wcm/components/form/container/v2/container)
-22. [Form text field](content/src/content/jcr_root/apps/core/wcm/components/form/text/v2/text)
-23. [Form options field](content/src/content/jcr_root/apps/core/wcm/components/form/options/v2/options)
-24. [Form hidden field](content/src/content/jcr_root/apps/core/wcm/components/form/hidden/v2/hidden)
-25. [Form button](content/src/content/jcr_root/apps/core/wcm/components/form/button/v2/button)
+22. [Form container](content/src/content/jcr_root/apps/core/wcm/components/form/container/v2/container)
+23. [Form text field](content/src/content/jcr_root/apps/core/wcm/components/form/text/v2/text)
+24. [Form options field](content/src/content/jcr_root/apps/core/wcm/components/form/options/v2/options)
+25. [Form hidden field](content/src/content/jcr_root/apps/core/wcm/components/form/hidden/v2/hidden)
+26. [Form button](content/src/content/jcr_root/apps/core/wcm/components/form/button/v2/button)
 
 Visit the [roadmap wiki page](https://github.com/adobe/aem-core-wcm-components/wiki) for main upcoming components and features.
 
@@ -77,7 +78,7 @@ The latest version of the Core Components, require the below system requirements
 
 Core Components | AEM 6.5 | AEM 6.4 | AEM 6.3 | Java
 ----------------|---------|---------|---------|------
-[2.5.0](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.5.0) | 6.5.0.0+ | 6.4.2.0+ | 6.3.3.0+ | 8, 11
+[2.6.0](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.6.0) | 6.5.0.0+ | 6.4.4.0+ | 6.3.3.4+ | 8, 11
 
 For a list of requirements for previous versions, see [Historical System Requirements](VERSIONS.md).
 
@@ -137,7 +138,7 @@ To include the core components package into your own project's maven build using
      <groupId>com.adobe.cq</groupId>
      <artifactId>core.wcm.components.all</artifactId>
      <type>zip</type>
-     <version>2.5.0</version>
+     <version>2.6.0</version>
  </dependency>
  ```
 
@@ -162,7 +163,7 @@ To include the core components package into your own project using AEM Archetype
      <groupId>com.adobe.cq</groupId>
      <artifactId>core.wcm.components.all</artifactId>
      <type>zip</type>
-     <version>2.5.0</version>
+     <version>2.6.0</version>
  </dependency>
  ```
 

VERSIONS.md

@@ -4,6 +4,7 @@ See below for a full list of system requirements for historical versions of the
 
 Core Components | Extension | AEM 6.5 | AEM 6.4 | AEM 6.3 | Java
 ----------------|-----------|---------|---------|---------|------
+[2.6.0](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.6.0) | - | 6.5.0.0+ | 6.4.4.0+ | 6.3.3.4+ | 8, 11
 [2.5.0](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.5.0) | - | 6.5.0.0+ | 6.4.2.0+ | 6.3.3.0+ | 8, 11
 [2.4.0](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.4.0) | - | 6.5.0.0+ | 6.4.2.0+ | 6.3.3.0+ | 8, 11
 [2.3.2](https://github.com/adobe/aem-core-wcm-components/releases/tag/core.wcm.components.reactor-2.3.2) | 1.0.12 | 6.5.0.0+ | 6.4.2.0+ | 6.3.3.0+ | 8

bundles/core/pom.xml

@@ -465,7 +465,6 @@
             <scope>test</scope>
         </dependency>
 
-
         <!-- Only required for junit 4 -->
         <dependency>
             <groupId>io.wcm</groupId>

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v1/ExperienceFragmentImpl.java

@@ -23,6 +23,7 @@
 import org.apache.sling.api.SlingHttpServletRequest;
 import org.apache.sling.api.resource.Resource;
 import org.apache.sling.api.resource.ResourceResolver;
+import org.apache.sling.api.resource.ValueMap;
 import org.apache.sling.models.annotations.Exporter;
 import org.apache.sling.models.annotations.Model;
 import org.apache.sling.models.annotations.injectorspecific.*;
@@ -33,6 +34,7 @@
 import com.adobe.cq.export.json.ComponentExporter;
 import com.adobe.cq.export.json.ExporterConstants;
 import com.adobe.cq.wcm.core.components.models.ExperienceFragment;
+import com.adobe.cq.xf.ExperienceFragmentsConstants;
 import com.day.cq.wcm.api.LanguageManager;
 import com.day.cq.wcm.api.Page;
 import com.day.cq.wcm.api.Template;
@@ -71,38 +73,41 @@ public class ExperienceFragmentImpl implements ExperienceFragment {
     @ScriptVariable
     private Page currentPage;
 
-    @ValueMapValue(name = ExperienceFragment.PN_FRAGMENT_PATH, injectionStrategy = InjectionStrategy.OPTIONAL)
-    private String fragmentPath;
+    @ValueMapValue(name = ExperienceFragment.PN_FRAGMENT_VARIATION_PATH, injectionStrategy = InjectionStrategy.OPTIONAL)
+    private String fragmentVariationPath;
 
     @OSGiService
     private LanguageManager languageManager;
 
     @OSGiService
     private LiveRelationshipManager relationshipManager;
 
-    private String localizedFragmentPath;
+    private String localizedFragmentVariationPath;
 
     @PostConstruct
     protected void initModel() {
         if (inTemplate()) {
             String currentPageRootPath = getLocalizationRoot(currentPage.getPath());
             // we should use getLocalizationRoot instead of getXfLocalizationRoot once the XF UI supports creating Live and Language Copies
-            String xfRootPath = getXfLocalizationRoot(fragmentPath, currentPageRootPath);
+            String xfRootPath = getXfLocalizationRoot(fragmentVariationPath, currentPageRootPath);
             if (!StringUtils.isEmpty(currentPageRootPath) && !StringUtils.isEmpty(xfRootPath)) {
-                String xfRelativePath = StringUtils.substring(fragmentPath, xfRootPath.length());
+                String xfRelativePath = StringUtils.substring(fragmentVariationPath, xfRootPath.length());
                 String localizedXfRootPath = StringUtils.replace(currentPageRootPath, CONTENT_ROOT, EXPERIENCE_FRAGMENTS_ROOT, 1);
-                localizedFragmentPath = StringUtils.join(localizedXfRootPath, xfRelativePath, JCR_CONTENT_ROOT);
+                localizedFragmentVariationPath = StringUtils.join(localizedXfRootPath, xfRelativePath, JCR_CONTENT_ROOT);
             }
         }
-        String xfContentPath = StringUtils.join(fragmentPath, JCR_CONTENT_ROOT);
-        if (!resourceExists(localizedFragmentPath) && resourceExists(xfContentPath)) {
-            localizedFragmentPath = xfContentPath;
+        String xfContentPath = StringUtils.join(fragmentVariationPath, JCR_CONTENT_ROOT);
+        if (!resourceExists(localizedFragmentVariationPath) && resourceExists(xfContentPath)) {
+            localizedFragmentVariationPath = xfContentPath;
+        }
+        if (!isExperienceFragmentVariation(localizedFragmentVariationPath)) {
+            localizedFragmentVariationPath = null;
         }
     }
 
     @Override
-    public String getLocalizedFragmentPath() {
-        return localizedFragmentPath;
+    public String getLocalizedFragmentVariationPath() {
+        return localizedFragmentVariationPath;
     }
 
     @NotNull
@@ -111,19 +116,19 @@ public String getLocalizedFragmentPath() {
     }
 
     /**
-     * Returns the localization root of the resource defined at the given path
+     * Returns the localization root of the resource defined at the given path.
      *
      * Use case                                  | Path                                 | Root
-     * ----------------------------------------  |--------------------------------------|------------------
+     * ------------------------------------------|--------------------------------------|------------------
      * 1. No localization                        | /content/mysite/mypage               | null
      * 2. Language localization                  | /content/mysite/en/mypage            | /content/mysite/en
      * 3. Country-language localization          | /content/mysite/us/en/mypage         | /content/mysite/us/en
      * 4. Country-language localization (variant)| /content/us/mysite/en/mypage         | /content/us/mysite/en
      * 5. Blueprint                              | /content/mysite/blueprint/mypage     | /content/mysite/blueprint
-     * 4. Livecopy                               | /content/mysite/livecopy/mypage      | /content/mysite/livecopy
+     * 6. Live Copy                              | /content/mysite/livecopy/mypage      | /content/mysite/livecopy
      *
-     * @param path the resource path.
-     * @return the localization root of the resource at the given path if it exists, {@code null} otherwise.
+     * @param path the resource path
+     * @return the localization root of the resource at the given path if it exists, {@code null} otherwise
      */
     private String getLocalizationRoot(String path) {
         String root = null;
@@ -143,8 +148,8 @@ private String getLocalizationRoot(String path) {
     /**
      * Returns the language root of the resource.
      *
-     * @param resource The resource
-     * @return The language root of the resource if it exists, {@code null} otherwise
+     * @param resource the resource
+     * @return the language root of the resource if it exists, {@code null} otherwise
      */
     private String getLanguageRoot(Resource resource) {
         Page rootPage = languageManager.getLanguageRoot(resource);
@@ -157,8 +162,8 @@ private String getLanguageRoot(Resource resource) {
     /**
      * Returns the path of the blueprint of the resource.
      *
-     * @param resource The resource
-     * @return The path of the blueprint of the resource if it exists, {@code null} otherwise
+     * @param resource the resource
+     * @return the path of the blueprint of the resource if it exists, {@code null} otherwise
      */
     private String getBlueprintPath(Resource resource) {
         try {
@@ -183,8 +188,8 @@ private String getBlueprintPath(Resource resource) {
     /**
      * Returns the path of the live copy of the resource.
      *
-     * @param resource The resource
-     * @return The path of the live copy of the resource if it exists, {@code null} otherwise
+     * @param resource the resource
+     * @return the path of the live copy of the resource if it exists, {@code null} otherwise
      */
     private String getLiveCopyPath(Resource resource) {
         try {
@@ -211,9 +216,9 @@ private String getLiveCopyPath(Resource resource) {
      * to be used with XF.
      * This method works around this issue by deducting the XF root from the XF path and the root of the current page.
      *
-     * @param xfPath The experience fragment path.
-     * @param currentPageRoot The localization root of the current page.
-     * @return The localization root of the experience fragment path if it exists, {@code null} otherwise.
+     * @param xfPath the experience fragment path
+     * @param currentPageRoot the localization root of the current page
+     * @return the localization root of the experience fragment path if it exists, {@code null} otherwise
      */
     private String getXfLocalizationRoot(String xfPath, String currentPageRoot) {
         String xfRoot = null;
@@ -234,8 +239,8 @@ private String getXfLocalizationRoot(String xfPath, String currentPageRoot) {
     /**
      * Checks if the resource exists at the given path.
      *
-     * @param path The resource path.
-     * @return {@code true} if the resource exists, {@code false} otherwise.
+     * @param path the resource path
+     * @return {@code true} if the resource exists, {@code false} otherwise
      */
     private boolean resourceExists(String path) {
         return (StringUtils.isNotEmpty(path) && resolver.getResource(path) != null);
@@ -244,11 +249,28 @@ private boolean resourceExists(String path) {
     /**
      * Checks if the resource is defined in the template.
      *
-     * @return {@code true} if the resource is defined in the template, {@code false} otherwise.
+     * @return {@code true} if the resource is defined in the template, {@code false} otherwise
      */
     private boolean inTemplate () {
         Template template = currentPage.getTemplate();
         return template != null && StringUtils.startsWith(resource.getPath(), template.getPath());
     }
 
+    /**
+     * Checks if the resource at the given path is an Experience Fragment variation.
+     *
+     * @return {@code true} if the resource is an XF variation, {@code false} otherwise
+     */
+    private boolean isExperienceFragmentVariation(String path) {
+        if (StringUtils.isNotEmpty(path)) {
+            Resource resource = resolver.getResource(path);
+            if (resource != null) {
+                ValueMap properties = resource.getValueMap();
+                String xfVariantType = properties.get(ExperienceFragmentsConstants.PN_XF_VARIANT_TYPE, String.class);
+                return xfVariantType != null;
+            }
+        }
+        return false;
+    }
+
 }

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v1/NavigationImpl.java

@@ -242,7 +242,7 @@ private NavigationRoot(@NotNull Page navigationRoot, int configuredStructureDept
         /**
          * Gets the resource representation of the navigation root page.
          *
-         * @return The resource for the navigation root, empty if the resource could not be resolved.
+         * @return the resource for the navigation root, empty if the resource could not be resolved
          */
         @NotNull
         final Optional<Resource> getPageResource() {

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v1/PageImpl.java

@@ -234,9 +234,9 @@ public String getExportedType() {
     /**
      * Returns a map (resource name => Sling Model class) of the given resource children's Sling Models that can be adapted to {@link T}.
      *
-     * @param slingRequest The current request.
-     * @param modelClass   The Sling Model class to be adapted to.
-     * @return Returns a map (resource name => Sling Model class) of the given resource children's Sling Models that can be adapted to {@link T}.
+     * @param slingRequest the current request
+     * @param modelClass the Sling Model class to be adapted to
+     * @return a map (resource name => Sling Model class) of the given resource children's Sling Models that can be adapted to {@link T}
      */
     @NotNull
     private <T> Map<String, T> getChildModels(@NotNull SlingHttpServletRequest slingRequest,

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/models/ExperienceFragment.java

@@ -31,15 +31,15 @@ public interface ExperienceFragment extends ComponentExporter {
 
     /**
      * Name of the configuration policy property that specifies the experience fragment variation path. The property
-     * should provide a String value.
+     * should provide a {@code String} value.
      *
      * @since com.adobe.cq.wcm.core.components.models 12.9.0
      */
-    String PN_FRAGMENT_PATH = "fragmentPath";
+    String PN_FRAGMENT_VARIATION_PATH = "fragmentVariationPath";
 
     /**
      * Returns the localized path of the experience fragment variation if the experience fragment resource is defined
-     * in the template. If not, it returns the configured fragment path if it exists, null otherwise.
+     * in the template. If not, it returns the configured fragment path if it exists, {@code null} otherwise.
      *
      * If both the content page and the experience fragment have a localized root (language, live copy or blueprint),
      * - it is then assumed that the content pages and the experience fragments follow the same structure patterns -
@@ -49,7 +49,7 @@ public interface ExperienceFragment extends ComponentExporter {
      * @return Localized experience fragment variation path
      * @since com.adobe.cq.wcm.core.components.models 12.9.0
      */
-    default String getLocalizedFragmentPath() {
+    default String getLocalizedFragmentVariationPath() {
         throw new UnsupportedOperationException();
     }