@ez-aem/policies v1.0.3
EZ-AEM Policies
Easily Manage AEM Policies and Style System with EZ-AEM Policies.
The AEM Policies and Style System provide a flexible and powerful way to manage access and styling of components. But, authoring the policies - either in the AEM GUI or manually writing XML can be tedious and limiting.
EZ-AEM Policies is a toolset to make authoring and managing your Policies and Styles easier. The included tools are:
Component Policies
Component Policies are used to define the settings to be applied to a component within AEM. Component Policy definitions include "metadata" such as the component type, description, policy name, styles, and title. Component Policies may have an attributes object with has settings that are to be applied for the component. Additionally, Component Policies may have a configurations object that defines related settings such as default components, authoring, plugins, etc.
Usage
// Example usage of Component Policies
const { ComponentPolicy } = require("@ez-aem/policies");
const components = require("../components");
const styles = require("../../../theme/src/styles");
const cqAuthoring = {
assetToComponentMapping: {
mapping_image: {
attributes: {
assetGroup: "media",
assetMimetype: "image/*",
droptarget: "image",
resourceType: "core/wcm/components/image/v3/image"
}
},
},
};
module.exports = [
new ComponentPolicy({
component: "core/wcm/components/container/v1/container",
description: "Default Policy for Container Component",
policy: "policy_default",
styles: styles.container.default,
title: "Default Container Policy",
attributes: {
components: components.all,
layout: "responsiveGrid",
layoutDisabled: false,
},
configurations: {
"cq:authoring": cqAuthoring,
}
})
}Options
| Options | Required | Description |
|---|---|---|
| component | true | The resource Type of the component. For the Core Container component, the value would be "core/wcm/components/container/v1/container" |
| description | false | A description of the purpose of the Component Policy, that will be displayed in the in the Policy editor GUI in AEM. |
| policy | true | The name of the Component Policy. This will be used as a reference within page template definitions to assign a Policy to a component type. |
| styles | false | A Style Groups object with the definitions for the Style System |
| title | true | The title of the Component Policy, that will display in the AEM Policy editor GUI. |
| attributes | false | An object with attributes that will be applied to the component in AEM. Consult the component source code for options. Whatever is included here will be output as part of the main policy node in xml so it's up to you to ensure it's functional |
| configurations | false | Additional component configurations that are separate from Attributes and metadata. For example, the cq:authoring values or plugins. These configurations will be output as children of the main node in the xml. Again, it's up to you to ensure that it's functional. |
Style Groups and Items
EZ-AEM Policies provides tools to manage the AEM Style System: CQStyleGroups, CQStyleGroup, and CQStyle.
CQStyle
The CQStyle is the individual definition of a Style System option and is composed of a few attributes: label, id, classes. CQStyle objects are combined in an array to form the CQStyleGroup.
Usage
new CQStyle({
label: "Library Preset",
id: "library-preset",
classes: "library-preset accordion--preset:library-preset",
}),Options
| Attribute | Required | Default Value | Description |
|---|---|---|---|
| label | true | null | The label that will be visible to authors to choose the Style and apply it to a component. |
| id | true | null | The id corresponds with the cq:styleId and is used to match applied styles to a component. This id is stored on a component when selected by an author for matching. It can be referenced in code to apply a Style to a component. This must be unique. AEM generates this id for you, but the EZ-AEM Policies toolset does not, as the ID must remain the same after it has been used by an author for later referencing. Cannot have spaces or special characters. |
| classes | false | The id value will be used as the default | The value classes attribute will be output on the component wrapping element upon a match with the id value. By default, the value of the id will be used, and as such, the classes attribute isn't necessary. But if you would like a different value than the id or perhaps multiple classes to be output, you can include those in the string. |
CQStyleGroup
The CQStyleGroup includes an array of CQStyle's along with some other metadata. Multiple CQStyleGroup's can be combined to form a CQStyleGroups object that is used in a policy.
Usage
const { CQStyle, CQStyleGroup } = require("@ez-aem/policies");
module.exports = new CQStyleGroup({
label: "Presets",
styles: [
new CQStyle({
label: "Library Preset",
id: "library-preset",
classes: "library-preset accordion--preset:library-preset",
}),
],
});Options
| Attribute | Required | Default Value | Description |
|---|---|---|---|
| label | true | null | The label visible to authors in the Policy Editor GUI and also in the authoring editor Style System dropdown. |
| allowMultiple | false | false | Determines if multiple CQStyle settings can be applied simultaneously. |
| styles | true | CQStyle[] | An array of CQStyle objects. |
CQStyleGroups
Multiple CQStyleGroup's can be combined to form a CQStyleGroups array that is used in a policy. Accepts an CQStyleGroup[] as it's parameter.
Usage
const { CQStyleGroups } = require("@ez-aem/policies");
module.exports = new CQStyleGroups([
require("./preset"),
require("../_common/justify-self"),
require("../_common/align-self"),
]);Policy Generator
Generating the policies/.content.xml is the one of the biggest benefits of the EZ-AEM Policies toolset, and allows you to use a scripting language to simplify and supercharge your Policy management. Create a file which will be called by an npm run generate command. In that file require all of your Component Policies and Style Groups. Call the generatePolicies method, passing the policies array and the path where you want the policies/.content.xml to be generated. Optionally you can provide a tabWidth parameter to control the indentation of the generated xml.
Usage
// package.json
{
"scripts": {
"generatePolicies": "node ./generatePolicies.js"
}
}// ./generatePolicies.js
const { generatePolicies } = require("@ez-aem/policies");
const policies = [
require("./components/accordion"),
require("./components/breadcrumb"),
require("./components/button"),
require("./components/carousel"),
...require("./components/container"),
require("./components/download"),
require("./components/embed"),
...require("./components/experiencefragment"),
require("./components/form-button"),
require("./components/form-container"),
require("./components/image"),
require("./components/languagenavigation"),
require("./components/list"),
require("./components/navigation"),
require("./components/page"),
require("./components/progressbar"),
require("./components/search"),
require("./components/separator"),
require("./components/tabs"),
require("./components/teaser"),
require("./components/text"),
require("./components/title"),
];
generatePolicies(policies, "/src/main/content/jcr_root/conf/mysite/settings/wcm/policies");Options
| Parameter | Required | Default Value | Description |
|---|---|---|---|
| policies | true | null | Type CQStyleGroups[]. An array of Policy objects. |
| outputPath | true | null | The path to where you want the policies/.content.xml file output. This value will be combined with __dirname from the directory in which the npm script was ran. |
| tabWidth | false | 2 | The number of spaces to indent the XML output. |