adobe-consulting-services / acs-aem-commons

ACS AEM Commons

This project is a unified collection of AEM/CQ code generated by the AEM consulting practice.

Building

This project uses Maven for building. Common commands:

From the root directory, run mvn -PautoInstallPackage clean install (for AEM 6.5) or mvn -PautoInstallPackage,cloud clean install (for AEMaaCS) to build the bundles and content packages and install the container package to an AEM instance.

From the bundle directory, run mvn -PautoInstallBundle clean install to build just the bundle and install to an AEM instance. In addition there is the profile autoInstallUiAppsPackage to just install the ui.apps package to AEM.

The Maven profile cloud is used to both build both the AEMaaCS and the AEM 6.5 packages/bundles as well as to optionally install the version targeted for AEMaaCS (with the additional profile autoInstallPackage or autoInstallUiPackage). It is automatically active when no other profile is activated via command line or settings,.xml.

To build only the version for AEM 6.5 (without using any other profiles) use the command line option -P \!cloud to deactivate the default profile cloud.

Using with VLT

To use vlt with this project, first build and install the package to your local AEM instance as described above. Then cd to content/src/main/content/jcr_root and run

vlt --credentials admin:admin checkout -f ../META-INF/vault/filter.xml --force http://localhost:4502/crx

Once the working copy is created, you can use the normal vlt up and vlt ci commands.

Specifying AEM Host/Port

The AEM host and port can be specified on the command line with: mvn -Dcrx.host=otherhost -Dcrx.port=5502

Distribution

• Maven artifact available from Maven central: https://central.sonatype.com/artifact/com.adobe.acs/acs-aem-commons-all
• Github releases: https://github.com/Adobe-Consulting-Services/acs-aem-commons/releases

Rules

• Spaces, not tabs.
• Provide documentation in the parent org GH project: https://github.com/Adobe-Consulting-Services/adobe-consulting-services.github.io
• Target AEM as a Cloud Service. AEM 6.5.x only features can still be contributed, but please create a Feature Review Github Issue before working on them to ensure they will accepted. Check the compatibility table for compatibility of older versions.
• API classes and interfaces must have JavaDocs. Not necessary for implementation classes.
• Don't use author tags. This is a community project.

Want commit rights?

• Create an issue.

acs-aem-commons's Issues

Add Disqus (or some other commenting system) on feature pages

WDYT?

site should explain who Adobe Consulting Services is

How about as another striation:

Who are you?

• We are Adobe Consulting Services. We build solutions on top of Adobe products including Adobe Experience Manager (AEM, fka CQ, fka Communique).

com.adobe.acs.commons.rewriter,version is missing export statement

Currently exported as 1.2.0. Needs to be locked down by next release.

utils page should use definition lists

and since Markdown doesn't support definition lists properly, textile will have to be used instead

URI parameterize Image Transformation

The Problem

Images can only be easily transformed (resized, cropped, rotated) via the Image component which requires associating a binary image with a resource.

Often requiring an Author to define an Image resource w the proper transformations is unwieldy.

Adaptive Image Servlet begins to solve this problem however still requires the "proxy resource" AFIAK

The Proposal

A Servlet that intercepts requests for nt:file resource types with a specific signature (selector) that uses parameterized instructions which are part of the suffix to transform the resource.

<img src="/content/dam//path/to/picture.png.transform.img.png/width/20/rotate/180/image.png"/>

This could/would reduce the need for multiple renditions of DAM assets as media-based WF tends to be heavy computationally and wrt to storage.

Concerns

• DoS via requesting infinite variety of image variations
  • Could restrict via OSGi config or possible via an inventive Design scheme
• Encouraging non-authorable, direct serving of DAM assets (as this is the most likely use-case) rather than proxying through Image Component resources
  • I see a propensity for serving of DAM image renditions rather than proxying through Image Component or its ilk
• Not sure this would make sense/be usable for Images uploaded to pages nodes as nt:files/nt:resources

Robots.txt on the ACS AEM Commons github site

The robots.txt I added is (of course) in a sub-dir of the site, so its ignored.

Can add files to the GH pages domain root (everything on google points to no)?

If not, we can add meta tags to the apidocs pages themselves like so

find . -name '*.html' -exec sed -i '' 's/<\/HEAD>/<meta name=\"robots\" content=\"noindex\"><\/HEAD>/' "{}" \;

To the copy-javadoc.sh

(unless the javadoc mvn plugin has support for this; didnt see it though)

DesignHtmlLibraryManagerImpl.writeIncludes() doesn't include CSS-only libraries

The contract of writeIncludes() says that it includes CSS and JS, but in fact that is not the case - only JS libraries are output.

Limited Parsys

A Component that allows a fixed # of components to be added; something like a Parsys that only accepts N components; where N is configurable by Design.

AEM ACS Commons - Component Design Paradigm Idea

Problem

Re-usable AEM Component rarely contain the markup or sum of features required for various customer use cases. This results in a copy-down overlay approach of the original JSP. This causes grief when upgrading source materials as enhancements are not recognized without re-integration.

This problem is very common when using the Foundation AEM Components.

Idea

(Re-usable) ACS AEM Components will:

• Contain minimal, semantic markup. An example is the audio component; it only outputs <audio> tag)
• Re-usable components will contain all the "working" jsps in an "partials" folder (naming TBD). The Working JSPs will be responsible for rendering a specific facet of the Component; in this case the <audio ...>...</audio> tag

/apps/acs-commons/components/content/audio/partials/audio.jsp

• The default script /apps/acs-commons/components/content/audio/audio.jsp will simply include the partials:

<cq:include script="partials/audio.jsp"/>

For a developer to augment the component markup, they simply have to superResourceType (i guess it would be sub-ResourceType) the ACS AEM Commons audio component and selectively include whatever partials they want intermixed with whatever markup or other facets they need (as long as the superType is set)

/apps/myapp/components/content/audio/audio.jsp

<div class="myclass-for-audio">
  <cq:include script="partials/audio.jsp"/>
  <p><%= properties.get('instructions', "Press play") %></p>
</div>

Concerns

• What level of granularity are the partials broken out; by logical facet of Component?
  • Ex. If Audio had the audio player AND instructions, should there only be one partials/audio.jsp with both facets, or one for each facet; partials/audio.jsp (audio tag) and partials/instructions.jsp (print instruction text).
  • Which scripts are responsible for which drop-targets/placeholders?
  • Will this cause (serious) code duplication across partials?
• Generally too confusing and a departure from normal process.

Web UI for dispatcher flush rules

Creating a Web UI for defining Dispatcher Flush rules would be great. This would allow for a base set of rules to be strictly defined as part of the application (OSGi Config) and another set to be defined in an ad hoc manner to support flexible content build out.

This UI might be able to be built out using ACS AEM Commons Generic Lists.

Dispatcher Flusher UI

CQ Author Tools UI for forcing dispatcher flush of any paths in Dispatcher (permission-able by admin)

Remove the procedural bottleneck of requesting Ops team to flush (delete) dispatcher caches post deployments or content activations across environment. This tends to be an impediment to new development as there is often a gap between dev and ops (and ops owns dispatcher config/stat files/etc.)

Versionable ClientLibs/Design Assets

The Problem

Everyone wants to be able to increment clientlibs/designs based on released to allow long TTLs for these typically long-lived assets.

Currently the only way I know how to do this is to have maven builds adjust the name of the clientlibs folder to contains a build no. (assuming all FW assets reside under a CL, which IMO they should; Designs are an odd abstraction -- see DesignHtmlLibraryManager.

Error pages should be always included using GET requests

The dispatching of error pages should always be done using a GET request so as to ensure that they get properly delivered.

For example, a request like

curl -u admin:admin http://localhost:4502/content/page/which/doesnt/exist.html -F./jcr:content/foo=bar

should not actually set jcr:content/foo to bar on the error page.

component-error-handler; resourceType blacklist

Would be nice to add a blacklist of resourceTypes/resourceType patterns that would be ignored which would generate "normal" behavior when an exception is thrown in them.

move TemplateUtils to util package and rename to be consistent with other util classes

Quick Reference

http://activecq.com/system/assets/46/original/quick-reference.html

Thoughts on moving my quick reference as a gh-pages page?

I'm a little hesitant because:

• It's a bit opinionated
• I update it on an ad hoc basis without review
• I closely curate what's in it; adding/keeping only things I frequently go back for. Things i don't use eventually get removed.

Im happy to move it over, or not; I maintain it for me, but am happy to share.

That being said, i'd welcome feedback/corrections/suggestions.

CQ should not be a predefinedVar for jslint

CQ is included in the list of predefined variables for jslint verification. This is potentially problematic as it can allow edit-time JS to seep into user-side JS. Since it only impacts one file, I'm going to remove it from this list.

Highly Scalable Session-like Serverside Storage

The Problem

CRX 2 does not scale wrt to writes/content-distribution in a way that makes it a reasonable solution for storing user-based highly volatile data. Personalized data tends to get pushed and persisted in the ClientContext via cookies.

Sometimes maintaining the state in Cookies does not make sense. (Business would like more control over stored data, does not want to expose the data directly to the user, privacy concerns, performance concerns (sending large cookies across all requests), etc.)

The Proposal

Use redis to create a highly scalable "session-like" store for user data. Users would posses a cookie key (ala JSESSIONID) which would be associated with a data set in redis. redis can be access from all Publish servers so the data is not tied to a single publish server thus highly scalable. redis also has native data expiration to automatically expire content. redis is hugely scalable wrt to reads and writes as it is an in-memory datastore.

Concerns

• Aggressive undertaking.
• Dependency on Redis and Jedis (java api for redis)
  • This may exclude it from ACS AEM Commons.
• Security concerns/considerations
• "Promotion" of a non-Adobe supported product
• May be rendered moot by Oak

Dynamic RTE Configuration doesn't support externalStyleSheets

There's no way to specify externalStyleSheets for an RTE produced by Dynamic RTE configuration. There should be.

Analysis build shouldn't fail due to Checkstyle

Unfortunately, we have 1100+ checkstyle warnings at this point. Until that number is reduced, we can't really be failing the analysis build for them. Once that number has been reduced to a managable number, we can reenable it.

Dispatcher Flush UI allowedPaths too loose (v1.2.0)

Not necessarily a bug, but marking it as such.

Disptacher Flush UI Template shows up in, if not "buggy", then atleast odd places.

Example:

Shows up as viable Template for Cloud Services.

Im sure itll show up in a variety of other places as well.

Unless other have suggestions i move to restricting to to:

/etc/acs-commons/dispatcher-flush

/etc/dispatcher-flush

/etc/replication

IMO those are the most logical places (options) for these pages to live.

Project is referring to an unreleased version of ui.commons

From https://travis-ci.org/Adobe-Consulting-Services/acs-aem-commons/builds/12147278:

Could not find artifact com.adobe.granite:com.adobe.granite.ui.commons:jar:5.5.8

remove all the README.md files from the src/main/java tree

Write an isAuthor method?

Does it help to write a utils method to get check the sling runmode and return an isAuthor boolean? I can do it, but, need to know from you guys if I should create a new SlingUtils class or add this to an existing class.

Let me know what you thinks.

Thanjs

DTM Cloud Services configuration

Cloud Services configuration for Dynamic Tag Management

Add a JSP Custom Tag for the Designer HTML Library Manager

Something like:
<dhlm:includeClientLibraries region="head" js="true" css="true"/>

Cloud Service Configuration for ShareThis.com

This is a pretty popular service.

Handling 3rd party dependencies

One of our design principals is to not have required 3rd party dependencies. Which implies that we can have optional 3rd party dependencies.

The policy I suggest is:

• 3rd party dependencies are marked as "optional" in the pom.xml file
• imported packages have resolution=optional

For each 3rd party dependency, I'd also like to see a separate project which makes that dependency available in a content package. For libraries which are already OSGi-ified, this would just be a content package project embedding the bundle. For libraries which are not OSGi-ified, we will need a content package project and an embedded bundle project.

An example (for the Twitter4J API) can be found here: https://github.com/justinedelson/com.adobe.acs.bundles.twitter4j

The idea is that this content package would be released and deployed and then could be incorporated into a project just like ACS AEM Commons. We'd have to add instructions for how to do this to the site as well as identify which features depend on which libraries.

WDYT?

DispatcherFlushRulesImpl shouldn't create new filters all the time

There's a slight inefficiency in DispatcherFlushRulesImpl where it creates new filter objects inside a loop. Since the filter object is stateless, this isn't necessary.

figure out how to add a little "New" indicator to the Features on the site

@davidjgonzalez can I ask you to take a crack at this?

ErrorPageHandlerImpl does unnecessary (maybe) queries

There are two queries running inside ErrorPageHandlerImpl and I believe both can be eliminated.

The first query is to find all the cases where the errorPages property is defined. This can be done without a query by using an InheritanceValueMap to walk up the resource tree from the parent resource.

The second query is to find a page with the appropriate name within the errors path. This can be done by direct node access.

clientlib selector on design page should be drop-down

It would be a better user experience if the edit dialog on the design page used drop down lists to select the client library category

Set word-wrap to break on gh-pages body's

Page content pushes width past view port making for awkward scroll experience on small devices, esp on feature pages

PageHelper

A clean wrapper for exposing common "Page" data, such as contents of <head>'s meta-tags, etc.

In the ACS-AEM-Commons utility pages I find myself using "ugly" code to display simple data points like Page Title

final String title = TextUtil.getFirstNonEmpty(
                    currentPage.getPageTitle(),
                    currentPage.getTitle(),
                    currentPage.getName());

No to mention escaping and localizing values.

IME we (cq implementors) tend to have very similar lookup patterns/uses for all the various Page attrs (title, keywords, description, nav titles, etc.). My hesitation is this list of common usages may not warrant a full "wrapper" implementation. I think we'd want to define the interface before adding to the project.

Documentation - add an "Updated" flag, like the "New" flag

Similar to the New flag, we should have a way of flagging pages as being updated. I see this as a manual process, i.e. we'd flag the Forms page as updated to draw attention to the fact that it has changed. Or when new widgets are added to the custom widgets page.

switch from Cobertura to JaCoCo

JaCoCo is a more current coverage tool than cobertura.

Standardize on a node representation for documentation

I've noticed we use (at least) two different styles for representing JCR nodes in documentation:

• JSON
• XML/Vault Serialization

Although the latter is more accurate, it seems noisier to me and I generally prefer JSON.

Component-specific forced cell stack/search paths

The Problem

Design Dialogs are a powerful tool for storing cross-site component configurations. The way the cell lookup works prevents the very common use case of allowing certain components from sharing a design-global configuration vs a template-specific configuration. Ex. Logo on Geometrixx; requires editing on each type of page (Homepage and a Content page). page impl cellNames can be setup, but this prevents other components from being configured on a per-template basis which can be desirable.

The Proposal

Create a Sling Filter that looks at the to-be-included Component and set the cellName based on a property on the cq:Component node. Im not sure if IncludeOptions will allow a full reset of the cell stack -- may require another approach.

Named Transform Image Servlet

Kinda of like the AEM Adaptive Image Servlet, except on bovine growth hormones.

https://github.com/davidjgonzalez/acs-aem-commons/tree/feature/named-transform-image-servlet

Inspired by previous discussions in Issue #24, with @ykisen and @justinedelson around non-destructive renditioning of Images. Note, this approach does NOT support authorability of renditions.

Allows developers to create transform rule sets (resize/crop/rotate - in whichever order) and apply the named transforms against (almost?) any image in AEM.
Works against:

• cq:Pages (jcr:content/image)
• Image component resources
• DAM Assets (/content/dam/foo.png)
• DAM Asset Renditions (/content/dam/foo.png/jcr:content/renditions/whatever.jpg)
• Binary Images (/etc/designs/mysite/images/foo.png)

Requesting URIs require a "transform" extension, the first suffix segment is the named transform and the last suffix segment is "image." or "img." (to promote cacheability).

Current all transforms are maintained in a single OSGi Config; debating trying to break it out to allow "sets" of named transforms via configFactory configs.

Reverse Replication of User Resources

The Problem

As AEM moves from WCM to WebApp, the need to move around User profile information becomes more common. Current "OOTB" implementation for this requires various Launchers and dev-based "touch" of resource for replication.

The Proposal

• Creating disabled Launchers for RR'ing profile resources - OR - creating an event listener (that could be configured for any path i supposed) that handles queuing of resources for Reverse Replication.
• Creating a ReplicationUtil (or Helper) that can be used to "touch" a resource to trigger it for RR (setting the lastMod, lastModBy and cq:distribute properties).

Concerns

RR has many nuances and pitfalls. We would need to be very careful we dont create a faulty/broken abstraction.

Forms Filter is auto-enabled even without config

Update Sling Filter to require a configuration policy so it only include in the filter stack if explicitly desired.

Add a Rewriter Pipeline component for static domains

This comes up with regularity that some elements need to be rewritten to make them absolute URLs to some secondary domain which is "cookie-less".

DTM and TypeKit Cloud Service Dialogs Doesn't Open in AEM/CQ 5.6.0

OOTB AEM configpage [1] loads the dialogs using in-page JS written out by Java code.

String dialogPath = (!resource.getResourceType().startsWith("/libs") ? "/libs/" : "") + resource.getResourceType() + "/dialog";  

In our case, resource.getResourceType is acs-commons/components/utilities/dtmpage so the dialogPath turns into /libs/acs-commons/components/utilities/dtmpage which is incorrect.

[1] /libs/cq/cloudserviceconfigs/components/configpage/body.jsp

Page Images/Renditions

The Problem

As components become more dynamic the need for multi-rendition of pages (our favorite sort of authorable resource!) becomes more necessary. Sling's resource-centric worldview positions us exceedingly well (ex. page based selectors) however defining various images (or more typically, image transformations) based on page renditions is still problematic.

Ex. I maybe want a 4x3 (200px x 150x) cropped image for search results, but a 16 x 9 (160px x 90px) image for a featured box in the sidebar, etc. We have no good, concise way for Authors to define an image to represent a page and provide transformations w previews for the various renditions.

The Proposal

Not 100% sure .. early POC is creating a new component with multiple dialog tabs, each tab featuring a html5smartimage widget with preset crop ratios. Crop rations are store on discrete nodes but image binary is pulled for the "usual" image node under a page's jcr:content. A special "image-preview" selector is added to the page to display all images at their various transformations.

Concerns

I am not convinced this is the best solution, however my gut reaction is allowing renditions of Pages to be managed centrally (at said Page) is key.

Dispatcher Flush Rules Handler

Replication Handler that, on content replication, issues Dispatcher Flush requests for other content trees, independent of stat level. Ex.

Replication of resources matching: /content/dam/mysite/.* ~> Flush /content/mysite

or

Replication of resources matching: /etc/packages/.* ~> Flush / (everything! who knows what a new package could affect!)

Similar to the new 4.1.4+ Dispatcher Handler functionality, but does not require bash scripting, and can be achieved via simple OSGi Configuration mappings (future versions may include an UI-based component). The Ops maintained dispatcher handlers are brittle in that they live outside the natural realm of the application, maintained by a team that should not require intimate knowledge of the inter-content dependencies.

(Needs a better name)

service.vendor and service.description services properties should be set automatically

Would be best not to reproduce these all over the place.

Ensure that all packages have correct export versions

Error pages which are first-level children of the page of the page definiting errorPages don't properly detect the error page

watermark rendition process should log something when the watermark path isn't valid

Currently, you get no feedback

Bootstrap files-set for new Projects

Create a maven archetype that extends the Adobe multi-module maven archetype but includes core organization and place holders.

Intermediary solution: a zip of the augmenting files to unzipped over a new multi-mod project.

Key elements:

• skeleton component (copy down to create new components; promotes a common impl structure)
• common osgi configs xmls
• component organization
  • content/pages
  • global.jsp
  • base components
  • other examples XML of various common nodes. Templates, widgets, etc.