To get up-and-running with Core Components in your own project, there are four steps, which are individually detailed in sections below:
Alternatively, for broader instructions on how to get started from scratch with the project setup, the Core Components, Editable Templates, Client Libraries and component development, the following multi-part tutorial might be of interest:
Getting Started with AEM Sites - WKND Tutorial
One of the driving ideas behind the core components is flexibility. Releasing new versions of the Core Components more often allows Adobe to be more flexible in delivering new features. Developers in turn can be flexible in which components they choose to integrate into their projects and how often they wish to update them.
For this reason, the Core Components are not part of the quickstart when starting in production mode (without sample content). Therefore, your first step is to download the latest released content package from GitHub and to install it on your AEM environments.
There are several ways to automate this, but the simplest way to quickly install a content package on an instance is by using the Package Manager; see Install Packages. Also, once you’ll have a publish instance running as well, you’ll need to replicate that package to the publisher; see Replicating Packages.
For reasons explained in the Proxy Component Pattern section, Core Components must not be directly referenced from the content. To avoid that, they all belong to a hidden component group ( .core-wcm
or .core-wcm-form
), which will prevent them from showing up directly in the editor.
Instead, site-specific components must be created, which define the desired component name and group to display to page authors, and refer each to a Core Component as their super-type. These site-specific components are sometimes called “proxy components”, because they don’t need to contain anything and serve mostly to define the version of a component to use for the site. However, when customizing the Core Components, these proxy components play an essential role for markup and logic customization.
So for each Core Component that is desired to be used for a site, you must:
Create a corresponding proxy component in the site’s components folder.
Example
Under /apps/my-site/components
create a title node of type cq:Component
Point to the corresponding Core Component version with the super-type.
Example
Add following property:
sling:resourceSuperType="core/wcm/components/title/v1/title"
Define the component’s group, title, and optionally description. These values are project specific and dictate how the component is exposed to authors.
Example
Add following properties:
componentGroup="My Site"
jcr:title="Title"
jcr:description="Section Heading"
For instance, look at the title component of the WKND site, which is a good example of a proxy component that is built that way.
If not done yet, create a Client Library that contains all of the CSS and JS files that are needed for your site.
On the Client Library of your site, add the dependencies to the Core Components that might be needed. This is done by adding an embed
property.
For example, to include the Client Libraries of all v1 Core Components, the property to add would be:
embed="[
core.wcm.components.image.v1,
core.wcm.components.list.v1,
core.wcm.components.breadcrumb.v1,
core.wcm.components.form.container.v1,
core.wcm.components.form.text.v1
]"
Make sure that your proxy components and client libraries have been deployed to your AEM environment before moving to the next section.
The following steps are performed in the Template Editor.
That’s it! In the pages created from the edited template, you should now be able to use the newly created components.
Read next: