com.day.cq.wcm.designimporter

Class DesignPackageImporter

java.lang.Object

com.day.cq.wcm.designimporter.DesignPackageImporter

@Service(value=DesignPackageImporter.class)
public class DesignPackageImporter
extends java.lang.Object

Provides API for importing a design package. The entry service for the design importer functionality.

A design package is an archived HTML project containing an HTML file along with several (optional) referenced scripts and styles. This class provides API for importing that design package under a CQ page or component.

See Also:

CanvasBuilder

Constructor Summary

Constructors

Constructor and Description
DesignPackageImporter()

Method Summary

Modifier and Type	Method and Description
DesignImportResult	importDesignPackage(Page importerPage, java.lang.String designPackagePath, CanvasBuildOptions buildOptions) Imports a design package, similarly to importDesignPackage(org.apache.sling.api.SlingHttpServletRequest, com.day.cq.wcm.designimporter.CanvasBuildOptions), but with a different set of parameters.
DesignImportResult	importDesignPackage(SlingHttpServletRequest slingHttpServletRequest) Imports a design package from a sling request.
DesignImportResult	importDesignPackage(SlingHttpServletRequest slingHttpServletRequest, CanvasBuildOptions buildOptions) Imports a design package from a sling request similar to how importDesignPackage(org.apache.sling.api.SlingHttpServletRequest) imports, the difference being the amount of control you've over various building options.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DesignPackageImporter

public DesignPackageImporter()

Method Detail

importDesignPackage

public DesignImportResult importDesignPackage(SlingHttpServletRequest slingHttpServletRequest)
                                       throws DesignImportException

Imports a design package from a sling request.

A design package is typically imported by dropping a design package onto the designimporter component, which in turn POSTs the file to CQ server. This API serves as the starting point for import of the design package from the POST sling request. The POST request contains the uploaded file stream as a request parameter named "designfile".

The design package is expected to be a conforming HTML project with a "defined" structure. At the minimum, the project must contain the HTML file with the name index.html or index.htm at the root (This rule is configurable via CanvasBuilder OSGi component configuration). This is the only conformance required. Authors are free to choose any project structure or file/directory naming conventions as per their wishes. The importer works by fully parsing the HTML document and not by relying upon certain naming conventions.

The import process involves the following steps:

1. The design package is unloaded at a unique location under /etc/designs. This design path is translated from the CQ page initiating the request
2. The unloaded files are looked up for HTML files. Appropriate CanvasBuilder service implementation that is registered to handle the HTML of that name pattern is executed
3. The CanvasBuilder builds the CQ page by parsing the HTML file as following:
   1. It parses the HTML document and culls out CQ components, scripts, styles and other relevant meta information
   2. It builds the page component nodes for the CQ components extracted
   3. It aggregates the extracted scripts and styles into CQ clientlibs
   4. It generates a top level canvas component that contains the reference to all the extracted CQ components as well as the clientlibs

If a more controlled building is required, consider using the importDesignPackage(org.apache.sling.api.SlingHttpServletRequest, CanvasBuildOptions) API instead.

Parameters:

slingHttpServletRequest - The sling request for importing the design package. A design package is an archived HTML project containing the main HTML file along with all the referenced scripts, styles and assets. By default, the main HTML file should be named index.html and appear at the root level of the zip archive. The rule can however be modified via CanvasBuilder configuration. *

Returns:

DesignImportResult The object encapsulating the warnings ,if they arose, during the import process

Throws:

MalformedArchiveException - if there is an error reading the input archive stream

MissingHTMLException - if there is no index.html or index.htm entry in the zip archive

UnsupportedTagContentException - if unsupported content is encountered within a tag

MissingCanvasException - if the input HTML stream is missing the canvas boundary

DesignImportException - if there is an exception writing to the CRX repository

importDesignPackage

public DesignImportResult importDesignPackage(SlingHttpServletRequest slingHttpServletRequest,
                                              CanvasBuildOptions buildOptions)
                                       throws DesignImportException

Imports a design package from a sling request similar to how importDesignPackage(org.apache.sling.api.SlingHttpServletRequest) imports, the difference being the amount of control you've over various building options.

This api lets you have control over what you want to build by providing build flags specified via CanvasBuildOptions. You can choose to switch on or off, the building of canvas nodes, canvas component and clientlibs. With clientlibs, you can further choose to switch on or off, the building of head scripts, head styles, body scripts, body styles or a combination of some of those

Parameters:

slingHttpServletRequest - Contains http request and input stream of the design package. Design package is a zipped HTML project containing the main HTML file along with all the referenced scripts, styles and assets. By default, the main HTML file should be named index.html and appear at the root level of the zip archive. The rule can however be modified via CanvasBuilder OSGi configuration.

buildOptions - The CanvasBuildOptions object that contains build flags for switching on or off certain build options

Returns:

DesignImportResult The object encapsulating the warnings ,if they arose, during the import process

Throws:

MalformedArchiveException - if there is an error reading the input archive stream

MissingHTMLException - if there is no index.html or index.htm entry in the zip archive

UnsupportedTagContentException - if unsupported content is encountered within a tag

MissingCanvasException - if the input HTML stream is missing the canvas boundary

DesignImportException - if there is an exception writing to the CRX repository

importDesignPackage

public DesignImportResult importDesignPackage(Page importerPage,
                                              java.lang.String designPackagePath,
                                              CanvasBuildOptions buildOptions)
                                       throws DesignImportException

Imports a design package, similarly to importDesignPackage(org.apache.sling.api.SlingHttpServletRequest, com.day.cq.wcm.designimporter.CanvasBuildOptions), but with a different set of parameters.

Parameters:

importerPage - An existing page of template type "wcm/designimporter/templates/importerpage"

designPackagePath - The absolute path to a design package zip file in the repository

buildOptions - The CanvasBuildOptions object that contains build flags for switching on or off certain build options

Returns:

DesignImportResult The object encapsulating the warnings ,if they arose, during the import process

Throws:

MalformedArchiveException - if there is an error reading the input archive stream

MissingHTMLException - if there is no index.html or index.htm entry in the zip archive

UnsupportedTagContentException - if unsupported content is encountered within a tag

MissingCanvasException - if the input HTML stream is missing the canvas boundary

DesignImportException - if there is an exception writing to the CRX repository