Getting Started in AEM Mobile With the Ionic AEM Apps Library

The Phonegap aspect of AEM Mobile (I’ll eventually come up with some reasonable way to refer to this) previously called AEM Apps gives authors the ability to cobble together native hybrid applications using the authoring interfaces and affordances proper to AEM.  While the interfaces for authoring and the methodologies for development of components and templates will be familiar to authors and developers respectively, the differences between authoring and developing for a site and a mobile application expose numerous technical and mental hurdles.  The Ionic AEM Apps Library and complementary Maven Archetype endeavor to lower or eliminate these hurdles while putting in place standards and patterns for authoring and development in this context.  

This writing is the first in a series exploring the functionality, concepts, and practices introduced by the Phonegap aspect of AEM Mobile, the Ionic AEM Apps Library, and the complementary Ionic AEM Apps Maven Archetype.  Through this series we will build the canonical requirement set for demonstrating any application framework, a ToDo application.  The final code which this series of posts will result in can be found on the Olson Digital Github https://github.com/OlsonDigital/ionic-aem-mobile-todo-app.

A Quick Anecdotal Introduction to the Library and Archetype

AEM Mobile (Apps), while not opinionated concerning how you develop your apps from a code perspective, is extremely opinionated concerning how your application content is configured.  These two extremes lead to two problems.  First, the lack of opinion concerning development leaves developers without reasonable patterns to follow.  Second, the abundance of opinion concerning content structure leaves developers with the task of creating a massive amount of fairly cryptic configuration.  The combination of these two matters led us to develop the Ionic AEM Apps Library and the supporting Archetype.  The Former encapsulates our opinions concerning how single page Cordova applications should be authored in the context of AEM and the later bootstraps your Content Sync configuration allowing you to focus only on the concerns specific to your unique deployment.

We speak a bit more on the matter on Youtube https://youtu.be/KNK75v-Pwhg?list=PLlGWqv32msPdrEofFFzuHzQa9gKphoU_d.

A Quick Word on why Nomenclature is an Issue

If you’ve been to any recent presentation on AEM Mobile you have probably heard this bit of history but I place it here in an effort to clear up confusion in the reading of this and the subsequent posts in the series.  

Before rebranding there were two separate mobile app offerings integrated with AEM: AEM Apps and DPS.  AEM Apps was a collection of tools and dashboards allowing for the authoring of Cordova applications within AEM.  DPS was a stand alone product which happened to integrate with AEM via AEM being able to push Articles and Collections to DPS.  Earlier this year these two offerings were brought under a single umbrella from a naming perspective and the entire package is now called AEM Mobile.  What we are talking about in this post and the subsequent few posts is what was formerly known as AEM Apps, that is, the ability for authors to author a Cordova application from within AEM and the various deployment affordances which come with that.  Around post 5 in the series we will switch focus to the aspect of AEM Mobile formerly named DPS.

Getting Started With the Archetype

We have produced the Ionic AEM Apps Maven Archetype to help bootstrap your application development.  The Archetype produces a multi-module project structure which includes and deploys to AEM:

1. A Core project bundle where Java backing classes, services, etc are defined

2. A UI module containing deployable elements such as Component definitions, Sightly, CSS, JS, etc

3. The Ionic AEM Apps Library bundle

4. An initial content tree for the application

5. Content Sync configuration for the application

The fourth and fifth elements above were the primary drivers behind creating an Archetype as these configurations are quite robust and their creation tends to be error prone resulting in problems which are difficult to debug.  Content Sync will be discussed in greater detail in a future post.

To get started with development we can execute the Archetype, create, and deploy a new project following the directions in the Archetype’s README.  For the purposes of our example we will call the application “TODO Mobile App” and will give it an artifact ID of “todo-mobile-app”.  The URLs and examples in this and the next couple posts presume your usage of the same artifact ID.  If you use a different ID simply swap out “todo-mobile-app” where appropriate.

Anatomy of an Ionic AEM Apps Project

With a project created we can look in detail at the anatomy of the project, the structure of which treads the line between technical necessity and opinion.

This organization, for the most part, should be fairly familiar to you as an AEM developer.  The majority of the code resides in the UI module.  Components, Templates, and Client Libraries are established as they would be in typical AEM projects.  Where the structure differs is principally in the Content Sync configuration.  To understand this configuration some understanding of Content Sync is necessary.

Content Sync, at its core, is a mechanism to produce a .zip file containing content.  How it cobbles together this zip file is based on the Content Sync configuration it is executing.  What each configuration does during the construction of the zip file is based on the properties of the configuration and most importantly the Content Sync Handler specified for the configuration.  Content Sync Handlers are OSGI services which do the work of looking up, transforming, and populating the zip file with the configured content.  Some of the handlers are quite simple, such as copy which simply copies specified resources into a specified location in the zip file.  Others perform more robust logic such as clientlib which renders a referenced Client Library and places the rendering into the resultant zip file.  

Exercising the Project

Our application can be viewed in the AEM Mobile dashboard on author http://localhost:4502/libs/mobileapps/admin/content/dashboard.html/content/mobileapps/todo-mobile-app/shell.  The Archetype starts you off with an Application Root, under which you create Application States (the next post in this series will discuss Roots, States, and how these map to Angular application constructs in a depth which one might call excruciating).  To exercise our project we can build out a single state application which does essentially nothing except present a title.  We can then go through the steps of previewing the application, downloading the Content Sync package of the application, and building it to a device.  

• From the AEM Mobile Dashboard for the app http://localhost:4502/libs/mobileapps/admin/content/dashboard.html/content/mobileapps/todo-mobile-app/shell, click on “TODO Mobile App English” under “Manage Content”

• Select “TODO Mobile App”

• Create a new Page

• Select The “TODO Mobile App - Application State” Template

• Open the new page for editing

• Add a title component (just so there is some content on the page)

• Return to the english content root http://localhost:4502/libs/mobileapps/admin/content.html/content/mobileapps/todo-mobile-app/en

• Open the TODO Mobile App Page for editing

• Open the Page Properties dialog

• Open the Application tab

• Select the new page we created as the default state for the application

Once done, to preview our application, simply switch to Preview mode and refresh the page.  You should see the Title component which you added to the new page you created.  While this is less than impressive aesthetically, what you are seeing is a single page Ionic application running in your browser.

Next we can pull down the application using Content Sync and deploy it to a device or device emulator.

NOTE: What is contained in the zip file generated by Content Sync is a Cordova application.  In order to build and run this application you will need to have your development environment appropriately set up.  Instructions concerning how to do this can be found in numerous places including the Cordova site https://cordova.apache.org/#getstarted and the Ionic site http://ionicframework.com/getting-started/.  Before attempting to build and run a project created using AEM Mobile it is advisable to try creating a simple Ionic or vanilla Cordova project outside the context of AEM using the Getting Started instructions found on those sites to ensure your environment is appropriately situated.  General familiarity with Cordova will also be invaluable as you start developing more robust applications.

• Open the AEM Mobile Dashboard for the app http://localhost:4502/libs/mobileapps/admin/content/dashboard.html/content/mobileapps/todo-mobile-app/shell

• Click on the Phonegap icon in the top right of the PhoneGap Build tile

• Select Development

• Press Download

By executing these steps you have invoked the Content Sync configuration located at jcr_root/content/mobileapps/todo-mobile-app/shell/_jcr_content/pge-app/IonicAEMApp-dev in our project (note, while Content Sync will be discussed in depth in a future post, if you want to start exploring it now you can spider through the configurations starting from the config listed above to get a feel for how the items are pieced together).  This Configuration describes how to transform our page tree, assets, client libraries, etc, into a structure which Cordova will be able to recognize and build.  If you are familiar with Cordova development you should recognize the structure of the contents of the zip file.  

To deploy the application to a device or emulator

• Unzip the zip file

• Open a console at the root of the unzipped folder structure

• Run `cordova platforms add android` or `cordova platforms add ios` depending on the platform you wish to test

• Run `cordova build android` or `cordova build ios`

• Run `cordova run android` or `cordova run ios`

If you have a device plugged in, your development environment appropriately set up, and some luck, Cordova should deploy the application to the device, otherwise it will attempt to open an emulator and deploy to that.  What you should see as the app opens is the lovely default splash screen complete with comic sans font, followed by the same title screen which you saw in preview mode.

Assuming all went well, you now have a functioning hybrid native application authored in AEM and you’ve successfully overcome a major hurdle in hybrid application development and AEM Mobile development - getting setup.  In the next post we will explore the authoring patterns enabled by the Ionic AEM Apps library and specifically the mapping between AEM Pages and Angular UI Router States.  That will be quickly followed by a deep dive into Ionic AEM Apps component development in a third post.  Beyond that Content Sync, concepts of modular development, and reuse across the various faces of AEM Mobile will be explored in future posts.