com.day.cq.wcm.designimporter.api

Interface CanvasBuilder

public interface CanvasBuilder

Defines contract for building a canvas from a raw HTML document stream.

The CanvasBuilder is responsible for building a canvas component tree, along with the top level canvas component script as well as the design and clientlibs. A CanvasBuilder builds canvas artifacts for one html document. If a design package contains multiple importable html documents, multiple CanvasBuilders hook in to accomplish import.

The CanvasBuilder should dispatch appropriate events during major events of its lifetime. These events, listed as they appear in order, are tabulated as follows:

Event	Description
EVENT_STARTING	Dispatched before the CanvasBuilder begins building. May be used for any pre-processing
EVENT_PARSE_COMPLETE	Dispatched when the html document stream has been successfully parsed.
EVENT_COMPONENT_TREE_BUILT	Dispatched after the canvas component tree has been persisted to the repository
EVENT_CANVAS_SCRIPT_BUILT	Dispatched after the canvas component script has been generated and persisted successfully
EVENT_COMPLETE	Marks the completion of canvas building.

The bundled implementation of the CanvasBuilder also attaches contextual information to the above events. This information comes handy to find various state parameters and process accordingly.

The contextual information is sent in form of event payload, accessible via org.osgi.service.event.Event#getProperty(String). The below table enlists various event properties along with their type, description and the events the payload is available with.

Property	Type	Description	Available
designImporterContext	DesignImporterContext	The design importer context associated with the canvas build operation	ALL
parseResult	ParseResult	Encapsulates the result of html document parsing. Can be used to access the markup formed and/or cq components culled	EVENT_PARSE_COMPLETE and all events onward
canvas	Resource	The resource representing the root of the canvas component tree built	EVENT_COMPONENT_TREE_BUILT and all events onward

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	EVENT_CANVAS_SCRIPT_BUILT
static java.lang.String	EVENT_CLIENTLIBS_BUILT
static java.lang.String	EVENT_COMPLETE
static java.lang.String	EVENT_COMPONENT_TREE_BUILT
static java.lang.String	EVENT_PARSE_COMPLETE
static java.lang.String	EVENT_STARTING
static java.lang.String	PN_FILEPATTERN The name of the OSGi property that defines the name pattern of the HTML file that this CanvasPageBuilder is capable of translating.

Method Summary

Modifier and Type	Method and Description
void	build(java.io.InputStream htmlStream, DesignImporterContext designImporterContext) Builds the canvas for the input HTML document stream and the import context.
void	build(java.io.InputStream htmlStream, DesignImporterContext designImporterContext, CanvasBuildOptions buildOptions) Builds the canvas for the input HTML document stream and the import context.

Field Detail

EVENT_STARTING

static final java.lang.String EVENT_STARTING

See Also:

Constant Field Values

EVENT_PARSE_COMPLETE

static final java.lang.String EVENT_PARSE_COMPLETE

See Also:

Constant Field Values

EVENT_COMPONENT_TREE_BUILT

static final java.lang.String EVENT_COMPONENT_TREE_BUILT

See Also:

Constant Field Values

EVENT_CANVAS_SCRIPT_BUILT

static final java.lang.String EVENT_CANVAS_SCRIPT_BUILT

See Also:

Constant Field Values

EVENT_CLIENTLIBS_BUILT

static final java.lang.String EVENT_CLIENTLIBS_BUILT

See Also:

Constant Field Values

EVENT_COMPLETE

static final java.lang.String EVENT_COMPLETE

See Also:

Constant Field Values

PN_FILEPATTERN

static final java.lang.String PN_FILEPATTERN

The name of the OSGi property that defines the name pattern of the HTML file that this CanvasPageBuilder is capable of translating.

See Also:

Constant Field Values

Method Detail

build

void build(java.io.InputStream htmlStream,
           DesignImporterContext designImporterContext)
    throws RepositoryException,
           DesignImportException

Builds the canvas for the input HTML document stream and the import context.

Parameters:

htmlStream - The InputStream representing the the HTML document that needs to be translated to CQ Page

designImporterContext - The context associated with the design package import request

Throws:

RepositoryException - When an exception occurs while writing to the repository

DesignImportException - When an import exception occurs

build

void build(java.io.InputStream htmlStream,
           DesignImporterContext designImporterContext,
           CanvasBuildOptions buildOptions)
    throws RepositoryException,
           DesignImportException

Builds the canvas for the input HTML document stream and the import context.

Parameters:

htmlStream - The InputStream representing the the HTML document that needs to be translated to CQ Page

designImporterContext - The context associated with the design package import request

buildOptions - Set of option flags to control the way the page(and everything around it) is built

Throws:

RepositoryException - When an exception occurs while writing to the repository

DesignImportException - When an import exception occurs