Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
{{AVMWarning}}
Back to WCM Developer Documentation
Background
WCM Preview allows editorial users to preview the website 'in-context' (with the style, markup and composition of the website), but using the content from any sandbox in the system.
This is primarily used for two activities:
- To allow content contributors to view their changes in the context of the website, while they are in the process of making those changes
- To allow content approvers to review a change set they've been asked to approve (via workflow), in the context of the website
Effectively it provides a way for contributors and reviewers to view changes as if they'd been published to the live site, but without actually publishing those changes anywhere.
Preview in Alfresco WCM
Alfresco WCM provides 3 ways to preview content in the context of the web site:
- Via the virtualisation server
- Via test server deployment
- Via 'virtualisation' of content retrievals by the web application
Virtualisation Server
This approach to WCM preview is intended to support in-context preview for static HTML web sites and simple (MVC model 1) JSP web applications. In this approach, each Web Project is assumed to be a self contained web site and each sandbox in the Web Project is automatically 'deployed' as a webapp to the virtualisation server (which is nothing more than a slightly modified Tomcat server). In fact there is no true deployment occurring at all - the virtualisation server lazily 'deploys' each sandbox the first time someone requests a preview of it, and even then no physical deployment occurs (the virtualisation server has been customised to read the webapp directly from the Alfresco repository, rather than from the filesystem).
In order to achieve transparent preview of any sandbox in any Web Project in the system, the authoring system uses dynamic hostnames (in tandem with wildcard DNS) for accessing the virtualisation server, and from this enhanced hostname the virtualisation server is able to determine which sandbox and Web Project to read content and webapp assets from. This ensures that the webapp itself has no knowledge of any Alfresco WCM constructs (sandboxes, Web Projects, virtualisation server, etc.) - it simply runs as if it's in a native Tomcat server and the virtualisation system ensures that assets are read from the correct sandbox for each preview request.
See Virtualization Server FAQ for more details.
Test Server Deployment
The Test Server Deployment functionality (added in Alfresco Enterprise v2.2) takes a different approach to in-context preview. Rather than forcing the web application to run inside the virtualisation server (which assumes a static web site or J2EE webapp), it allows a contributor to deploy the content in their user sandbox (or a reviewer to deploy the content in a workflow sandbox) to an external target (either an ASR or FSR), from which it can be rendered by any web application technology that can either read from a filesystem or access an ASR via HTTP (which includes all of the major web application technologies in use today, including Java, .NET, PHP, Ruby, Python, CGI, etc.).
This requires some additional up-front administration, in order to create a sufficiently sized pool of 'test' web application instances to support the expected amount of concurrent in-context preview activity. Making this pool sufficiently large is important since configuring too few test servers will create a bottleneck in the content production process, as contributors are forced to wait for a test server to become available before being able to conduct their preview activities. Note that this approach also creates some latencies in the preview process, since instead of simply clicking on the preview button in the authoring UI, a content contributor or reviewer must first 'check out' a test server and deploy the sandbox of interest to it.
Note however that this approach is also transparent to the web application instances - none of them are aware that they are merely test instances. These instances simply read content from their source (an ASR or filesystem populated by an FSR) and are unaware of how the content arrived there and from whence it came.
The Preview URI Service added in 2.2SP1 can also be useful in this scenario to ensure that the preview button visible throughout the authoring UI does something sensible (ie. sends the user to the preview instance of the webapp, rather than to the virtualisation server).
See WCM_Deployment_Features#Live/Test_Server_Deployment for more details, and please note the limitation described in JIRA Issue ENH-165.
Note that this will be the default WCM preview mechanism as of Alfresco v3.2.
Virtualised Content Retrieval
The third approach to in-context preview supported by Alfresco WCM is somewhat different, primarily in that it doesn't attempt to preserve transparency in the web application - when running in preview mode, the web application is explicitly aware of which sandbox it's operating against. The way this works is that the web application ensures that all content retrieval operations are performed using HTTP (ideally via a library that provides a single mechanism for both HTTP I/O and direct file I/O - we'll see why in a minute). When in preview mode, the web application is configured to call Web Scripts running in the authoring instance of Alfresco - these Web Scripts provide all of the typical content retrieval operations (retrieve single asset, retrieve set of assets, retrieve assets via a query, etc.), however when running in the authoring instance these Web Scripts have a parameter that indicates which sandbox the operation should be applied to. This allows the web application to effectively 'virtualise' all content retrievals - specifying exactly which sandbox the user is wishing to preview and pulling content only from that sandbox.
Now the obvious question is: how does the web application know which sandbox the user wishes to preview? The answer is that the authoring instance tells it, via a customised preview URI. In other words, the preview button that's shown throughout the authoring UI (which, by default, has a URI that points to the virtualisation server) needs to be reconfigured with a custom URI that points to the external 'preview' instance of the web application instead, and one of the components of that URI is the identifier of the sandbox which the user wishes to preview. So all the web application has to do is ensure it captures the sandbox identifier that's passed in and pass it through to any Web Scripts it calls, and it will be as if the web application is virtualising itself. Provided the application also includes the sandbox identifier in any hyperlinks it emits in the HTML output, the virtualisation experience will be seamless - the contributor can click around the web application at will, remaining 'pinned' to the sandbox that they originally requested to preview.
The only slightly complex piece of this puzzle is that every web application tends to have its own unique URI scheme, so there's no way for Alfresco to automatically determine what the URI of the external web application is. For this reason functionality was added in Alfresco Enterprise 2.2SP1 that allows administrators to either configure a URI template for their web application, or inject custom Java code that can implement whatever complex URI mapping rules might be necessary in order to construct a correct URI for the web application. This mechanism is described in more detail at Preview URI Service, and for earlier versions of Alfresco (including v2.0 and v2.1) a workaround is described in this forum post.
Now in production, the web application may in fact perform some of the content retrievals directly from disk (since this provides a significant performance benefit). To do this the HTTP library that's being used by the web application should support file:// URIs, and the web application itself needs to be configurable so that it knows whether it's running in 'preview mode' (in which case all content retrieval is via parameterised Web Scripts with http:// URIs) or in 'production mode' (in which case most content retrieval will be directly from disk via file:// URIs).
Finally, note that due to the lack of sandbox-specific querying in current versions of Alfresco WCM (see this issue in JIRA), any pages that rely on queries for retrieving content won't be correctly virtualised - instead they need to be executed against the staging sandbox. While this may seem like a serious limitation, it's important to remember that:
- this only affects preview (ASRs act as though they only contain staging sandboxes)
- in practice most content contributors are previewing individual content items (often referred to as 'detail pages') most of the time, and those pages typically don't rely on queries for retrieval
- in most cases a contributor's change set is small enough that most queries will return mostly correct results anyway (since the delta between staging and the user sandbox is usually tiny, relative to the total amount of content in the Web Project)
Note however that this assumes that the web application is designed in such a way that queries are only used when absolutely necessary (eg. this approach would be invalidated if queries were used for all content retrieval operations). This is a best practice anyway, so should be a design goal regardless of the preview approach being utilised.
Selecting a Preview Approach
Selecting one of these mechanisms for a given Alfresco WCM implementation is highly dependent on a number of things:
- the nature of the site (static vs dynamic)
- the technology used to implement the web application (Java vs other)
- the amount of concurrent in-context preview traffic the content contributors are expected to generate
That said there are some fairly clear differentiating characteristics, and the following comparison matrix provides a high level overview:
| | Virtualisation Server | Test Server Deployment | Virtualised Content Retrieval |
| Web Application Technology | Static sites and Java only | Any | Any |
| Alfresco versions | v2.0 - v3.1 (deprecated in v3.2+) | v2.2+ | v2.0+ |
| Transparent to Web App | Yes | Yes | No |
| Transparent to Content Contributor | Yes | No - content contributor must explicitly deploy their sandbox before previewing | Yes |
| Number of Concurrent Previews | Limited by virtualisation server scalability | Limited by number of 'test' instances of web application | Limited by web application scalability |
| Number of Instances of Web Application (including supporting infrastructure such as ASRs, FSRs, databases, etc.) | 0 | Many | 1 |
| Web Application Source Code Managed in | Alfresco Web Project | Anywhere (Alfresco, source code management system, etc.) | Anywhere (Alfresco, source code management system, etc.) |
| Supports Content Queries | No | Yes | Yes |
| Content Queries are Sandboxed | n/a | Yes | No - all queries execute against the staging sandbox |
| Requires wildcard DNS and/or access to Alfresco's echoDNS service | Yes | No | No |
| Requires virtualisation server to be installed | Yes | No | No |
And as a final note, it's entirely feasible to use different preview mechanisms for different Web Projects in the same Alfresco WCM instance - choosing one of these mechanisms for a Web Project today in no way limits the choices for future Web Projects hosted in the same Alfresco WCM instance.
Back to WCM Developer Documentation
AVM
