This project contains the AEM CIF Venia reference site. It demonstrates the usage of CIF Core Components for Adobe Experience Manager (AEM). It is intended as a best-practice set of examples as well as a potential starting point to develop your own functionality.
The project can be used in two variants:
- AEM as a Cloud Service deployments
- AEM on-prem or AEM hosted by Adobe Managed Services deployments
This project was generated using the aem-project-archetype.
The default variant of the project is built and deployed on AEM as a Cloud Service. It requires an AEM as a Cloud Service with entitlement for the CIF Add-On. The CIF Add-On provides the commerce authoring tooling like product & category pickers or product search for authors it also manages the backend connection to Magento (or alternative commerce system) via GraphQL. Once provisioned it is deployed on AEM as a Cloud Service environments automatically.
The deployment on AEM as a Cloud Service happens via Cloud Manager and this project can be transferred into the Cloud Manager git repository.
For local development an AEM as a Cloud Service SDK with the CIF Add-On installed is required. Both can be downloaded via the Software Distribution channel. See Set up local AEM Runtime for instructions. For build and deployment steps see below.
In this variant the project is built and deployed on AEM 6.5 hosted by Adobe Managed Services or self-hosted. The minimum requirements are AEM 6.5 with the CIF Connector installed. The CIF Connector is not included in the generated project and must be installed separately. See CIF Connector project for instructions.
The CIF Core Components and the CIF Connector connect to a Magento (or alternative) via GraphQL. This connection has to be configured in the com.adobe.cq.commerce.graphql.client.impl.GraphqlClientImpl-default.config config. A reference is included in the project template. Consult documentation for detailed configuation steps.
The project deployment can be done via Cloud Manager or AEM package install. For project build and deployment use the classic profile, see steps below.
This project uses a dev branch for the development cycle between releases. On dev there can be dependencies to snapshot versions of the CIF Core components project. CircleCI will provide the snapshot dependencies including the react-components package on all branches except main.
After a release of the required dependencies, all dependencies have to be updated to release versions and the current state of the dev branch is merged to main. All releases of this project will be done from the main branch. This guarantees that the state on main can always be built and installed as-is.
The main parts of the template are:
- core: Java bundle containing all core functionality like OSGi services, listeners or schedulers, as well as component-related Java code such as servlets or request filters.
- ui.apps: contains the /apps (and /etc) parts of the project, ie JS&CSS clientlibs, components, templates and runmode specific configs
- ui.content: contains sample content using the components from the ui.apps
- ui.tests: Java bundle containing JUnit tests that are executed server-side. This bundle is not to be deployed onto production.
- ui.launcher: contains glue code that deploys the ui.tests bundle (and dependent bundles) to the server and triggers the remote JUnit execution
- ui.frontend: an optional dedicated front-end build mechanism (Angular, React or general Webpack project)
The Venia reference project code demonstrates how CIF core component can be adopted, customized, and extended for a project. The project includes an extended product teaser component example called MyProductTeaser. It demonstrates the CIF core components customization options by using an extended Sling MyProductTeaser model and a proxy component overlay.
This project includes sample configurations to demonstrate the usage of custom URLs for product and category pages. This allows each project to setup individual URL patterns for product and category pages according to their SEO needs. A combination of UrlProvider config with Sling Mappings is used.
This configuration must be adjusted with the external domain used by the project. The Sling Mappings are working based on the hostname and domain. Therefore this configuration is disabled by default and must be enabled before deployment. To do so rename the Sling Mapping hostname.adobeaemcloud.com folder in ui.content/src/main/content/jcr_root/etc/map.publish/https according to the used domain name and enable this config by adding resource.resolver.map.location="/etc/map.publish" to the JcrResourceResolver config.
For detailed configuration options see Configuring and customizing product and category pages URLs in the CIF Core Components Wiki and the AEM Resource Mapping documentation.
CIF Core Components already have built-in support for caching GraphQL responses for individual components. This feature can be used to reduce the number of GraphQL backend calls by a large factor. An effective caching can be achieved especially for repeating queries like retrieving the category tree for a navigation component or fetching all the available aggregations/facets values displayed on the product search and category pages.
To build all the modules, run in the project root directory the following command with Maven 3:
mvn clean install
This will build only the artefacts for an AEM as a Cloud Service target. To build the artefacts for AEM on-premise as target
use the -Pclassic profile:
mvn clean install -Pclassic
If you have a running AEM instance you can build and package the whole project and deploy into AEM with
mvn clean install -PautoInstallSinglePackage
Or to deploy it to a publish instance, run
mvn clean install -PautoInstallSinglePackagePublish
Or to deploy only the bundle to the author, run
mvn clean install -PautoInstallBundle
The classic profile can be combined with either of the examples mentioned above.
The client-side CIF core components access the Magento GraphQL endpoint directly, so all calls have to either be served from the same endpoint as AEM or served via a proxy that adds CORS headers.
- For AEMaaCS installations this is pre-configured as part of the CIF onboarding.
- For AEM on-prem installations, please add a proxy to your dispatcher configuration. You can find an example of dispatcher configuration in the CIF Core Components project.
- For local development, you can start a proxy using the following command. The GraphQL endpoint is then available at
http://localhost:3002/graphql.
npx local-cors-proxy --proxyUrl https://my.magento.cloud --port 3002 --proxyPartial ''
There are two levels of testing contained in the project:
This show-cases classic unit testing of the code contained in the bundle. To test, execute:
mvn clean test
This allows running integration tests that exercise the capabilities of AEM via HTTP calls to its API. To run the integration tests, use one of the following two commands depending on your project variant.
For AEM as a Cloud project:
mvn clean verify -Plocal,cloud
For AEM classic project:
mvn clean verify -Plocal,classic
Test classes must be saved in the src/main/java directory (or any of its
subdirectories), and must be contained in files matching the pattern *IT.java.
The configuration provides sensible defaults for a typical local installation of
AEM. If you want to point the integration tests to different AEM author and
publish instances, you can use the following system properties via Maven's -D
flag.
| Property | Description | Default value |
|---|---|---|
it.author.url |
URL of the author instance | http://localhost:4502 |
it.author.user |
Admin user for the author instance | admin |
it.author.password |
Password of the admin user for the author instance | admin |
it.publish.url |
URL of the publish instance | http://localhost:4503 |
it.publish.user |
Admin user for the publish instance | admin |
it.publish.password |
Password of the admin user for the publish instance | admin |
The integration tests in this archetype use the AEM Testing Clients and showcase some recommended best practices to be put in use when writing integration tests for AEM.
The frontend module is made available using an AEM ClientLib. When executing the NPM build script, the app is built and the aem-clientlib-generator package takes the resulting build output and transforms it into such a ClientLib.
A ClientLib will consist of the following files and directories:
css/: CSS files which can be requested in the HTMLcss.txt(tells AEM the order and names of files incss/so they can be merged)js/: JavaScript files which can be requested in the HTMLjs.txt(tells AEM the order and names of files injs/so they can be mergedresources/: Source maps, non-entrypoint code chunks (resulting from code splitting), static assets (e.g. icons), etc.
The project comes with the auto-public repository configured. To set up the repository in your Maven settings, refer to:
http://helpx.adobe.com/experience-manager/kb/SetUpTheAdobeMavenRepository.html
The Venia demo is only released on Github but not on Maven Central like other projects like the CIF components. To perform a release, we use a dedicated profile to make sure all modules versions are updated:
mvn release:prepare release:clean -Pclassic
Releases must be done on the main branch.
Contributions are welcomed! Read the Contributing Guide for more information.
This project is licensed under the Apache V2 License. See LICENSE for more information.