Four Tips for AEM Beginners: Overcoming Common Issues

This blog primarily targets Adobe Experience Manager (AEM) beginners in an attempt to solve/ familiarize them with typical problems encountered when they start using AEM, and how to resolve those problems. Don’t feel like you are alone in this… I have run into many of the problems myself and gotten stuck. Not knowing how to handle them, I wasted a fair amount of time in the initial stages. Therefore, I articulated solutions for a few significant hurdles an AEM beginner would face in his/her initial learning process to make their life easier. Below are such problems.

Need to install huge/multiple packages? 

Is Package Manager timing out?
This is often experienced in development systems (PC) where it does not have sufficient power to complete the package installation task quickly, which results in crashing your instance. AEM provides a file-based package upload. Place your packages under /crx-quickstart/install (create an install folder if it does not exist) and they will be automatically installed and appear in Package Manager as well.

AEM instance taking too long to start?
Due to the rapid growth of the repository, your instance will run slow or take a lot of time to start up (10 minutes at times). To avoid this and keep the instance running smoothly, we have to run offline revision cleanup or compaction. Adobe provides a tool called Oak-run, which can be downloaded from the link below:

https://repo1.maven.org/maven2/org/apache/jackrabbit/oak-run/

Use the Oak-run version that matches Oak core of your AEM Instance (For Oak version > 1.1.6). You can find the Oak version in the CRX page home tab.



In the case where you cannot open the CRX itself, the other way to find your oak instance is to navigate to your crx-quickstart folder and search for oak and you can find the bundle name, which reflects your Oak version.



Shutdown your AEM instance and run compaction with the command below.

java -jar /oak-run.x.x.x.jar compact install-folder/crx-quickstart/repository/segmentstore

Do you know about dialog editor and dialog conversion tools?
No need to write each property for the dialog by searching through the CQ WCM documentation. Just double click on the dialog node, which takes you to the dialog editor. You can also convert them to touch UI dialogs using a dialog conversion tool (download the cq-dialog-conversion-content package from packageshare). http://localhost:4502/libs/cq/dialogconversion/content/console.html

Is your repository corrupted? Take a backup beforehand.
Maybe you accidentally deleted an important file or bundle while playing with the instance. Maybe your repository indexes got corrupted. There are different options to back up your repository. Simply copy and paste the folder containing the quickstart jar file. This is a simple and safe option when your instance is not running. Alternatively, you have an option to do an online backup:

Go to http://localhost:4502/libs/granite/backup/content/admin.html and give the target path, choose appropriate delay amount not to affect other processes in the instance.



If you are new to AEM, are there other issues you are running into that you’d like to see a post on? Drop us a line below. Or, if you are well-versed in AEM, do you have any tips to share?

Simple Markdown Documentation For Your AEM Components

Documentation Documentation Documentation. I believe documentation is one of the most important aspects of delivering a product, or in this case, an AEM component.

If you aren’t already, you should use the Granite UI widget fieldDescription property to add helpful tooltips to your dialog fields. You can also use the Granite Alert Widget for quick in-line authoring tips.

Here is an example:

Markdown Servlet
In some cases, you might need to add more documentation about the component, whether it’s technical or otherwise. For that, we will piggyback off Dan’s post and create a simple servlet using flexmark. That servlet will accept the file path from the request suffix and render that file as HTML for us to view.

Update: I found out that Andrei Shilov had a very similar idea and wrote about it here.
The Steps:
First, add the following two dependencies to your maven project:
<dependency>
<groupId>org.jsoup</groupId>
<artifactId>jsoup</artifactId>
<version>1.11.3</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.vladsch.flexmark</groupId>
<artifactId>flexmark-osgi</artifactId>
<version>0.34.56</version>
<scope>provided</scope>
</dependency>

Then embed both of them as bundles in your content-package-maven-plugin like so:
<plugin>
<groupId>com.day.jcr.vault</groupId>
<artifactId>content-package-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
....
<embeddeds>
...
<embedded>
<groupId>org.jsoup</groupId>
<artifactId>jsoup</artifactId>
<target>/apps/aem-markdown/install</target> <!-- Change this to your project install path -->
</embedded>
<embedded>
<groupId>com.vladsch.flexmark</groupId>
<artifactId>flexmark-osgi</artifactId>
<target>/apps/aem-markdown/install</target> <!-- Change this to your project install path -->
</embedded>
</embeddeds>
...
</configuration>
</plugin>

You can also embed them using the maven-bundle-plugin <Embed-Dependency> as an alternative method.

Then add the following servlet code:
import com.vladsch.flexmark.html.HtmlRenderer;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.util.options.MutableDataSet;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.Charset;
import java.util.Optional;
import javax.jcr.Node;
import javax.jcr.RepositoryException;
import javax.servlet.Servlet;
import javax.servlet.ServletException;
import org.apache.commons.io.IOUtils;
import org.apache.jackrabbit.JcrConstants;
import org.apache.jackrabbit.commons.JcrUtils;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.request.RequestPathInfo;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.servlets.SlingSafeMethodsServlet;
import org.osgi.service.component.annotations.Component;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Component(
service = Servlet.class,
immediate = true,
property = {
"service.description=Markdown Servlet",
"service.vendor=Ahmed Musallam",
"sling.servlet.paths=/bin/markdown",
"sling.servlet.extensions=html",
"sling.servlet.methods=GET"
})

public class MarkdownServlet extends SlingSafeMethodsServlet {
private static final Logger log = LoggerFactory.getLogger(MarkdownServlet.class);
private static final MutableDataSet options = new MutableDataSet();

/*
* both Parser and Renderer are thread-safe according to:
* https://github.com/vsch/flexmark-java/blob/master/flexmark-util/src/main/java/com/vladsch/flexmark/util/IParse.java
* https://github.com/vsch/flexmark-java/issues/111
*/

private static final Parser parser = Parser.builder(options).build();
private static final HtmlRenderer renderer = HtmlRenderer.builder(options).build();

@Override
protected void doGet(SlingHttpServletRequest slingRequest, SlingHttpServletResponse slingResponse)
throws ServletException, IOException {

// The markdown file path is the suffix of the request
Resource mdFileResource =
Optional.ofNullable(slingRequest)
.map(SlingHttpServletRequest::getRequestPathInfo)
.map(RequestPathInfo::getSuffixResource)
.filter(resource -> JcrConstants.NT_FILE.equals(resource.getResourceType()))
.orElse(null);

if (mdFileResource == null) { // does not exist
String path = Optional.ofNullable(slingRequest)
.map(SlingHttpServletRequest::getRequestPathInfo)
.map(RequestPathInfo::getSuffix)
.orElse("");
slingResponse.sendError(404, "Markdown File does not exits at: "+ path);
} else { // does exist
try {
slingResponse.setContentType("text/html; charset=utf-8");
InputStream in = JcrUtils.readFile(mdFileResource.adaptTo(Node.class));
String markdownString = IOUtils.toString(in, Charset.defaultCharset());
String renderedHtml = renderer.render(parser.parse(markdownString));
slingResponse.getWriter().write(renderedHtml);
} catch (RepositoryException e) {
throw new ServletException("I've wrapped the real error in a Servlet Exception. Keep scrolling down...", e);
}
}
}
}

This servlet binds to the path /bin/markdown.html and uses the suffix as the path to the markdown file. For example, if my markdown file for the blockquote component was at path:/apps/my-com/components/general/blockquote/README.mdthen I could get the HTML version of it by requesting:/bin/markdown.html/apps/my-com/components/general/blockquote/README.md

Example Component with hepPath
You can use the servlet above with the component dialog helpPath property.

Here is an example:


The sample README.md file will look like this:

# Blockquote
A component that displays blockquote.
## Features
- Feature One
- Feature Two

## Edit Dialog Properties
1. `./quote` (richtext) The quote text
2. `./qouteTreatment` (select) The treatment class.

Options: `quote`, `quote blue` and `quote single-quote`
3. `./citation` (textfield) the citation text for the quote.
## Special Authoring Documentation
There are no special authoring documentation for this component
After the helpPath update, the dialog help icon will now point to the README.md path:


And when you click on it, the following page opens:


This is more than enough for general documentation. And since Markdown is parsed to semantic HTML, it is easy and clear to read.

Things I want to explore further:
While this is a good and simple way to render markdown with minimal effort, we can clean it up further. Let’s turn it into a project, and put it on Github to integrate with your existing project. To do this, add the following features:

1. Add a Granite Widget to display documentation markdown in a new tab on component dialogs. You can even pull the default README.mdautomatically.
2. Create a special page to display the markdown and add a CSS library for aesthetics

Learn Adobe Experience Manager

Adobe Experience Manager or AEM is Adobe’s market-leading Digital Experience Management platform and as a special this April, you can learn all about AEM with a free month of Pluralsight’s training courses!
Getting a License

Of course, to run AEM you need the binary and a license. If your organization already has AEM, reach out to whomever manages AEM, if not, you can request a copy from Adobe.

Existing Partners:
https://adobe.allegiancetech.com/cgi-bin/qwebcorporate.dll?idx=82357Q

Potential Customers:
https://www.adobe.com/products/request-consultation/marketing-cloud.html?s_osc=70114000002JNwKAAW&s_iid=70114000002JHs3AAG
What’s the Best Track for Me?
AEM projects involve a number of different roles and skillsets. Click on the
roles below to learn more about the role and what courses will help you
reach the next level.

AEM Author
Authors create the content in AEM, leveraging templates, components and
assets to create pages, emails, mobile apps and other experiences.
Learn how to use AEM’s authoring interface to it’s maximum extent and what
features of AEM you can leverage to make your content more flexible and
maintainable.

AEM Business Practitioner
Business Practitioners are experts of the use of the Adobe Experience Manager platform and help the business translate requirements into technical stories.
Learn how to use the AEM platform and how to solve business problems with AEM technology.

AEM Back-End Developer
Back-End Developers work inside the CMS to create services and components to render content to different channels including websites, mobile apps, emails, etc.

Learn how to use OSGi, the JCR and Apache Sling to structure and create powerful content-driven applications in AEM.

AEM Front-End Developer
Front-End Developers create components, HTML, CSS and JavaScript to create experiences for different channels including websites, mobile apps, emails, etc.

Learn how to use HTL and the AEM component framework to create dynamic but flexible content-driven experiences.

AEM Technical Overview

Adobe Solutions Consultant Diana Breen demonstrates some of the key functionality in Adobe Experience Manager.
AEM Authoring Fundamentals
Discover how you can use Adobe Experience Manager to create and manage the content of rich responsive web experiences.
AEM Authoring Building on the Fundamentals

Building upon AEM Authoring Fundamentals course, this course will expand your skills and knowledge for authoring in AEM into more advanced AEM topics.
AEM Developer Skill Assessment

Are you a novice or expert? Find out about 20 questions.
AEM Developer Fundamentals
An introductory developers course about how to get started with AEM 6.2. You’ll learn the tools that developers commonly use, the terminology, the history, and how to install and use AEM in practice.
AEM Building Full Stack Components


Learn to leverage AEM’s rendering lifecycle to architect solutions based
on designs. You’ll work with components, editable templates, and page
properties to build content structures that are returned as JSON from an
API endpoint.
Fundamentals of building from Projects in AEM

This course will teach you how to build and
debug Adobe Experience Manager (AEM) packages and how you can use them to import and export content to and from AEM’s Java Content Repository (JCR.)

Software required: Adobe Experience Manager, Maven.
Extending AEM Foundations
Adobe Experience Manager or AEM is Adobe’s market-leading web content management and digital marketing platform. This course
is ideal for backend developers and focuses on developing services,
servlets, and jobs in AEM.
Extending Adobe Experience Manager Advanced

AEM is built on OSGi, Sling, and a Java Content
Repository. This course will teach you to harness these technologies to
extend AEM.
Develop Websites and Components in AEM

This course will teach you the basics for developing websites using AEM,
including structure component development, understanding Apache Sling and
the JCR, and using HTL.
Develop Websites and Components in AEM Advanced

This course teaches you the advanced methods for developing websites,
including using AEM’s responsive grid, the advanced content component
development, debugging, and testing.

Where do I get help?
Learning AEM is no simple thing, the platform, while easy to use is large and complex. Some great resources for people looking to get started with AEM include:
Adobe Experience League
Adobe Experience Manager Facebook Group
Perficient Adobe Blog
Adobe’s Getting Started

AEM – Eclipse Plugin Setup Tutorial

Adobe have released eclipse plugin for developing AEM projects which makes easy to create and develop Adobe CQ / AEM projects. This plugin can be used to develop OSGi bundles, Components , Templates and Content from the scratch.

This plugin will seamlessly integrate with the AEM instance and all the changes can be pushed/deployed directly on to the AEM server.

Installing AEM Plugin in Eclipse (PS: Using Eclipse Luno)

Step 1 : Goto Help > Install New Software…

Step 2 : Click Add and enter http://eclipse.adobe.com/aem/dev-tools/ in Location and click ‘OK’



Step 3 : Select both ‘AEM’ and ‘Sling’ and Click ‘Next’


Step 4 : Click Finish and restart Eclipse.

Now, we are ready to create a AEM project within eclipse. Adobe has also released an extension for Brackets to develop components that supports ‘Sightly’, a new templating system. I will be posting in detail the steps to create a AEM project using eclipse and Bracket plugin soon.

AEM / Adobe CQ5 Tutorial for Beginners

Welcome to AEM CQ5 Tutorial or Adobe Experience Manager Tutorial. The purpose of creating this post is that most of AEM blogs and tutorials available online are not properly indexed. For example, if a beginner wants to learn AEM he doesn’t have any proper guide, where to start learning aem from and how to learn AEM. So, I have decided to create this index post that will consist of all topics in a sequence that a beginner should follow to learn aem.

Introduction: -

·       History of AEM.

·       AEM Overview.

·       AEM Building Blocks.

·       AEM Installation and Setup.

·       Different AEM Console.

Good To Know:-

·       AEM Shortcut and Quick Reference Guide.

·       Adobe AEM Best Practices for creating a Website.

·       Adobe AEM Best Practice for creating project Structure.

·       Best Practices and Basics as Suggested by Adobe. (Ocean of AEM Knowledge in an organized form)

Basic AEM Developer

·       Create a Template.

·       Create a component in classic UI.

·       Create a component in touch UI.

·       Switch between Classic UI and Touch UI.

·       Convert Classic UI dialog to Touch UI Dialog.

·       Create a Dialog.

·       Create a Design Dialog.

·       Create a Page in AEM.

·       AEM core components overview

·       Create Proxy Component in AEM

·       Sling Resource Resolution in AEM.

·       Overlay and Sling Resource Merger in AEM.

·       Create Metadata Schema form for Custom MIME types

·       Explore Client Libraries in AEM.

·       AEM Link Checker: Comprehensive Guide

·       Asset Metadata AEM: Comprehensive Guide

·       AEM Collections: Comprehensive Guide

·       AEM Query Builder.

·       Create a Workflow in AEM.

·       Implement Internationalization in AEM.

·       Configure Maven with Eclipse.

·       Configure AEM plugin for Eclipse.

·       Create AEM Multi-Module Project.

·       OSGI Basics and Implementation in AEM

AEM with HTL (HTML Template Language) formerly known as Sightly

·       HTL Overview and Advantages over JSP.

·       Create a component in HTL.

·       Use Sling Model with HTL.

Advanced AEM Developer

·       Create Custom Process Step for Workflow in AEM.

·       AEM OAK Indexing.

·       Asset Metadata AEM: Comprehensive Guide

·       Create Metadata Schema form for Custom MIME types

·       Implement Personalization using ContextHub in AEM

·       Examples of Custom WorkFlow.

·       Configure Multi-Site Manager (MSM) in AEM.

·       Create Run Modes in AEM.

·       Create Custom OSGI configuration in AEM.

·       Create System User in AEM.

·       Get Resource Resolver from Resource Resolver Factory.

·       Configure File Vault in AEM.

·       Upload Media files to the AEM server from Desktop.

·       Connected Assets: Comprehensive Guide

AEM System Administrator

·       Configure Dispatcher in AEM.

·       Setup Tar MK Cold Standby in AEM.

·       Run Online and Offline TAR Compaction.

·       AEM OAK Indexing: Comprehensive Guide

·       Migrate User and Groups in AEM.

·       Configure Node Store and Data Store in AEM.

·       Restrict content to specific publishers in AEM.

·       Adobe AEM Curl Commands.

Troubleshooting AEM

·       Display Components in Touch UI.

·       Analyse Heap Dump in AEM.

·       Explore Request Log.

·       AEM 6.1 HotFixes.

AEM Integrations

·       Integrate AEM with Angular 2 JS.

·       Create a component using Angular 2 JS.

·       Integrate AEM with Bootstrap Framework

AEM Miscellaneous Tasks

·       Guide for Adobe AEM Certification.

·       Software to improve developer productivity.

·       Top 5 Features in AEM 6.2.

AEM Programs

·       Create custom login component using HTL(Sightly) and Bootstrap

·       Implement 301 and 302 Redirect in AEM.

·       Create a Nested Multi-field AEM Component.

·       Create Touch UI Nested MultiField Dialog in AEM

·       Configure RTE Plugin in Touch UI.

·       Create Custom AEM Mobile Emulator.

·       Implement Social Plugin in AEM.

·       Create a Touch UI component using Coral UI.

·       Enable HTTPS in AEM.

·       ACS AEM Samples (code examples used to educate AEM developers on how to do certain things)

·       ACS AEM Common ( Nice collection of commonly used components that can be reused by developers)

·       ACS AEM Tools (wide collection of tools that can be used to ease the life of an aem developer)

AEM Interview Questions

·       Basic AEM Interview Questions.

·       Tricky AEM Interview Questions.

AEM Forms

·       Implement AutoComplete Adaptive Form

The list is not completed Yet, I will add more topics soon. Feel free to suggest topics that will be added in these sections to improve the AEM CQ5 Tutorial list further for AEM Beginners and Advanced developers.