Monday, January 15, 2018

Setup local AEM instance (with AEM Forms Package)

This article describes the steps for setting up a new AEM instance for working locally.

Please note: This is not for team development and certainly not for production use, it's just some quick pointers to get a novice going.

Note, these instructions include AEM Forms as well

My Setup:

Since detailed instructions are often dependent on having the right versions of things, here's a summary of my environment:
  • Ubuntu Linux 16.10
  • Oracle JDK 1.8.0_151
  • AEM 6.3

Step 1: Get the installation files.


You will need the following installation files to set yourself up with an AEM forms environment:
  1. AEM quickstart jar file (for example: AEM_6.3_Quickstart.jar)
  2. License file (for example: license.properties)
Note 1: If you don't have the quickstart jar, you can obtain it from Adobe

Note 2: If you don't have a license file, then you can obtain a license key from Adobe. When starting up AEM for the first time, you will need to enter the license key and then it will automatically create the license file.

Step 2: Create a folder for your installation

AEM is an Apache Sling application, so you can simply run it from the JAR file. when running the JAR, AEM unpacks itself, so it is useful to do this in a logical place.

On my machine I  like to do this in the home folder at ~/Software/AEM63Stack, but you may have a different preference.

Within the primary folder I like to create two subfolders, one for an author and one for a publish instance.

Paste both files in the author subfolder and the publish subfolder. Once pasted rename the two jars as follows:
  • Author jar: aem-author-6.3.0-p4502.jar
  • Publish jar: aem-publish-6.3.0-p4503.jar

This tells the AEM engine what instance type each will be used for as well as the port to use.

Here's what my folder looks like at this stage:

.
├── author
│   └── aem-author-6.3.0-p4502.jar
└── publish
    └── aem-publish-6.3.0-p4503.jar

Step 3: Create a startup shell script (Optional)

I like to have a shell script that I run when starting up AEM. It just makes it easier, and it creates an alternative to double-clicking the quickstart jar. Later one this can be replaced with more robust scripts that start and stop AEM.

In the author sub-folder, create a file called "aemstart.sh"

Add this content to the file:
#!/bin/bash 
echo "Starting up AEM 6.2"
java -jar aem-author-6.3.0-p4502.jar -nointeractive -gui

Give the file execute permissions:
chmod +x aemstart.sh
 .
├── author
│   ├── aem-author-6.3.0-p4502.jar
│   ├── aemstart.sh
│   ├── crx-quickstart
│   └── licenAEM-CFP-6.3.1.1se.properties
└── publish
    ├── aem-publish-6.3.0-p4503.jar
    └── aemstart.sh

Now copy the file to your publish sub-folder as well.

Here's what my folder looks like at this stage:

.
├── author
│   ├── aem-author-6.3.0-p4502.jar
│   └── aemstart.sh
└── publish
    ├── aem-publish-6.3.0-p4503.jar
    └── aemstart.sh

Step 4: Start up AEM Author

Now you're ready to start up AEM. Open a terminal in the location where the aemstart.sh file was created (for your author instance) and simply run:
./aemstart.sh

The first time you run this, it'll be a bit slow because it is actually unpacking the JAR and setting up your AEM server. On subsequent loads it is a bit faster.

Upon executing the script, an AEM dialog will appear with a progress bar showing how the startup is progressing.

If you look in the "author" folder you will notice that a new sub-folder has been created, named "crx-quickstart" this is where the actual AEM server sits.

Once AEM is started up, a browser window will automatically open up pointing to the server at localhost:
  • If a license file was supplied the browser will open on the AEM login page.
  • If a no licence file was provided the browser will open on a page allowing your to capture your license key. After the key is supplied, you will also be taken to the login page

You can login with admin, admin

Here's what my folder looks like after starting up the author for the first time:

.
├── author
│   ├── aem-author-6.3.0-p4502.jar
│   ├── aemstart.sh
│   ├── crx-quickstart
│   └── license.properties
└── publish
    ├── aem-publish-6.3.0-p4503.jar
    └── aemstart.sh

Step 5: View your logs

AEM provides a number of useful logs that you should tail while developing. All the logs are stored at crx-quickstart/logs

The most important logsto look at initially are:
  • request.log: This records all REST requests sent to the Sling server
  • error.log: This is the log where all AEM messages are written 

 

Step 6: Setup AEM Forms Package

Once you're logged into AEM, go to the package share:
  • http://localhost:4502/crx/packageshare
  • Or navigate: Tools > Deployment > Package Share
You'll have to log into package share with your Adobe ID.

Once logged into Package Share, search for the Forms Add on package for your Operating system. In my case it is called: AEM-FORMS-6.3.1.2-LX

Once the package is finished downloading you can click on the "Downloaded" button. This will navigate you to the package manager (http://localhost:4502/crx/packmgr) where you can simply install the package that was just downloaded.

All that's needed now is to click on Install, to install the package

Note: If the package has unfulfilled dependencies, it will not install. You will need to first download and install the relevant dependencies. In my case I needed to download and install the following packages (in order):
  • AEM-6.3-SERVICE-PACK-1
  • AEM-CFP-6.3.1.1
  • AEM-FORMS-6.3.1.2-LX
You'll need to restart your AEM instance when all of this is done.

FAQ:

What about the publish instance?

I've excluded the publish instance for this article, but will explore it in a future article.

 

References:

  • https://helpx.adobe.com/support/experience-manager/6-3.html

Saturday, June 17, 2017

Sortie 1 :: Exploring the AEM Rich Text Editor


"The Rich Text Editor (RTE) provides authors with a wide range of functionality for editing their textual content; providing them with icons, selection boxes and menus for a WYSIWYG experience. These can be individually activated, deactivated, or configured for your installation-specific text component(s)."

Since the RTE  has so many options and potential variations, it makes sens to explore it in more depth.

An AEM Master should be able to user, configure and customise the RTE, but the AEM Master should also understand the limitation of the RTE.

This Sortie is designed to provide that skill via a few basic steps

 

Prerequisites

  • Running AEM author instance (6.2 or 6.3)
  • Dev tools installed (Maven, Git, Eclipse)
  • AEM Tools for Eclipse installed

Note: While writing this Sortie I used AEM 6.3 with Maven Archetype 11, so if you're using different versions your mileage may vary)

 

Steps

Step 1: Get your Git on

The intention with the AEM BootCamp is to follow a standard development process centred around the GitHub repository.

  1. Start by cloning the Sortie repository to you local machine (URL: https://github.com/AEMBootCamp/Sortie-0001-RTE)
  2. I'd suggest you use a standardised folder on your machine to contain all AEM BootCamp code. For example ~/Repos/AEMBootCamp. I'll refer to this folder as [AEM_BOOTCAMP_HOME]
  3. It would probably be best if you cloned the repo at [AEM_BOOTCAMP_HOME]/Sortie-0001-RTE, but feel free to use another location if you so feel. I'll refer to this folder as [REPO_HOME]
  4. Once the repo is cloned, create your own branch.
    1. cd [REPO_HOME]
    2. git branch <yourname>
    3. git checkout <yourname>
  5. Then cd into the [REPO_HOME]/soldiers folder and create a folder for yourself (for example [REPO_HOME]/soldiers/greg)
  6. Now you can create an Eclipse workspace at the [REPO_HOME] level

Make sure you complete the sortie in this folder. Remember to commit regularly and push your code when you're done (or when you want others to review it)

 

Step 2: Create a basic site to be used in this Sortie

To be able to play with the RTE, we need an AEM page to add the component to. And to have a page, we need a site.

So let's start by creating a brand new site using Maven ArcheType 10 or 11 (For details of how to do this, please follow the instruction provided at https://helpx.adobe.com/experience-manager/using/first-arch10.html)

Here are the steps I followed (You might choose another path):
  • In eclipse: File > New > Other > AEM > AEM Sample Multi-Module Project
  • Location: /home/gregf/Repos/AEMBootCamp/Sortie-0001-RTE/soldiers/greg
  • Archetype = aem-project-archetype : 11
  • Name = sortie1-rte
  • Group Id = org.aembootcamp.rte
  • Artifact Id = sortie1-rte
  • Don't deploy on a server
  • Finish
  • Note: I got an issue at this step (See https://github.com/AEMBootCamp/Sortie-0001-RTE/issues/3). However, the project was created successfully
Once the project is created, build and deploy it to a running AEM server:
At this stage you should be able to open the site in your AEM author instance at:
Make sure this page runs as expected, i.e. in Edit mode the screen should look like this:



Note: I am getting intermittent issues here related to not being able to find the sling model used by the service. See https://github.com/AEMBootCamp/Sortie-0001-RTE/issues/4

Step 3: Understand the RTE from an Author's perspective:

Now you can start playing with the author capabilities to understand what is available.

First read:
Note that:
  • The RTE is used for three OOTB components (Text, Table, Text & Image)
  • While doing in-line editing very few options are available to the author
  • When you switch to full-screen mode a few additional option are made available, like ordered and unordered lists
  • The features available in the RTE is dependent on how it is configured, so we'll need to move on to configurations next
Now Clean up the page so that it contains just a title component and a single text component:

 Now let's use the default options available in the RTE to edit the text.
  • Add bold, italic and underlined text
  • Add a link URL
  • Add some left-aligned, right-aligned and centre-aligned text
  • Add an unordered list
  • Add an ordered list
  • When you're done you page should look something like this (shown here in Preview mode)



Step 4: Configuring the RTE

In the previous section we played with some of the default functionality provided by the RTE. However, if we want to make different functionality available in the RTE, plugins need to be added and configured. The available plugins (listed by Plugin ID) are:
  • edit
  • findreplace
  • format
  • image
  • keys
  • justify
  • lists
  • misctools
  • paraformat
  • spellcheck
  • styles
  • subsuperscript
  • table
  • undo

First read:

Complete the tutorial at: https://helpx.adobe.com/experience-manager/using/configure-touchui-rte.html
  • Note; These is some dodgyness in this tutorial that you should keep an eye out for. In particular:
    • The sling:resourceType of the template is incorrect. It should be "touchRTE/components/page/templateRTE"
    • There is not instruction to change the componentGroup for the new component. So it is added to the General group
    • You must remember to make the component accessible to author's in Design mode, else it isn't available in the side panel

Now that you've followed a basic tutorial on the RTE, use your knowledge to build a customized RTE for the sortie1-rte project:
  • I'm building it directly in CRXDE, but amending the tutorial details according to my needs
  • I have Eclipse set up to synchronise with CRX using vault
  • My component is based on HTL, not JSP
  • I'm creating a custom component that customizes the RTE to include a findreplace plugin and spellcheck plugin

Final Checkpoint

Once you've completed step 4, you should be in a position to give your project to another developer to use. You can test this locally by:
  • Deleting the sortie1-rte from your local AEM instance
  • Rebuilding from source using mvn clean install -PautoInstallPackage
  • If you now open the en page in Edit mode, the author should have access to your text component with customized RTE plugins.

References:

Web Links:
GitHub Repo:
Slack Channel:
  • sortie1-rte

 

Issues and resolutions during this sortie:

Finding and resolving issues is a big part of the learning experience. The AEM BootCamp uses GitHub for logging and managing issues.

The following issues were experienced by soldiers while completing the Sortie:





Tuesday, June 13, 2017

Welcome

Welcome soldier!

If you want to join the AEM BootCamp, introduce yourself below and send us a mail at aembootcamp  [at]   8bitplatoon.com. Some specific instructions regarding the email:

  • Use the subject line "Sign me up"
  • Include your GitHub user name in the mail

Once we receive the mail, we'll send you and invite to join our Slack Team and GitHub page.

Regards,

The AEM BootCamp team