Surf Platform
From AlfrescoWiki
This Wiki page provides a partial overview of the Surf platform but focuses primarily on technical details to facilitate adoption. The two technical sections are the Design Documentation and the Developer's Guide.
Contents |
[edit] 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 class-leading web applications.
The Surf platform is built to be very lightweight. It can build as a standalone WAR file and is designed from the ground up to stand alone within the Web Tier. It includes the Alfresco Web Script Runtime so that application developers can build components, pages, and templates using the rich scripting and FreeMarker templating processing capabilities of Alfresco within in the Web Tier.
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.
Developers who use Alfresco Surf platform will have a wide technology stack at their disposal. This includes Java, JSP, HTML, Web Scripts, server-side JavaScript, and FreeMarker. Developers may also configure the system to use additional renderers.
In the Dynamic Website application, assemblers are able to browse the Alfresco Web Components library and automatically self-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).
[edit] Who uses the Surf platform?
The Surf platform is used by Alfresco's 3.0 release of products to provide a uniform suite of interchangeable functionality.
These applications include:
- Alfresco 3.0
- Alfresco's next generation of enhanced collaboration and document management services. 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 Dynamic Website
- An in-context, drag-and-drop toolkit aimed especially at business users to allow the rapid self-assembly of web applications and web experiences with minimal IT intervention. Empowers teams to construct their own web applications that feature rich end-user interaction, including image galleries, blogs, and forums.
- Alfresco Network and Alfresco Extranet
- Two applications that Alfresco will be making available to its community, partners, and customers. These applications allow our community to interact with each more closely, discover solutions quicker and access a wide array of new services including the Alfresco Knowledge Base and the Alfresco Web Component library.
All of these applications are presently being built on top of the Surf platform. The Surf platform itself is a product that our community and customers may wish, and are encouraged, to use in building their own web applications.
[edit] Distribution and Packaging
Alfresco Surf platform is included with the Alfresco source tree and is distributed along with the community 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.
Right now, there are plans to separately distribute the Alfresco Surf platform as a bundled WAR or ZIP file. If these plans change, we will post information to the Wiki.
[edit] Building the Surf platform
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 Developer Guide. You need Ant and Subversion but then you can sync the source code and then you are ready.
Once you have synced the source code, you should have a /root directory. To build the Surf platform, use the following command:
ant incremental-webframework-tomcat
This tells the Surf platform to build and to build a WAR file. If you have your 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.
[edit] Deploying the Surf platform
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.
In the case of Tomcat, use the following steps:
- Stop Tomcat
- Copy your WAR file into the Tomcat
/webappsdirectory - Start Tomcat
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.
[edit] Features of the Surf platform
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.
[edit] 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.
[edit] Page dispatching framework
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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] Building your own application
This section provides guidance on building your own applications using the Surf platform. Much of this information is contained in separate wiki pages, which are linked from this page.
[edit] Developers Guide
A deep technical reference to the Surf platform is provided in our Surf Platform 3.0 - Developers Guide.
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.
[edit] Walkthroughs and Examples
A guided walkthrough with very specific, yet applicable examples of how to build your own web application are provided on the Surf Platform - Guided Examples page.
