Preview URI Service 2.2 to 3.1

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

{{AVMWarning}}
AVM2.23.03.1
Back to WCM Preview

Table of Contents

• 1 Preview URI Service Interface (2.2 to 3.1)


• 2 Preview URI Service Implementations
  
  
  
  • 2.1 VirtualisationServerPreviewURIService
  
  
  • 2.2 StoreSpecificPreviewURIService
  
  
  • 2.3 URITemplatePreviewURIService
    
    
    
    • 2.3.1 URI Template Variables
    
    
  
  
  • 2.4 NullPreviewURIService
  
  


• 3 Configuring the Preview URI Service
  
  
  
  • 3.1 Example Configuration
  
  


• 4 Developing a Custom Preview URI Service Implementation
  
  
  
  • 4.1 Sample Code
  
  

Preview URI Service Interface (2.2 to 3.1)

The org.alfresco.web.bean.wcm.preview.PreviewURIService interface was introduced in Alfresco Enterprise 2.2.2 and is also available in Alfresco 3.0.x, 3.1.x. For Alfresco Community 3.2 and higher, please refer to Preview URI Service

The Alfresco Explorer (JSF-based web client) uses a single Spring bean called 'PreviewURIService' to calculate all preview URIs in all Web Projects in the system.  This bean must implement the following Java interface:

package org.alfresco.web.bean.wcm.preview;

public interface PreviewURIService
{
    /**
     * @param storeId     The id of the store to generate the preview URI for.
     * @param pathToAsset The path to the asset to generate the preview URI for.
     * @return The Preview URI for the given store id and/or asset (may be null).
     */
    String getPreviewURI(String storeId, String pathToAsset);
}

Preview URI Service Implementations

4 implementations of this interface are provided with Alfresco WCM:

VirtualisationServerPreviewURIService

The class org.alfresco.web.bean.wcm.preview.VirtualisationServerPreviewURIService generates virtualisation server preview URIs and is primarily provided for backwards compatibility.

StoreSpecificPreviewURIService

The class org.alfresco.web.bean.wcm.preview.StoreSpecificPreviewURIService delegates to other PreviewURIService implementations based on the store that's being previewed.  This implementation should normally be used as the master 'PreviewURIService' Spring bean, to allow different preview schemes to be used for different Web Projects.  This is particularly important if new Web Projects are expected to be added to the system at a later date, but you're unsure as to which of the various WCM Preview mechanisms will be used for those Web Projects.

If the store being previewed doesn't appear in the list of configured PreviewURIServices, the VirtualisationServerPreviewURIService is used as the default.

URITemplatePreviewURIService

The class org.alfresco.web.bean.wcm.preview.URITemplatePreviewURIService uses a (configurable) URI template for generating preview URIs.  The template language is identical to the one used for Web Scripts - see Web Scripts#URL Templates for more details.

URI Template Variables

The URITemplatePreviewURIService currently recognises two parameters in URI templates:

1. {storeId} - the AVM store id of the sandbox being previewed eg. mywebproject--alice
   
2. {pathToAsset} - the root-relative path of the asset being previewed eg. /www/avm_webapps/ROOT/content/xml/press_releases/myPressRelease.xml
   

Note that both of these parameters are optional - if they're not found in the URI template the replacement value won't appear in the resulting preview URI.

NullPreviewURIService

The class org.alfresco.web.bean.wcm.preview.NullPreviewURIService generates no URI whatsoever.  This is useful for Web Projects where preview is disabled or disallowed for some reason.

Configuring the Preview URI Service

To ensure backwards compatibility, the Web Client uses an instance of the VirtualisationServicePreviewURIService as the default PreviewURIService.  You may override this behaviour by defining a new Spring bean in a custom *-context.xml file (as described at Repository Configuration) with the name 'PreviewURIService', using any class that implements the PreviewURIService interface.  For example if you wished to disable preview for an entire Alfresco WCM instance, you would create the following Spring configuration:

<beans>
  <bean id='PreviewURIService' class='org.alfresco.web.bean.wcm.preview.NullPreviewURIService'/>
</beans>

As mentioned above, what's recommended is that the StoreSpecificPreviewURIService be used as the master PreviewURIService instead, ensuring that you have the choice to vary the preview approach per Web Project.

Example Configuration

Here's an example demonstrating all 4 implementations being used across a set of 6 Web Projects:

<beans>
  <!-- Note that we use the StoreSpecificPreviewURIService as the 'master' PreviewURIService, allowing us to vary the preview mechanism by Web Project -->
  <bean id='PreviewURIService' class='org.alfresco.web.bean.wcm.preview.StoreSpecificPreviewURIService'>
    <constructor-arg index='0'>
      <list>

        <!-- PreviewURIService for 'test' Web Project - uses a URI template -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='test.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.URITemplatePreviewURIService'>
              <constructor-arg index='0' value='http://stage.someothercompany.com{pathToAsset}?storeId={storeId}' />
            </bean>
          </constructor-arg>
        </bean>

        <!-- PreviewURIService for 'mywebapp' Web Project - uses a different URI template -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='mywebapp.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.URITemplatePreviewURIService'>
              <constructor-arg index='0' value='http://preview.acme.com:8080/mywebapp/content/{storeId}{pathToAsset}' />
            </bean>
          </constructor-arg>
        </bean>

        <!-- PreviewURIService for 'anotherwebapp' Web Project - uses the default virtualisation server preview -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='anotherwebapp.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.VirtualisationServerPreviewURIService' />
          </constructor-arg>
        </bean>

        <!-- PreviewURIService for 'someotherwebapp' Web Project - doesn't support preview at all -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='someotherwebapp.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.NullPreviewURIService' />
          </constructor-arg>
        </bean>

        <!-- PreviewURIService for 'yetanotherwebapp' Web Project - doesn't support preview at all -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='yetanotherwebapp.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.NullPreviewURIService' />
          </constructor-arg>
        </bean>

        <!-- PreviewURIService for 'thelastwebapp' Web Project - uses a third URI template -->
        <bean class='org.alfresco.util.Pair'>
          <constructor-arg index='0' value='thelastwebapp.*' />
          <constructor-arg index='1'>
            <bean class='org.alfresco.web.bean.wcm.preview.URITemplatePreviewURIService'>
              <constructor-arg index='0' value='http://qa.goodies.com:8080/preview?storeId={storeId}&amp;asset={pathToAsset}' />
            </bean>
          </constructor-arg>
        </bean>
      </list>
    </constructor-arg>
  </bean>
</beans>

Note in particular the use of the StoreSpecificPreviewURIService to enable Web Project specific behaviour, and the use of multiple URITemplatePreviewURIService's with different URI templates in each case.

Developing a Custom Preview URI Service Implementation

Implementing a custom PreviewURIService requires a working knowledge of Java development, as well as an Alfresco SVN Development Environment.  You should also be familiar with how Alfresco code extensions are packaged (ie. as AMP Files) and deployed (ie. via the Module Management Tool).

If you're familiar with Java you should find implementing a custom PreviewURIService straight forward, given the simplicity of the interface.

Sample Code

The following sample implementation shows how you might strip out the 'synthetic' directories that get added to the start of every asset in a Web Project:

public class CustomPreviewURIService
    implements PreviewURIService
{
    private final static String SYNTHETIC_DIRECTORIES = '/www/avm_webapps/ROOT/';
    private final String previewServerHostnameAndPort;

    public CustomPreviewURIService(String previewServerHostnameAndPort)
    {
        assert previewServerHostnameAndPort != null : 'previewServerHostnameAndPort must not be null';
        this.previewServerHostnameAndPort = previewServerHostnameAndPort;
    }

    public String getPreviewURI(String storeId, String pathToAsset)
    {
        StringBuilder result = new StringBuilder('https://' + previewServerHostnameAndPort);

        if (pathToAsset.startsWith(SYNTHETIC_DIRECTORIES))
        {
            result.append(pathToAsset.replace(SYNTHETIC_DIRECTORIES, '/'));
        }
        else
        {
            result.append(pathToAsset);
        }

        return(result.toString());
    }
}

Back to WCM Preview