Package com.day.cq.wcm.designimporter

Class DesignPackageImporter

  • @Service(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 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