This section describes how to configure and if desired, extend the design importer for landing pages. Working with Landing Pages after import is covered in Landing Pages.

Making the design importer extract your custom component

Here are the logical steps to make design importer recognize your custom component

1. Create a TagHandler

A tag handler is a POJO that handles HTML tags of a specific kind. The “kind” of HTML tags your TagHandler can handle is defined via the TagHandlerFactory’s OSGi property “tagpattern.name”. This OSGi property is essentially a regex that should match the input html tag you wish to handle. All the nested tags would be thrown to your tag handler for handling. For example if you register for a div that contains a nested <p> tag, the <p> tag would also be thrown to your TagHandler and it’s up to you how you wish to take care of it.

The tag handler interface is similar to a SAX content handler interface. It receives SAX events for each html tag. As a tag handler provider, you need to implement certain lifecycle methods which are automatically called by the design importer framework.

your tag handler factory must expose an OSGi property called “tagpattern.name” the value of which is matched against the input html tag.

If there are multiple tag handlers matching the input html tag, the one with a higher ranking is picked. The ranking itself is exposed as an OSGi property service.ranking.

The TagHandlerFactory is an OSGi component. Any references that you wish to provide to your TagHandler must be via this factory.

3. Make sure that your TagHandlerFactory has a better ranking if you wish to override the default.

Preparing the HTML for Import

After you have created an importer page, you can import your full HTML landing page. To import your HTML landing page, you need to first zip its contents into a design package. The design package contains your HTML landing page along with the referenced assets (images, css, icons, scripts, and so on).

The following cheat sheet provides a sample for how to prepare your HTML for import:

At a minimum, the design package must contain an index.html file at the root level. In case the landing page to be imported has a mobile version as well, then the zip must contain a mobile.index.html along with index.html at the root level.

Preparing the Landing Page HTML

To be able to import the HTML, you need to add a canvas div to the landing page HTML.

The canvas div is an html div with id="cqcanvas" that must be inserted within the HTML <body> tag and must wrap the content intended for conversion.

A sample snippet of the landing page HTML after addition of the canvas div is as follows:

Preparing the HTML to include editable AEM components

When you import a landing page, you have the choice to import the page as-is, which means that after the landing page is imported you cannot edit any of the imported items in AEM (you can still add additional AEM components on the page).

Before you import the landing page, you may want to convert some of the parts of the landing page so that they are editable AEM components. This allows you to quickly edit parts of the landing page even after the landing page design has been imported.

You do this by adding the data-cq-component to the appropriate component in the HTML file that you import.

The following section describes how to edit your HTML file so that you convert certain parts of your landing pages into different editable AEM components. Components are described in detail at Landing Pages Components.

Pastaba:

HTML markup to convert parts of the landing page into AEM components have both a long form and a shorthand tag declaration. Both are described for each component.

Limitations

Before importing, please note the following limitations:

Any attribute like class or id applied on the <body> tag is not preserved

If any attribute like id or class is applied on the body tag for example <body id="container"> then it is not preserved after the import. So the design being imported should not have any dependencies on the attributes applied on the <body> tag.

Drag and Drop zip

Drag/Drop zip upload is not supported for Internet Explorer and Firefox versions 3.6 and earlier. To upload a design when using these browsers, click the drop file zone to open up a file upload dialog box and upload your design using that dialog.

The browsers that support "drag and drop" of the design zip are Chrome, Safari5.x, Firefox 4 and above.

Modernizr is not supported

Modernizr.js is a javascript based tool that detects native capabilities of browsers and detects if they are suited for html5 elements or not. Designs that use Modernizr for enhancing support in older versions of different browsers can cause import issues in the landing page solution. Modernizr.js scripts are not supported with the Design importer.

Page properties are not preserved at the time of importing design package

Any page property (e.g. Custom Domain, Enforcing HTTPS, etc.) set for a page (that uses Blank Landing Page template) prior to importing the design package are lost after the design has been imported. Therefore, the recommended practice is to set the page properties after importing the design package.

Text

HTML markup to insert a text component (foundation/components/text) in the HTML within design package:

But otherwise, absolute URL images are supported for img tags that are not part of Image Component div.

Call-to-action components

You can mark part of landing page for importing as an "editable Call to action component" - such imported call-to-action components can be edited after importing the landing page. AEM includes the following CTA components:

Click Through Link - Lets you add a text link that when clicked takes the visitor to a target URL.

Graphical Link - Lets you add an image that when clicked takes the visitor to a target URL.

Click Through Link

This CTA component can be used to add a text link on the landing page.

Supported properties

Label, with bold, italics and underline options

Target URL, supports third party and AEM url

Page rendering options (same window, new window etc..)

HTML tag to include click through component in the imported zip. Here href maps to target url, "View Product Details" maps to label and so on.

Graphical Link

This CTA component can be used to add any graphical image with link on the landing page. The image can be a simple button or any graphical image as background. When the image is clicked, the user will be taken to the target URL specified in the component properties. It is a part of "Call to Action" group.

Supported properties

Image cropping, rotation

Hover text, description, size in px

Target URL, supports third party and AEM url

Page rendering options (same window, new window etc..)

HTML tag to include graphical link component in the imported zip. Here href will map to target url, img src will be the rendering image, "title" will be taken as hover text and so on.

Lead Form

A lead form is a form that is used to collect a visitor/lead's profile information. This information can be stored and used later to do an effective marketing based on the information. This information generally include title, name, email, date of birth, address, interest, and so on. It is a part of "CTA Lead form" group.

With the help of these components author can design a standalone lead form, these fields corresponds to lead form fields. In standalone or imported zip application user can add extra fields using cq:form or cta lead form fields, name and design them according to the requirements.

Map lead form fields using specific pre-defined names of CTA lead form, for example – firstName for first-name in lead form, and so on.

Fields that are not mapped to lead form will map to cq:form components - text, radio, checkbox, dropdown, hidden, password.

User can provide the title using “label” tag and can provide styling by using style attribute “class” (only available for CTA lead form components).

Thank You page and subcription list can be provided as a hidden parameter of the form (present in the index.htm) or can be added/edited from edit bar of “Start of lead form”
<input type="hidden" name="redirectUrl" value="/content/geometrixx-outdoors/en/user/register/thank_you"/>
<input type="hidden" name="groupName" value="leadForm"/>

Constraints like – required can be provided from edit configuration of each of the component.

HTML tag to include graphical link component in the imported zip. Here "firstName" is mapped to lead form firstName and so on, except for checkboxes - these two check boxes map to cq:form dropdown component.

Parsys

The AEM parsys component is a container component that can contain other AEM components. It's possible to add a parsys component in the imported HTML. This allows the user to add/delete editable AEM components to the landing page even after it has been imported.

The paragraph system gives users the ability to add components using the sidekick.

HTML markup to insert a parsys component (foundation/components/parsys) in the HTML within design package:

Inserts a AEM parsys component (foundation/components/parsys) in the landing page created after importing the design package.

Initializes the sidekick with default components. New components can be added to the landing page by dragging components from the sidekick onto the parsys component.

Two title components are also part of the parsys.

Target

The target component shows the contents of an experience on the page. One can have many experiences created in a campaign and the target component can dynamically show content from different experiences to various users visiting the page.

The html markup to insert a target component and also create different experiences in a campaign:

Overlaying template

Referring a component from Landing page

Suppose you have a component which you want to reference in your HTML using data-cq-component attribute such that the design importer renders a component include at this place. e.g., you want to reference the table component (resourceType = /libs/foundation/components/table). Following needs to be added in the HTML:

Configuring OSGI modules

The components that expose properties configurable via OSGI console are as follows:

Landing Page Design Importer

Landing Page Builder

Mobile Landing Page Builder

Landing Page Entry Preprocessor

The below table briefly describes the properties:

Component

Property Name

Property Description

Landing Page Design Importer

Extract Filter

The list of regular expressions to be used for filtering files from extraction.
Zip entries matching any of the specified patterns are excluded from extraction

Landing Page Builder

File Pattern

The Landing Page Builder can be configured to handle HTML files matching a regular expression as defined by file pattern.

Mobile Landing Page Builder

File Pattern

The Landing Page Builder can be configured to handle HTML files matching a regular expression as defined by file pattern.

Device Groups

The list of device groups to be supported.

Landing Page Entry Preprocessor

Search Pattern

The pattern to search for, in the archive entry contents. This regular expression is matched with the entry content line by line. Upon match, the matching text is replaced with the replacement pattern specified.

The pattern that replaces the matches found. You may use regex group references like $1, $2. Additionally, this pattern supports keywords like {designPath} that get resolved with the actual value during import.

Pastaba:

Current limitation of Landing Page Entry Preprocessor:
If you need to make any changes to the search pattern, when you open the felix property editor, you need to manually add backslash characters to escape the regex metacharacters. If you do not manually add backslash characters, the regex is considered invalid and will not replace the older one.

For example, if the default configuration is

/\* *CQ_DESIGN_PATH *\*/ *(['"])

And you need to replace CQ_DESIGN_PATH with VIPURL in the search pattern, then your search pattern should look like this:

/\* *VIPURL *\*/ *(['"])

Troubleshooting

When importing the design package, you may encounter several errors, described in this section.

Initialization of sidekick with Landing Page relevant components

If the design package contains a parsys component markup, then after importing, the sidekick starts showing landing-page relevant components. You can drag and drop new components onto the parsys component within your landing page. You can also go to the design mode and add new components to the sidekick.

Error messages displayed during import

In case of any errors (e.g. the imported package is not a valid zip), the design import will not import the package and instead display an error message on top of the page just above the drag and drop box. Examples of error scenarios are stated here. After correcting the error, you can re-import the updated zip onto the same blank landing page. Different scenarios where errors are thrown are as follows:

Imported design package is not a valid zip archive.

Imported design package does not contain an index.html at the top level.

Warnings displayed after import

In case of any warnings (e.g. HTML refers to images that do not exist within the package), the design importer will import the zip but at the same time display a list of issues/warnings on the Result Pane, Clicking on the issues link, will display a list of warnings which point out any issues within the design package. Different scenarios where warnings are caught and displayed by design importer are as follows:

HTML refers to images that do not exist within the package.

HTML refers to scripts that do not exist within the package.

HTML refers to styles that do not exist within the package.

Where are the files of the ZIP file being stored in AEM?

After the landing page has been imported, the files (images, css, js, etc.) within the design package are stored in the following location in AEM:

/etc/designs/default/canvas/content/campaigns/<name of brand>/<name of campaign>/<name of landing page>

Suppose the landing page is created under the campaign geometrixx and the name of the landing page is myBlankLandingPage then the location were Zip files are stored is as follows:

Then box img is used in the design importer, the resulting landing page appears not have preserved the formatting. To work around this, be aware that AEM adds div tags in the CSS and rewrite code accordingly. Otherwise, some CSS rules will be invalid.