🆕 Note that the requirements have changed as of September 2016. If you do not have AEM 6.2, please use the release/6.1-FP2 branch.
To provide you - the developer - with an AEM Apps project on your filesystem, ready to be built and installed to a running AEM 6.2 instance and committed to a version control system.
- AEM 6.2
- Apache Maven version
>=3.2.5 - node.js version
>=4.3.0 - PhoneGap CLI version
>=6.3.0(install exact version withnpm install -g [email protected]) - (iOS only) Xcode version
>=7.3.1 - (iOS only) ios-deploy
- (Android only) Android SDK
Clone this repository to your machine to begin.
This repository is built around two placeholders to enable quick customization: brand_name_placeholder and app_name_placeholder.
To customize this boilerplate for your own project, simply replace every occurrence of these two variables with (JCR-friendly) names of your choice. You can use customize-app.sh for this, if you're using bash.
For example, let's say my brand name is 'Geometrixx' (originality is not the goal here) and app name is 'ShapesCon'.
Note: the following has only been tested on OS X. YMMV.
./customize-app.sh Geometrixx ShapesCon
This project is based on the multimodule-content-package-archetype (with the bundle removed for simplicity), so it contains the same helpful profiles and properties to build and deploy your project with maven.
From the project root, run:
mvn -PautoInstallPackage clean install
... to build all the content packages and install to a AEM instance. The CRX host and port can be specified on the command line with mvn -Dcrx.host=otherhost -Dcrx.port=5502 <goals>
An app template only install option is also available. This option will only install the starter kit core components and an associated app template. Once the template only option has been installed instances of the starter kit can be created by accessing the Create App action of the AEM Apps console.
From the project root, run:
mvn -PautoInstallTemplate clean install
- Navigate to the AEM Apps console
- Select Create menu option
- Select Create App
- Choose the Starter Kit template
- Complete the wizard
Once built and installed via maven, your new app should be editable in AEM. Take a look at the new Apps admin console to view the available apps on your instance.
A new app folder with the brand name you specified above ('Geometrixx' in my case) should be listed. Tap it to view the app you created, which will be listed with the PhoneGap logo as it's thumbnail. If you followed the instructions exactly and have your author instance running locally on :4502, you should be able to author your new app via the following link:
http://localhost:4502/editor.html/content/mobileapps/Geometrixx/ShapesCon/en/home.html
A few things to try:
- Add a child page. It will become linked via the Ionic Menu List component already included on the home page of your app
- Add an image or text component
- Check out the aem-phonegap-kitchen-sink project to experiment with a number of components that deal with PhoneGap's device APIs
- Enter 'preview' mode, and drag the page to the right to reveal the left shelf menu
From the Apps console, navigate to your app's Command Center (your URI will differ based on the values you provided to customize-app.sh).
Locate the 'PhoneGap Build' tile, and the down arrow to the top right of the pane. Tap this arrow, then tap the 'Download CLI' item to initiate a download of your app's content. A .zip payload will be downloaded locally. Using your command line of choice, navigate to the directory created by extracting the payload. Using OS X? this handy Finder toolbar app makes it easy.
Using the PhoneGap CLI, build and deploy your application to the iOS Simulator with the following command:
phonegap emulate ios
Note: at the time of writing there is an open issue with Apple's ATS and Cordova-ios. See the following note in our docs for a workaround.
To use vlt with this project, first build and install the package to your local AEM instance as described above. Then cd 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.
A very open Content-Security-Policy meta tag has been included in two places. You should review the documentation on its usage and adjust this tag for your particular app's requirements.
localhost takes on a different meaning when your app is running on Android, unfortunately. As a workaround you can use either http://10.0.2.2:4503/ as your app's "Update URL" (which will fail on iOS), or set it to the IP address of your machine.
Just testing the waters? No problem. From the package manager console, locate the package named 'your-app-name-content-1.0-SNAPSHOT.zip'. It should be at the top of the list. Uninstall this package to remove your app, it's template, component, design, and supporting clientlibs.