If you are using Experience Manager, you can use a preview application to simulate sets of trigger conditions, such as time-based triggers, in order to determine which content items are displayed when specific conditions are met. This section describes how to set up a custom application to function as the preview application in Workbench.
The preview application enables content administrators to determine whether each content item is or is not displayed by particular combinations of navigation queries and triggers. This chapter describes how to set up your own custom application as the Workbench preview application.
You can start the preview application for a specific page or for an individual cartridge. A selected cartridge is displayed in the context of a page that includes it.
The preview application does not need to be an exact representation of your final front-end application if it uses the correct data. The business logic that is built into Workbench is not tied to the physical representation of the front-end application. It is good practice, however, to make sure that your preview application represents your final application closely enough to enable business users to verify that their changes are correct.
By default, Workbench is configured to use the Discover Electronics
reference application as the preview application. This application is located
under
%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring
($ENDECA_TOOLS_ROOT/reference/discover-electronics-authoring
on UNIX).
Workbench communicates with the preview application via settings you specify in the Preview Settings tool. The Preview URL field lets you specify the preview application URL.
Note
The preview application must not use frames, because they are likely to collide with the frames of the Workbench preview toolbar.
In order to enable auditing and editing in your custom preview application, your JSP file rendering code must include logic for adding preview frames and buttons for auditing and editing content items.
Your custom preview application should include tags that specify paths to the required JavaScript and CSS resources, as well as tags for enabling audit and edit functionality. These are provided in the tag library.
These requirements assume an application that uses JSP files for cartridge renderers (as in the case of the Discover Electronics reference application). If you are using a different technology stack to implement your Assembler application, you must write your own auditing functionality. See Enabling non-Java applications for preview.
All JSP files must include the tag library, as shown below:
<%@ taglib prefix="endeca" uri="/endeca-infront-assembler/utilityTags"%>
Each
<head>
tag must contain a reference to the
pageHead
tag. This includes paths to the Preview
JavaScript and CCS files:
<head>
<endeca:pageHead rootContentItem="${rootComponent}"/>
<title><c:out value="${component.title}"/></title>
<meta name="keywords" content="${component.metaKeywords}" />
<meta name="description" content="${component.metaDescription}" />
</head>
All slots and content items must include a
PreviewAnchor
tag that wraps them in a div class that
contains preview information. This tag requires the current content item
element and enables audit and edit functionality. Oracle recommends that
instead of including this in every renderer, have a centralized place where
content items are dispatched. In the Discover reference application, this is
done in the
include.tag
:
<%-- save the parent's component currently in request scope into page scope --%>
<c:set var="parentComponent" scope="page" value="${requestScope['component']}"/>
<%-- set the content item the child will use as this one (the one passed in the tag) --%>
<c:set var="component" scope="request" value="${component}"/>
<c:catch var="importException">
<endeca:previewAnchor contentItem="${component}">
<c:import url="${resourcePath}" charEncoding="UTF-8"/>
</endeca:previewAnchor>
</c:catch>
Each
<body>
tag must contain a reference to the
pageBody
tag. This tag requires the root and current
content item elements and enables audit and edit functionality:
<script type="text/javascript" src="<c:url value='/js/global.js'/>"></script>
</head>
<body>
<endeca:pageBody rootContentItem="${rootComponent}" contentItem="${component}">
<div class="PageContent">
<%--include user panel --%>
<%@ include file="/WEB-INF/views/userPanel.jsp" %>
In order to handle preview for different devices, you must implement conditional rendering logic for different user agent strings. The rendering code should include the tags described in the previous section.
You can retrieve the user agent String by getting a reference to the
UserState
object and calling
getUserAgent()
on it. The
UserState
class is documented in the Javadoc for the
com.endeca.infront.content
package.
For example, the Discover Electronics reference application includes
the following logic in the
WEB-INF\services\assemble.jsp
page:
UserState userState = webappCtx.getBean(properties.getProperty("user.state.ref"), UserState.class);
String userAgent = userState.getUserAgent();
//If the userAgent is null, then no user-agent was specified and we need to get the user agent from the request header.
if(userAgent == null){
userAgent = request.getHeader("user-agent");
}
Preview requires a request attribute to decorate the page. For
example, the Discover Electronics reference application includes the following
logic in the
WEB-INF\services\assemble.jsp
page. The last line
retrieves the value of the
preview.enabled
property from the
assembler.properties
file. The value of the constant
PreviewAnchor.ENDECA_PREVIEW_ENABLED
is
endeca:previewAnchorsEnabled
.
//If the userState has no specified userAgent, use the one from the request header.
if(userAgent == null){
userAgent = request.getHeader("user-agent");
}
request.setAttribute(PreviewAnchor.ENDECA_PREVIEW_ENABLED, Boolean.valueOf(properties.getProperty("preview.enabled")));
########################################################
This section describes how to enable hotspots in any Assembler-based Web application that lets a user audit and edit cartridges and slots in Experience Manager.
The preview JavaScript framework should be added to the Assembler application's Web pages to enable this behavior. The framework supports single page applications (SPAs) and the popular module loader RequireJS. Note that the framework depends on the open source JQuery library. If your application already uses a JQuery version higher than 1.9, and if its available on the window object, you do not have to include the JQuery version provided by Oracle Commerce.
Include the following style sheet in the head of your page:
<link rel="stylesheet" href="http://@@WORKBENCH_HOST@@:@@WORKBENCH_PORT/ifcr/tools/xmgr/app/preview/css/audit-site.css" />
If you do not use an AMD module loader, include the following scripts in the head tag of the page or at the bottom of the body tag - depending on your script loading strategy.
<!-- You can skip inclusion of the following two scripts if your web app already uses jquery version higher than 1.9. If not, make sure jquery is loaded before loading the preview script --> <script type="text/javascript" src="http://@@WORKBENCH_HOST@@:@@WORKBENCH_PORT/ifcr/static/oraclejet/js/libs/jquery/jquery-2.1.1.min.js"></script> <script type="text/javascript"> ocJQuery = jQuery.noConflict(true); </script> <!-- Oracle commerce preview framework that enables hotspots in a web page --> <script type="text/javascript" src="http://@@WORKBENCH_HOST@@:@@WORKBENCH_PORT/ifcr/tools/xmgr/app/preview/js/preview.js"></script>
<script type="text/javascript"> requirejs.config({ paths: { jquery: "/ifcr/static/oraclejet/js/libs/jquery/jquery-2.1.1.min", xmgrPreview: "/ifcr/tools/xmgr/app/preview/js/preview" } }); </script>
When you develop your application, you must pass the assembled content item (tree) returned by the Assembler to the preview framework to support editing and auditing a Web page from within Experience Manager. The content-item is used by Experience Manager to construct the manifest panel. Optionally, preview framework can add hotspots to slots and cartridges in the page by looking at the data-oc-content-item-id attribute on all DOM elements in the page.
You initialize the preview framework by calling the
initialize()
method and passing it the assembled
content item returned by the Assembler. You can instead pass the content-uri
that was used to invoke the Assembler service. In this case, the framework
makes a
jsonp
call to retrieve the content item. Be sure that
the
Assembler Service URL is set in
Preview Settings in Workbench.
The framework provides an
eventing mechanism to let application developers hook into
its life cycle. The available events are
hotspotsOn
,
hotspotsOff
,
addContentItem
, and
removeContentItem
. For example, in order to be
notified when the framework decorates the content items with hotspots, use:
framework.on("hotspotsOn", function() { // your code }, this);
The following preview framework API lists all the public methods and events. The API enables Assembler application pages to be decorated with hotspots when a business user previews pages in Experience Manager. The API must be used to enable Experience Manager to construct the manifest panel. The manifest panel assists the user in understanding how the page was assembled and allows the user to audit or edit slots and cartridges.
Adds data-oc-content-item-id attribute to the DOM element. All elements that should be decorated with hot spots must call this method.
Name |
Type |
Description |
---|---|---|
pElement |
Object |
Required. The DOM element that is injected with data-oc-content-item-id attribute. The element maps to the content item: slot or cartridge. |
pContentItem |
Object |
Required. The content item that represents a slot or cartridge. Example: { @type: "SearchBox", endeca:auditInfo: { "ecr:resourcePath": "/content/Web/Categories/Pages/Category - Bags - Cases", "ecr:assertedFacts": { "endeca:ancestorDimValId:100972", "endeca:ancestorDimValId:101022", "endeca:ancestorDimValId:101024", "101927", "endeca:ancestorDimValId:20001", "4294967266", "4294967247" ], "endeca:navAndSearchCount": [ "3" ], "endeca:time": [ "1441745067199" ], "endeca:workspaceId": [ "d826ca36-80a2-4278-a09f-2933dab92d1f" ], "endeca:path": [ "/content/Web" ], "endeca:templateType": [ "Page" ], "endeca:templateId": [ "" ], "endeca:workflowState": [ "1" ] }, ecr:innerPath: "headerContent[0]" }, name: "Search Box", contentPaths: ["/content/Shared/Auto-Suggest Panels"], templateTypes: ["AutoSuggestPanel"], templateIds: [ ], minAutoSuggestInputLength: "3", ruleLimit: "1" }
|
Initializes the preview framework, processes the content item tree and opens up a communication channel with Experience Manager. If Experience Manager responds with a load hot spots message, the framework traverses the application DOM and decorates the page with hot spots. This method should be invoked at the beginning of the page construction. Single page applications should use the addContentItemId() method to add data-oc-content-item-id attribute to the DOM elements that should be decorated with hotspots and then call addHotspots() to decorate the content items with hot spots.
Name |
Type |
Description |
---|---|---|
pContentItem |
Object/ String |
Required. The assembled content item tree that was returned by the Assembler's JSON serializer. This can also be set as a string that represents the content uri that was passed to the Assembler service. Example: { @type: "TwoColumnPage", endeca:auditInfo: { ecr:resourcePath: "/pages/DiscoverElectronics/about us" "ecr:assertedFacts": { "endeca:ancestorDimValId:100972", "endeca:ancestorDimValId:101022", "endeca:ancestorDimValId:101024", "101927", "endeca:ancestorDimValId:20001", "4294967266", "4294967247" ], "endeca:navAndSearchCount": [ "3" ], "endeca:time": [ "1441745067199" ], "endeca:workspaceId": [ "d826ca36-80a2-4278-a09f-2933dab92d1f" ], "endeca:path": [ "/content/Web" ], "endeca:templateType": [ "Page" ], "endeca:templateId": [ "" ], "endeca:workflowState": [ "1" ] }, }, name: "About Page", headerContent: [ { @type: "SearchBox", endeca:auditInfo: { "ecr:resourcePath": "/pages/DiscoverElectronics/about us", "ecr:assertedFacts": { "endeca:ancestorDimValId:100972", "endeca:ancestorDimValId:101022", "endeca:ancestorDimValId:101024", "101927", "endeca:ancestorDimValId:20001", "4294967266", "4294967247" ], "endeca:navAndSearchCount": [ "3" ], "endeca:time": [ "1441745067199" ], "endeca:workspaceId": [ "d826ca36-80a2-4278-a09f-2933dab92d1f" ], "endeca:path": [ "/content/Web" ], "endeca:templateType": [ "Page" ], "endeca:templateId": [ "" ], "endeca:workflowState": [ "1" ] } ecr:innerPath: "headerContent[0]" }, name: "Search Box", contentPaths: [ "/content/Shared/Auto-Suggest Panels" ], templateTypes: [ "AutoSuggestPanel" ], templateIds: [ ] } ], endeca:siteState: { @class: "com.endeca.infront.site.model.SiteState", contentPath: "/about-us", siteId: "/DiscoverElectronics", siteDisplayName: "Discover Electronics" } }
|
pCallback |
Function |
Optional. The callback that is invoked after the framework is initialized. Always use the callback if the content uri is passed as the first argument. This ensures that the framework has been initialized. |
Add the given content item tree to the Manifest. Optionally turns on hot spots for the dynamically generated DOM element and its descendants - elements with the data-oc-content-item-id attribute which visually represent the content item tree. Information about the parent content item is needed in order to add it to the correct location in the page components area. Page components are uniquely identified by their resourcePath and innerPath information. This information can be found in the parent DOM element's data-oc-content-item-id attribute. If there is no parent DOM element, the content item will be added to the end of the page components tree in the Manifest.
An example of this method can be found in the
SearchBox.jsp
page in the Discover Electronics
application. The parent search box DOM element is passed so that the auto
suggest results cartridge is added to the correct location in the page
components tree.
This method should be invoked to add dynamic content item trees, such as auto suggest, that are returned by the Assembler after a page has been constructed.
Name |
Type |
Description |
---|---|---|
pContentItem |
Object |
Required. The new content item tree returned by the Assembler's JSON serializer. |
pElement |
Object |
Optional. The new DOM element with data-oc-content-item-id attribute. |
pParentElement |
Object |
Optional. The parent DOM element with data-oc-content-item-id attribute. Adds the content tree to the correct location in the page components area of the Manifest. |
Removes hot spots from the element and its descendants. The associated content item tree is removed from the page components area of the Manifest.
Name |
Type |
Description |
---|---|---|
pElement |
Object |
Required. The DOM element with the {@link CONTENT_ITEM_SELECTOR} attribute whose hot spots and associated content item tree are to be removed. |
Decorates the element and optionally its descendants with hot spots. An error occurs if the preview framework has not been prepared yet. You must call the framework's prepare() method before using this method.
Name |
Type |
Description |
---|---|---|
pElement |
Object |
Required. The DOM element that is to be decorated with hot spots. |
pTraverseDom |
Boolean |
Required. Flag indicating whether or not the descendants of the element have to be decorated. |
Removes hot spots from the element and optionally removes its descendants. An error occurs if the preview framework has not been prepared yet.
Name |
Type |
Descripton |
---|---|---|
pElement |
Object |
Required. The DOM element from which hot spots are to be removed. |
pTraverseDom |
Boolean |
Required. Flag indicating whether or not hot spots have to be removed from the descendants. |
After you have finished instrumenting your preview application, you can enable it for use in Workbench.
Ensure that your application has been correctly instrumented before enabling it for preview in Workbench. See Enabling your Java application for preview.
All examples shown below are taken from the configuration files for
the Discover Electronics authoring application, located in
%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring
(on Windows) or
$ENDECA_TOOLS_ROOT/reference/discover-electronics-authoring
(on UNIX). The exact mechanisms used for configuring your Assembler and content
sources will depend on your implementation details.
For a full description of the properties described below, see the
Assembler API Javadoc for the
AssemblerFactory
and
ContentSource
interfaces and their corresponding
implementations.
To enable your custom preview application:
In the constructor arguments for your
AssemblerSettings
, set the following:In the Discover Electronics reference implementation, these are configured as properties in
WEB-INF\assembler.properties
:workbench.host=localhost workbench.port=8006 # ... Additional settings removed from this example ... preview.enabled=true
These properties are then included in the Assembler context file,
WEB-INF\assembler-context.xml
:<!-- ######################################################################## # ASSEMBLER FACTORY # # Required. # --> <bean id="assemblerFactory" class="com.endeca.infront.assembler.spring.SpringAssemblerFactory" scope="singleton"> <constructor-arg> <bean class="com.endeca.infront.assembler.AssemblerSettings"> <property name="previewEnabled" value="${preview.enabled}" /> <property name="previewModuleUrl" value="http://${workbench.host}:${workbench.port}/ifcr" /> </bean> </constructor-arg> <constructor-arg> <list> <bean class="com.endeca.infront.logger.SLF4JAssemblerEventLogger" /> </list> </constructor-arg> </bean>
In the constructor arguments for your
StoreFactory
bean, setisAuthoring
totrue
.<bean id="StoreFactory" class="com.endeca.infront.content.source.FileStoreFactory" init-method="init" destroy-method="destroy"> <property name="configurationPath" value="${repository.configuration.path}"/> <property name="isAuthoring" value="${preview.enabled}"/> <property name="appName" value="${workbench.app.name}" /> <property name="host" value="${workbench.host}" /> <property name="clientPort" value="${workbench.publishing.clientPort}"/> <property name="serverPort" value="${workbench.publishing.serverPort}"/> <property name="messageTimeout" value="10000" /> </bean>
Property name Value configurationPath Required. The path from which the content and configuration zip files are retrieved appName Required. The name of the EAC application isAuthoring Optional. Default is false. If this is an authoring server, the value must be set to true. host Required if the isAuthoring
property is set to true. The name of the server the workbench is running on. Default is localhost..serverPort Optional. Used only when the isAuthoring
property is set to true. The port the Workbench is listening on. Default is 8007.clientPort Optional. Used only when the isAuthoring
property is set to true. The port used to initiate contact to the workbench from this server. If client port is set to -1, the system will assign an ephemeral port automatically.messageTimeout Optional. Used only when the isAuthoring
property is set to true. The amount of time in milliseconds to wait on communications with the workbench. Default is 10000ms.Configure a link service for your application that returns a preview link as a JSONP response.
This service must construct a link to the page selected for preview; for example, if a content administrator previews the Brand - Canon Web Browse page in the reference application, the service returns
"/browse/_/N-25y6"
. Additionally, the response from the service is used to construct the links in the Audit Panel.In Discover Electronics, the link service is configured as a link servlet that uses the
com.endeca.infront.web.spring.PreviewLinkServlet
class. The servlet is defined inWEB-INF\web.xml
:<servlet> <servlet-name>link</servlet-name> <servlet-class> com.endeca.infront.assembler.servlet.spring.SpringPreviewLinkServlet </servlet-class> <init-param> <description> The ID of the NavigationStateBuilder in the spring contextConfig file </description> <param-name>navigationStateBuilderBeanId</param-name> <param-value>navigationStateBuilder</param-value> </init-param> <init-param> <description> The ID of the MdexResource in the spring contextConfig file </description> <param-name>mdexResourceBeanId</param-name> <param-value>mdexResource</param-value> </init-param> </servlet>
If you have implemented your own link service for use with preview, you can specify the path to the service.
After you have created your own preview link service, you can specify it for use with preview instead of the default link service included with the Discover Electronics reference application.
Note
For information about the required inputs and outputs for a link
service, see the Javadoc for the
AbstractPreviewLinkServlet
class in the
com.endeca.infront.assembler.servlet
package.
To change the preview link service:
Open your application's deployment descriptor file,
web.xml
.For the Discover Electronics reference application, this file is located at
%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring\WEB-INF\web.xml
.The servlet definition for the Discover Electronics reference application is shown below:
<servlet> <servlet-name>link</servlet-name> <servlet-class> com.endeca.infront.assembler.servlet.spring.SpringPreviewLinkServlet </servlet-class> <init-param> <description> The ID of the NavigationStateBuilder in the spring contextConfig file </description> <param-name>navigationStateBuilderBeanId</param-name> <param-value>navigationStateBuilder</param-value> </init-param> <init-param> <description> The ID of the ContentSource in the spring contextConfig file </description> <param-name>contentSourceBeanId</param-name> <param-value>contentSource</param-value> </init-param> </servlet>
Define the link servlet mapping.
For example:
<servlet-mapping> <servlet-name>link</servlet-name> <url-pattern>/servlet/link.json/*</url-pattern> </servlet-mapping>
You can manage the preview URL configuration and the preview devices for an application in Workbench by using the Preview Settings tool.
After you have instrumented your application and it for preview, it becomes the default preview application for your initial site or any sites that you add to your application. You can manage preview devices for displaying content and change the default application preview URLs or site-specific preview URLs.
Navigate to the Preview URLs section.
The default preview URL that you set up in Enabling your preview application appears in the Default Preview URL field. The link service URL that you set up in Changing the preview link service appears in the Default Link Service URL field. The URL that exposes the Assembler Services REST API for non-Java applications appears in the Default Assembler Service URL field. These URLs also appear by default for the sites listed in the section below the default URLs section.
To change the default preview application follow these steps:
Enter the fully qualified preview URL of the default preview application in the Default Preview URL field.
Enter the URL of the service within the application that constructs links for preview in the Default Link Service URL.
Enter the URL that exposes the Assembler Services REST API for preview in the Default Assembler Service URL. This field is only required for non-Java applications. It is not required for Java applications. See Formatting the Assembler Service URL for more information.
To update the preview URLs and link service URLs for a site follow these steps:
In the Preview URL field of the site, enter the fully qualified preview URL of the site that you want to preview .
In the Link Service URL of the site, enter the URL of the service within the site that constructs links for preview.
If your organization has integrated Oracle Core Commerce Platform with Guided Search, you must include the
pushSite
parameter in the Link Service URL for each site:pushSite=<
. For example:siteID
>http://<PREVIEW_HOST>:<PREVIEW_PORT>/crs/link.json?pushSite=mobileHomeSite
In the Assembler Service URL of the site, URL that exposes the Assembler Services REST API for preview. This field is only required for non-Java applications. It is not required for Java applications.
In the Manage Preview Devices section, enter values for the attributes of each preview device.
All devices can be rotated, so enter the height and width of the page orientation that is previewed more frequently.
Option Description Name The name of the device User Agent Agent types supported as a string Height The view port height of the device, in pixels Width The view port width of the device, in pixels Zoom The Zoom factor can simulate displays on devices other than the current monitor. For example, the display on a retina display monitor can be simulated by setting the Zoom factor to 30 -- that is, 30%. The following table shows example preview settings by device.
Option
First Preview Device
Second Preview Device
Name
Handheld
Tablet
User Agent
Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A537a Safari/419.3
Mozilla/5.0 (iPad; U; CPU OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B334b Safari/531.21.10
Height
680
1224
Width
400
848
Zoom
30
60
At runtime, the Assembler Service URL is used to build the various URLs for individual content items in your site.
For example, if your site uses the following Assembler Service URL:
http://localhost:8006/assembler-authoring/json
The JSON for the
/browse
page can be retrieved by concatenating the path
at the end of the URL:
http://localhost:8006/assembler-authoring/json/browse
If the path is not appended at the end of the URL, you can also use a
placeholder
%s
to designate where the path should be
inserted at runtime. For example, to retrieve the following
/browse
page:
http://localhost:8006/discover-authoring/browse?format=json
You can format the Assembler Service URL with a placeholder:
http://localhost:8006/discover-authoring%s?format=json
Note that if you do not use a placeholder, the path is always appended to the end of the Assembler Service URL.
Experience Manager makes a JSONP call to the deployed Assembler Service by using the jsonp query parameter. For example, to construct the Manifest panel for the browse page, Experience Manager makes a call to the Assembler Service at the following:
http://localhost:8006/assembler-authoring/json/browse?jsonp=<dynamic_method_name>
After instrumenting and enabling your preview application, you can test the preview and audit functionality in Workbench.
Your custom preview application must be fully instrumented and enabled in Workbench in order for the preview option to be displayed.
To test your custom preview application:
Hove the mouse over the content item.
The Action menu button appears.
Optionally, specify the preview time instead of using the default indicated by the system clock for the MDEX Engine:
Specifying a preview device lets you see how the application renders on that device.
Click the gear button and select Audit
The Audit Panel appears with a list of all content items considered for the specified content slot.
Click any of the listed Locations to navigate to that location in the preview application.
Click the name of any of the listed content items and confirm that you return to that item in Experience Manager.
You can disable the ability to preview your application in Experience Manager.
To disable preview, you export the preview configuration of your application, replace the preview URL and link service URL with null values and then import your updated preview configuration, as follows:
Export the preview configuration.
The following command exports the Discover preview configuration to the
/import
folder in unzipped files:runcommand.sh IFCR exportContent configuration/tools/preview /localdisk/apps/Discover/config/import/configuration/tools/preview true
Replace the preview URL and link services URL information with null values in the configuration-preview JSON file.
{ "ecr:type":"configuration-preview", "linkServiceUrl":"", "previewUrl":"", "assemblerServiceURL":"http://localhost:8006//assembler-authoring/json", "devices": [ { "userAgent":"Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A537a Safari/419.3", "name":"Handheld (Portrait)", "height":1280, "width":960, "zoom":50 } ] }
Import the updated preview configuration.
The following command imports the Discover preview configuration to the
configuration/tools/preview
folder:runcommand.sh IFCR importContent configuration/tools/preview /localdisk/apps/Discover/config/import/configuration/tools/preview