Module for Adobe Experience Manager (AEM) to automate the conversion of HTML code into Sightly, as well as generate the associated Java Sling Models and XML dialogs, aiming to streamline the development process of AEM components.
npm install aem-htl-builderbash
npm i aem-htl-builder
`
$3
If you cloned this repository instead of installing it via npm, to run the scripts go to
package.json file and run the scripts from there.
Configuration
After installing the module, you need to set up a configuration file.
Run the following command to create an empty configuration file.
`bash
npx aem-htl-builder configure
`
Now that the file has been created you need to configure it.
Here is an example of valid configuration file:
`json
{
"project": {
"aemProjectPath": "/Users/username/projects/mysite",
"rootPackage": "com.mysite.core",
"componentGroup": "MySite - Content",
"appName" : "mysite"
},
"html": {
"useSingleFile": true,
"singleFilePath": "/Users/username/html-files/test.html",
"directoryPath": "/Users/username/html-files"
}
}
`
And below is the detailed description of what each field does:
1. To configure the project object:
- aemProjectPath: Specify the absolute path to your local AEM project.
- rootPackage: Specify the directory holding AEM Sling models. You can find it at aemProjectName/core/src/main/java/
- componentGroup: Specify the component group to which the components will be added.
- appName: The appName field represents the name of the root folder within the aemProjectName/ui.apps/src/main/content/jcr_root/apps/ directory in your AEM project. This folder contains your project-specific components, templates, and other resources.
2. To configure the html object:
- useSingleFile: If set to true, the module will read and use the HTML file from the singleFilePath field. If set to false, the module will prompt the user to select an HTML file via the terminal from directoryPath.
- singleFilePath : Specify the path to an existing HTML file.
- directoryPath : Specify the path to an existing directory containing HTML files which you will use do build AEM component.
$3
You can also set-up configuration by simply running the script with already specified parameters (example below):
`bash
aem-htl-builder configure \
--aemProjectPath="/Users/username/projects/mysite" \
--rootPackage="com.mysite.core" \
--componentGroup="MySite - Content" \
--appName="mysite" \
--useSingleFile=true \
--singleFilePath="/Users/username/html-files/test.html" \
--directoryPath="/Users/username/html-files"
`
Syntax
This section provides a detailed guide on how to prepare your HTML for processing by this module.
It covers the necessary attribute HTML syntax for each AEM component field type.
Here is a list of all the attributes that are currently supported by the module:
- textfield-[VarName]
- textarea-[VarName]
- checkbox-[VarName]
- link-[VarName]
- img-[VarName]
- select-[VarName]
- description
- i18n-[VarName]
- list-[VarName]
The [VarName] placeholder represents the variable name you choose for the field and should be replaced by the actual name in your HTML.
$3
To add a textfield to your component, you need to follow these steps:
Add the textfield-[VarName] attribute to your paragraph tag, replacing [VarName] with your chosen field name.
- HTML Original:
`html
Component Title
`
- What module expects:
`html
Component Title
`
$3
To add a textarea to your component, you need to follow these steps:
Add the textarea-[VarName] attribute to your paragraph tag, replacing [VarName] with your chosen field name.
- HTML Original:
`html
Lorem Ipsum is simply dummy text of the printing and typesetting industry.
`
- What module expects:
`html
Lorem Ipsum is simply dummy text of the printing and typesetting industry.
`
$3
- HTML Original:
`html
Species: Human
`
- What module expects:
`html
Species: Human
`
$3
To add a link to your component, you need to follow these steps:
Add the link-[VarName] attribute to your paragraph tag, replacing [VarName] with your chosen field name.
- HTML Original:
`html
Click Here
`
- What module expects:
`html
Click Here
`
$3
To add an image to your component, you need to follow these steps:
Add the img-[VarName] attribute to your html tag, replacing [VarName] with your chosen field name.
- HTML Original:
`html
`
- What module expects:
`html
`
$3
- ~~HTML:~~
`html
`
$3
If you have an element in your html which will be used for i18n you will need to:
Add the i18n-[VarName] attribute to your html tag, replacing [VarName] with your chosen field name.
- HTML Original:
`html
Location
Contact
`
- What module expects:
`html
Location
Contact
`
After running aem-htl-builder convert command following will be added to:
- en.json:
`json
{
"Location": "Location",
"Contact": "Contact"
}
`
#### Note
If there is already in en.json file the key with the same name e.g. 'Location' this example would override
its value with new one.
$3
The description requires the presence of another attribute from the list.
- HTML Original:
`html
Component Title
`
- What module expects:
`html
Component Title
`
textfield-title serves as an example and it can be as well e.g. img-varName , link-varName etc.
$3
If you want to add a list to your component, you need to follow these steps:
Add the list-[VarName] attribute to tag, replacing [VarName] with your chosen list name.
- HTML Original:
`html
-
Margherita
10.99 €
-
Pepperoni
Click the link here!
13.99 €
`
- What module expects:
`html
-
Margherita
10.99 €
-
Pepperoni
Click the link here!
13.99 €
`
Notice that since this is a list you need to add attributes only to elements which you want to include in the list (multifield) only once.
After running aem-htl-builder convert command following code will be added to component dialog:
`xml
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/multifield"
fieldLabel="pizzasModel"
composite="{Boolean}true">
sling:resourceType="granite/ui/components/coral/foundation/container"
name="./pizzasModel">
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
fieldLabel="title"
name="./title"/>
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
fieldLabel="price"
name="./price"/>
jcr:primaryType="nt:unstructured"
jcr:title="pizzaLink Container"
sling:resourceType="granite/ui/components/coral/foundation/form/fieldset">
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/foundation/form/checkbox"
text="Open link in another tab."
name="./pizzaLinkCheckbox"
value="true"/>
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/pathfield"
fieldLabel="pizzaLink"
name="./pizzaLink"
required="{Boolean}false"
rootPath="/content"/>
`
The module will as well add the original HTML list as a comment under the newly converted list.
Convert HTML to Sightly
After successfully setting up configuration, and adding custom attributes to original HTML file
run the following command to create AEM component
`bash
npx aem-htl-builder convert
``