Using Core Components

To get up-and-running with Core Components in your own project, there are four steps, which are individually detailed in sections below:

1. Download and Install
2. Create Proxy Components
3. Load the Core Styles
4. Enable the Components

Download and Install

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.

Create Proxy Components

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:

1. 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

2. Point to the corresponding Core Component version with the super-type.

   Example
   Add following property:
   sling:resourceSuperType="core/wcm/components/title/v1/title"

3. 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.

Load the Core Styles

1. If not done yet, create a Client Library that contains all of the CSS and JS files that are needed for your site.

2. 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.

Allow the Components

The following steps are performed in the Template Editor.

1. In the Template Editor, select the Layout Container, and open its policy.
2. In the list of Allowed Components, select the proxy components created previously, which should show up under the component group assigned to them. Once done, apply the changes.
3. Optionally, for the components that have a design dialog, they can be pre-configured.

That’s it! In the pages created from the edited template, you should now be able to use the newly created components.

Read next:

• Customizing Core Components - to learn how to style and customize the core components.
• Component Guidelines - to learn the implementation patterns of the Core Components.