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.

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.

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.

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.

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.


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:

  1. 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>
  2. In the constructor arguments for your StoreFactory bean, set isAuthoring to true.

    <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>			 
  3. 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 in WEB-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.

To change the preview link service:

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.

  1. Navigate to the Application SettingsPreview Settings tool.

  2. 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.

  3. To change the default preview application follow these steps:

  4. To update the preview URLs and link service URLs for a site follow these steps:

  5. Click Save.

  6. 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.

    The following table shows example preview settings by device.

  7. Click Save.


Copyright © Legal Notices