Monday, October 27, 2008

Learning Surf 2 - Examining slingshot configuration

Examining slingshot configuration

You can see my previous blog entry for a background in getting started with surf.

The Surf platform is a web script based framework for developing web 2.0 based applications that can use the alfresco content repository. It relies on the technologies of xml, freemarker and javascript. It heavily leverages alfresco's freemarker templates and the javascript api, and the alfresco's web script technologies that define ui components or RESTful services.

Surf based applications can be developed without an Alfresco content repository access, but ones that use the content repository are developed and deployed as two war files, one for the web application built on surf (i.e. share.war), and one for the content repository it accesses (alfresco.war). These war files can be deployed within the same application container (i.e. tomcat) or different application containers on the same machine or different machines. The web application communicates with the content repository over RESTful services (essentially over http).

The share application is a surf framework application. The source tree stores share in a project called 'slingshot'. Slighshot depends on other projects in the source tree, including:
  • 3rd Party
  • Core
  • Web Framework
  • Webscript Framework
Configurations of a surf application are contained in the following types of configurations:
  • war configuration files (web.xml)
  • alfresco configuration files (i.e. web-framework-config.xml and LOTS more)
  • spring bean configurations (i.e. slingshot-application-context.xml)
  • resource bundles (i.e.
This blog will look at the first three to understand how a surf application is configured.

To trace the configuration, we start with the war. Whithin the Slingshot application is a source folder which includes web/WEB-INF that contains the web.xml for the share.war.

looking at web.xml

A context-param section is included to define the contextConfigurationLocation for spring to find all of the spring beans that are needed to configure the surf application. These include:
  • classpath:alfresco/webscript-framework-application-context.xml
  • classpath:alfresco/web-framework-application-context.xml
  • classpath:alfresco/web-framework-model-context.xml
  • classpath:alfresco/slingshot-application-context.xml
This ties slingshot to depend on the Webscript Framework and the Web Framework projects.

A listener is defined with a springframework web context loader listener wihich loads the spring context form the class paths defined in the 'contextConfigurationLocation' context parameter.

Several servlets are defined

url-patternservlet nameservlet class
/page/*, p/*

Finally, weblome file list includes:
  • index.jsp
  • index.html
looking at the web-framework-config alfresco configuration file

The configuration file defines
  • page-mapper
  • link-builder
  • file-system
  • format default
  • format print
  • format wap
  • persisters
  • model-type (object model) definitions
each model-type defines id, name, class, search path and default store for the following model types:
  • chrome
  • component
  • component-type
  • configuration
  • content-association
  • page
  • page-type
  • page-association
  • template-instance
  • template-type
  • theme
These model-type definitions define where to look for marshaled configurations for model objects of each type, whether to look on the remote store, local path or in the class path.

looking at spring bean application context files

Using spring explorer in Eclipse (Ganymede) allowed me to view spring bean configuration dependencies.

The slingshot-application-context.xml references beans defined in web-framework-application-context.xml and web-framework-model-context.xml.

The web framework beans reference beans defined in webscript-framework-application-context.xml.

slingshot-application-context.xml contains the following beans:

The 'webscript.resource' bean list resource bundles that contain messages to use. The other beans (i.e.'') tell surf where to look (i.e. search paths) for definitions of the different model components that surf needs to run. For instance, to know how 'chrome' is configured.

web-framework-application-context.xml contains the following beans:

Tracing through rendering the dashboard
To demonstrate the configuration, lets look at the beginning, rendering the dashboard. The share.war defines the welcome page 'index.jsp'. This jsp redirects to '/page/site-index'. As defined in web.xml, /page/* url pattern runs the 'pageRendererServlet'. This servlet looks for a model object named 'site-index'. The name 'site-index' is defined as a page model object found in the default remote store (as defined in web-framework-config.xml for the page model-type) in './site-data/pages'.
'site-index.xml' defines a page model object named 'site-index' which defines:
  • title = welcome
  • descrition = Landing page for users - will create user site dashboard
  • template-instances = site-index
  • authentication = user
The site-index page model object references a template instance named 'site-index' found also in the default store ( ./site-data/template-instance):
The template-instance refers to a template-type 'site-index' found in (site-data/template-types)
'site-index.xml' is a template-type model object and defines:
  • title = site index landing page template type
  • description = Site index landing page JSP Template Type
  • renderer = /site-index.jsp
  • renderer-type = jsp
Looking at '/site-index.jsp' as a jsp template renderer, we see scriptlet logic that follows:
If not already created the user dashboard, create the user's dashboard using the definition in presets (found in ./site-data/presets/presets.xml) for 'user-dashboard'.
Render the user dashboard.
In 'user-dashboard' preset, the 'components' section creates components and assigns to regions according to the template insance (dashboard-3-columns) defined in the 'pages' section.

The 'dashboard-3-columns.xml' template-instance definition defines

template-type = org/alfresco/dashboard.ftl.

'dashboard.ftl' imports alfresco-template.ftl and alfresco-layout.ftl and creates regions named 'component--' where the preset components are added.

The preset creates and places the following components into the dashboard template:
define title from (site-webscripts/org/alfresco/components/title/user-dashboard-title*)
define list of page components (dashlets) positioned at {column#}-{row#):
  • user-welcome at 1-1
  • user-calendar at 1-2
  • rssfeed at 2-1
  • alfresco-network at 2-2
  • my-activities at 2-3
  • cmisfeed at 3-4
  • my-profile at 3-1
  • my-sites at 3-2
  • my-tasks at 3-3
Each dashlet is defined by a ui web-script found in site-webscripts/orgb/alfrsco/components/dashlets/. See a description of alfresco's web-scripts technology for details on ui web scripts.

1 comment:

NancyG said...


I'm the Community Manager at Alfresco and I'd like to thank you for taking the time to share your knowledge.

We are planning to have a Surf CodeCamp in Chicago (I noticed from your profile that you are located in the area). I hope you can attend. We are working on a date, should be in late January/early February.

Best and happy holidays,

Nancy Garrity
Alfresco Community Manager