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.
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.
Important: The Venia project has two build profiles depending on the target platform where you deploy the project:
cloud(default profile): this is the default profile and targets AEM as a Cloud Service (AEMaaCS). This is active by default if you don't specify a profile or if-Pcloudis defined.classic: this profile is for Abobe Managed Services (AMS) or on-premise deployments. This is defined with the-Pclassicprofile.
Note that while the 'cloud' profile is active by default, the default behavior of maven is to disable it when any other profile is specified on the command line. This means that, for example, one has to explicitly specify the 'cloud' profile when using one of the installation profiles shown below.
To build all the modules with the default cloud profile, run in the project root directory the following command with Maven 3:
mvn clean install
If you have a running AEM instance you can build and package the whole project and deploy into AEM with
mvn clean install -PautoInstallPackage,cloud
Or to deploy it to a publish instance, run
mvn clean install -PautoInstallPackagePublish,cloud
Or alternatively
mvn clean install -PautoInstallPackage,cloud -Daem.port=4503
Or to deploy only the bundle to the author, run
mvn clean install -PautoInstallBundle,cloud
If you are building the Venia demo for on-premise deployment, simply use mvn clean install -Pclassic for the top-level command that builds all the modules, and replace the cloud profile with classic in the other example commands like mvn clean install -PautoInstallPackage,classic.
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 -Prelease-prepare
Contributions are welcomed! Read the Contributing Guide for more information.
This project is licensed under the Apache V2 License. See LICENSE for more information.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent