Surf Platform

[resplin]

Obsolete Pages{{Obsolete}}

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

Surf PlatformLabs 33.0
NOTE: This page describes the Alfresco Surf Platform which is included in Alfresco 3.0, 3.1 and 3.2.

If you are looking for information about Alfresco 3.3, please visit Spring Surf.

This page provides an overview of the Surf platform, focusing on technical details to facilitate adoption.  This provides a good first step for getting started with the Surf Platform.

If you are viewing this page, you may also be interested in the following documentation:

• Surf Developer's Guide
  
• Surf JavaScript API
  
• Surf Advanced Customization and Extension Guide
  
• Surf Deployment Configurations
  
• Surf Guided Walkthroughs
  

__toc__

Table of Contents

• 1 Overview
  
  
  
  • 1.1 Integration with Alfresco Web Content Management
  
  
  • 1.2 Integration with Alfresco Web Studio
  
  


• 2 Features
  
  
  
  • 2.1 100% XML
  
  
  • 2.2 Site Dispatcher
  
  
  • 2.3 Templates
  
  
  • 2.4 Components
  
  
  • 2.5 Formats
  
  
  • 2.6 Manage the Web Experience
  
  
  • 2.7 User Management, Connectors, and Credential Vaults
  
  
  • 2.8 Storage into the AVM Repository
  
  
  • 2.9 High Performance and Caching
  
  


• 3 Where is Surf used?
  
  
  
  • 3.1 Alfresco Share
  
  
  • 3.2 Alfresco Network
  
  
  • 3.3 Alfresco Web Studio
  
  


• 4 Getting Started
  
  
  
  • 4.1 Building
  
  
  • 4.2 Deploying
  
  


• 5 Additional Resources
  
  
  
  • 5.1 Developers Guide
  
  
  • 5.2 Javascript API
  
  
  • 5.3 Advanced Customization and Extension
  
  
  • 5.4 Guided Examples
  
  

Overview

The Alfresco Surf platform is a robust, enterprise-class web application and site assembly framework that bundles a full site construction object model and toolkit for building web sites and applications.

The Alfresco Surf Platform is designed to be lightweight.  It builds on the scriptable concepts that were first introduced with Alfresco's Web Scripts technology.  All pages, templates, components or indeed, any Surf object, is a content fragment that can be changed, tested and previewed without need for IT intervention or application server restarts.

Applications that are built with the Alfresco Surf platform are provisioned with a backbone that manages remote proxied connections to the Alfresco repository server, JSON streams, and user state across multiple components or widgets that are snapped into a page. Pages take advantage of dynamic website concepts such as multiple scopes (site, template, and page scopes), protected accessors to component regions, dynamic component configuration and so on.

Alfresco Surf includes the Alfresco Web Script Runtime and provides application developers with the full set of facilities for building scriptable applications.  Developers write components, pages and templates using the rich scripting and FreeMarker templating processing capabilities of Alfresco within the Web Tier.  Developers are thus empowered with a wide technology stack - including Java, JSP, HTML, Web Scripts, server-side JavaScript, and FreeMarker. Developers may also configure the system to use additional rendering processors if they wish.

Integration with Alfresco Web Content Management

Alfresco Surf works hand-in-hand with Alfresco Web Content Management and provides virtualized content retrieval, preview and test support for user sandboxes and web projects.  Applications built with Alfresco Surf can be deployed from Alfresco Web Project spaces to production servers while taking full advantage of Alfresco WCM's Enterprise class features.  These include:

• Safe editing of all aspects of Surf-powered sites.  Snapshots allow your Surf site to roll backward and forward in time.  Audit trails provide a rich log of changes made to the site.
  
• Integrated workflow for approval of all Surf components.  These include pages, templates, components, chrome, and much more.
  
• User sandboxes provide freedom for experimentation and iteration in design.  Change anything about your Surf site with the assurance that you can always discard changes or promote the bits you are happy with.
  

Furthermore, Surf applications can be deployed as a standalone WAR file to the production or presentation tier.  Alfresco Surf-powered applications can retrieve all of their runtime data from local disk, the classpath or from the Alfresco repository via REST.

Integration with Alfresco Web Studio

Alfresco Web Studio is available for Surf designers who wish to build Surf applications using a visual, drag-and-drop designer.  By using Alfresco Web Studio, application designers are able to browse a library of Alfresco Web Components and visually assemble their web experience. 

This puts the full-breadth of Alfresco Collaboration, Document Management, and Web Content Management functionality at their fingertips. It also opens the doors for Web Component provisioning from other open source and open-standards vendors (that is, Google Gadgets and so on).

Features

The platform collectively known as the Surf platform consists, in fact, of several integrated parts. This section describes some of these parts at a high level but you can find further detailed technical information in the Surf Platform 3.0 - Developers Guide.

100% XML

A major advantage of Alfresco's core product is the ability to manage multiple versions or snapshots of your web site at a time. This allows for every user who is working on a web site to make changes in real time and preview those changes instantly.

To help facilitate this, the Surf platform uses a lightweight XML-driven model to store all Model objects that make up the web site.  Model objects are things like pages, templates, components, themes, and chrome. Essentially, anything that can be customized in terms of the web experience is a Model object.

Site Dispatcher

Fundamentally, a well constructed web application framework should provide a page dispatching framework. A page dispatching framework allows application developers to easily create pages and link them to the overall navigation of the web site. It also allows for pages to be built in a way that promotes maximum reusability so that things do not need to be built more than once (unless you wish this to be the case).

Alfresco defines pages and associations between pages (Page-Associations) as Model objects. Pages have properties on them like title and description. Page Associations can be either child associations or linked associations.

Templates

A web application or web site may only have a few pages (as in the case of a simple project workspace) but it also may have hundreds of thousands of pages (in the case of, say, a product catalog or retail site). Page management in the former case is pretty simple.  In the latter case, it becomes more difficult.

Templates make it possible to define a page layout once and then reuse it across a large set of pages. Pages associate themselves to templates so that the dispatcher can determine how to appropriately render the page.

With this model in place, an update to the product's page does not need to be applied many times. You just apply it once and all product pages are affected at once.

In the Surf platform, you can develop templates using Freemarker, JSP, HTML, or Java. Most commonly, you will use Freemarker. In each of these template languages, the essential goal is to layout the placement of regions (or slots) into which components can be bound.

Components

Components are reusable UI objects that can be snapped into regions (or slots) within your page or template. They consist of back-end application logic and front-end presentation code. In other frameworks, they go by many names, including widgets, modules, gadgets, portlets, dashlets and so on.

A Component Type can be described and then instantiated many times. For example, a piece of calendar functionality would be a component type. It could be instantiated onto many separate pages.  Each instance manages its own application state and interaction with the end user independently.

In the Surf platform, you can develop components using a variety of technologies. Most commonly, you will use Alfresco's web scripting capabilities. This consists of server-side JavaScript (for application logic) and Freemarker (for presentation) in a typical MVC pattern. However, you can also use JSP, Java, HTML, or other language implementations.

Formats

When you build a web application, chances are that you will want it to be accessible, not only to a web browser, but also to hand-held devices, and not only on the screen, but also in print format, as a PDF or as a newsletter.

Formats allow you to do this. Any page rendition can have multiple formats. Therefore, you can build your web site once, with navigation structure as well as content, and then leverage formats to render it into multiple output formats.

Manage the Web Experience

In most page frameworks, there is an underlying assumption that components and page data come from a specific repository. As you might expect, the assumption is usually that all of your data lives in the vendor's repository.

With Alfresco's Surf platform, we make no such assumption. You may have multiple stores on the back-end with content. Some of them might be Alfresco servers; others might be wiki applications or blog applications, both of which are valid sources of content; or they might be SharePoint instances.

Alfresco's Surf platform allows you to build web sites around this information. You can build web experiences by describing what to display when the end-user is looking at a wiki page. One part of the page may show the wiki article. Other parts of the page may show information related to that wiki article.

User Management, Connectors, and Credential Vaults

As with most application frameworks, the notion of a current user and a pluggable authentication mechanism is key. The Surf platform allows you to extend the definition of the user object and plug in new authenticators.

By default, the Surf platform authenticates and manages user state against an Alfresco repository. Once that is done, the Surf platform takes this a step further by providing a Credential Vault. The vault automatically manages and stores credentials for any back-end service connections the user may make to remote services.

Naturally, this supports one or more Alfresco repositories. However, it also supports other data providers, such as Google Gadgets, wikis, blogs, and others. The user's credentials are mastered once and all downstream connections are automatically provisioned with the needed authentication tokens to connect and stream data back for rendering within the final presentation.

Storage into the AVM Repository

The Surf platform is 100% compatible with the AVM repository, which means that web applications built with the Surf platform can easily run standalone or within an Alfresco Web Project.

Alfresco Web Projects are an ideal place to build web application as they appeal to a diverse range of users, from developers to content contributors. They bring the power of source control tools to your business users and wrap everything neatly in workflow processes so that you can assure the quality of the content that reaches your consumers.

High Performance and Caching

The Surf platform avoids the pains of most legacy systems by avoiding the pitfall of being over-architected. There are many solutions on the market that are too complex and painful too use.  We deliberately avoided that by keeping everything very lightweight and fast. There are no EJBs or JMS message queues, and you do not have to orchestrate an army of deployment agents just to preview a small change to a page.

Instead, the Surf platform intentionally does not get much more complex than XML and a servlet engine. You can use Freemarker, JSP, Java, and HTML for all of your development. And you do not have to learn TCL or any other proprietary scripting language.

Keeping things simple allowed our developers to focus on performance. We want your pages to render extremely quickly. Components are therefore provisioned with the ability to describe their own caching behaviors. The framework automatically caches where appropriate to ensure the fastest possible rendering time.

Where is Surf used?

Alfresco Surf is the presentation tier technology utilized by Alfresco for its entire 3.x product suite.

Alfresco Share

Alfresco's next generation of enhanced collaboration and document management services. Alfresco Share provides out of the box web client templates for creating social networking sites that use a rich library of downloadable and shareable themes, components, templates, and application logic.

Alfresco Network

Alfresco Network provides a support service that Alfresco will be making available to its Enterprise customers, incorporating access to Alfresco news, ticket details and resolution, and new services, such as the Knowledge Base and the Web Component library.

Alfresco Web Studio

Alfresco Web Studio is a visual, drag-and-drop designer for building web sites with the Alfresco Surf platform.  It features graphical overlays that facilitate the building of your web site's pages, navigation structure, templates, and presentation layout. Web components snap into your site's pages through simple drag-and-drop interactions. Using Alfresco Web Studio, you can quickly create custom web sites while leveraging the strengths of the Alfresco Web Content Management runtime and repository.

Getting Started

Alfresco Surf platform is included with the Alfresco source tree and is distributed along with the community and enterprise source. It is 100% open source and is available from our public Subversion (SVN) server as usual. Developers can choose an existing distribution but they may also choose to build entirely from source.

In building entirely from source, developers can produce an 'empty' Surf site with all of the backing bits for them to build upon.

In addition, initial planning and work has begun on an Alfresco Surf SDK.  This will be very similar to the Eclipse SDK projects presently in existence for Alfresco and will permit Alfresco Surf developers to build components and templates directly within Eclipse.

Building

As with all of Alfresco's source code, you are able to access the Surf platform using Subversion. You must set up your build environment according to the documentation provided in our Alfresco SVN Development Environment and Surf Platform - Developers Guide. You need to get SVN installed, get all the pre-requirements installed, and then you can pull down the source code with SVN.

Once you have synced the source code, you should have a /HEAD/root directory. Switch to the root directory. You should have a main build.xml file and several other xml files for the ant script.

You should first do a full build with this command:

ant build

This will build any dependencies that are needed for the Surf build.

To build the Surf platform, use the following command:

ant incremental-webframework-tomcat

This builds the Surf platform along with all of its dependencies.  A WAR file will be produced as an output.  If you have your APP_TOMCAT_HOME environment variable set, the script will also auto-deploy the WAR file to your standalone Tomcat instance.

Once the build script finishes, the following file is produced:

/root/projects/web-framework/build/dist/alfwf.war

You have now successfully built the Surf platform.  The alfwf.war file contains a very small sample Surf application.  This is useful to test your Surf installation.

Deploying

The Surf platform builds and distributes as a standard WAR file. As mentioned, it is lightweight and everything you need is inside of the WAR file. Therefore, you can drop it into any valid Java application server.

It is important to note that the Surf application server does not need Alfresco!  In fact, Surf is entirely self-contained.  It runs on the presentation tier.  The Alfresco repository runs on the repository tier (which is a different application server instance).

In the case of Tomcat, use the following steps:

1. Stop Tomcat
   
2. Copy your WAR file into the Tomcat /webapps directory
   
3. Start Tomcat
   

Note - You can drop in the alfwf.war file from the previous section.

When Tomcat starts up, it will discover your WAR file and launch the web application. Once Tomcat finishes starting, you can open a browser and go to the following URL:

http://localhost:8080/alfwf/page?p=welcome

If everything is working correctly, you will see a welcome test page render back. This page contains several components that execute and render output to the screen.

You have now successfully built and deployed the Surf platform with a sample site. More information on how you can start to build your own pages and components is available later in this section.

Additional Resources

After you get the simple alfwf.war file sample running, you will probably be inclined to begin building your own web site.  This section provides some references on how you can get started.

Developers Guide

A deep technical reference to the Surf platform is provided in our Surf Platform 3.0 - Developers Guide.

Javascript API

An overview of the JavaScript API (which is available to Web Script and Template developers) is covered in our Surf Platform 3.0 - Freemarker Template and JavaScript API.

Advanced Customization and Extension

An in-depth look at advanced options for customization and extension of the Surf Platform.  The Advanced Customization Guide is really intended for framework developers who wish to enhance or extend the Surf Platform itself rather than build things with Surf.

Guided Examples

A community contributed collection of guided examples on building Surf applications and extending the Surf platform.