The Alfresco Content Services system is implemented in Java, which means that it can run on most servers that can run the Java Standard Edition. The platform components have been implemented using the Spring framework, which provides the ability to modularize functionality, such as versioning, security, and rules. The platform provides a scripting environment to simplify adding new functionality and developing new programming interfaces. This portion of the architecture is known as Web Scripts and can be used for both data and presentation services. The lightweight architecture is easy to download, install, and deploy.
Ultimately, Alfresco Content Services is used to implement ECM solutions, such as document management and records management. There can also be elements of collaboration and search across these solutions.
A content management solution is typically divided into clients and a server. The clients offer users a user interface to the solution and the server provides content management services and storage. Solutions commonly offer multiple clients against a shared server, where each client is tailored for the environment in which it is used.
Alfresco Content Services offers a web-based client called Alfresco Share, built entirely with the web script technology. Share provides content management capabilities with simple user interfaces, tools to search and browse the repository, content such as thumbnails and associated metadata, previews, and a set of collaboration tools such as wikis and discussions. Share is organized as a set of sites that can be used as a meeting place for collaboration. It's a web-based application that can be run on a different server to the server that runs the platform with repository, providing opportunities to increase scale and performance.
Alfresco has offered the Share web client for a long time. However, if a content management solution requires extensive customization to the user interface, which most do, then it is not recommended to customize Share. Develop instead a custom client with the Alfresco Application Development Framework (ADF), which is Angular based.
Clients also exist for mobile platforms, Microsoft Outlook, Microsoft Office, and the desktop. In addition, users can share documents through a network drive via WebDAV.
The content application server comprises a content repository and value-added services for building solutions.
Clients communicate with the content application server and its services through numerous supported protocols. HTTP and SOAP offer programmatic access while FTP, WebDAV, IMAP, and Microsoft SharePoint protocols offer application access.
This section covers the platform architecture in detail. It also goes through Content Modeling, which is a fundamental part of setting up a content management system. Finally it covers the platform access protocols and the platform modularity.
The following diagram illustrates the platform architecture and extension points [10]. Note that this does not represent a complete list of extension points [10]:
The platform consists of the repository and all services, developer extension points [10], and APIs [11]. The repository provides storage for documents and other content. The content metadata is stored in a relational database, while the content itself is stored directly on the file system. The relationships between content items, and their various properties (metadata) are defined in one or more content models [12].
Content models [12] can be thought of as describing types of content and the relationships between pieces of content. For example, there is a relationship between a content that has a container functionality (that is, folder), and the piece of content contained within it (that is, sub-folders and files). There might be constraints defined in the content model, such as a content type cannot contain other content unless it is a container type.
As well as the basic content storage functionality, the platform provides a wide range of content-related services. These include core services such as the Node Service, and the Version Service. There are also higher-level services such as Thumbnail Service (for creating thumbnail images and renditions of documents), the Site Service used for creating and managing sites in the Share application, and the Tagging Service, which provides the ability to tag content with keywords. The following sections of this documentation provide a brief tour of the available services.
Typically these services are implemented in Java, and expose an API described by the Public Java API [13].
The platform is highly extensible. You can write extensions in Java, JavaScript, and FreeMarker, and you can write client applications in any language using the ReST API [14]. You can create new content models [12] that define new content types, metadata, and relationships. You can define custom actions [15] that the repository will carry out when certain events happen (such as when new content is added to the repository). You can even create entirely new services, if required.
When you need to create custom business workflow you should use the Alfresco Process Services (APS) [16] product.
Content modeling specifies how nodes stored in the repository are constrained, imposing a formal structure on nodes that an application can understand and enforce. Nodes can represent anything stored in the repository, such as folders, documents, XML fragments, renditions, collaboration sites, and people. Each node has a unique ID and is a container for any number of named properties, where property values can be of any data type, single or multi-valued.
Nodes are related to each other through relationships. A parent/child relationship represents a hierarchy of nodes where child nodes cannot outlive their parent. You can also create arbitrary relationships between nodes and define different types of nodes and relationships.
A content model defines how a node in the repository is constrained. Each model defines one or more types, where a type enumerates the properties and relationships that a node of that type can support. Often, concepts that cross multiple types of node must be modeled, which the repository supports through aspects. Although a node can only be of a single type, you can apply any number of aspects to a node. An aspect can encapsulate both data and process, providing a flexible tool for modeling content.
Content modeling puts the following constraints on the data structure:
These constraints allow the definition (or modeling) of entities within the domain. For example, many applications are built around the notion of folders and documents. It is content modeling that adds meaning to the node data structure.
The repository provides services for reading, querying, and maintaining nodes. Events are fired on changes, allowing for processes to be triggered. In particular, the repository provides the following capabilities based on events:
Models also define kinds of relationships, property data types, and value constraints. A special data type called content allows a property to hold arbitrary length binary data. Alfresco Content Services comes prepackaged with several content models. You can define new models for specific use cases from scratch or by inheriting definitions from existing models.
For more information see content model introduction [12].
Protocols provide developers with another possible avenue for building their own applications and extensions. For example, if you are building a client application to connect with multiple repositories from multiple vendors, including Alfresco Content Services, then CMIS is a consideration. If you are building a client to connect via the SharePoint Protocol, then use the Alfresco Office Services (AOS). Protocols provide a resource for developers, in addition to the numerous other extension points and APIs built into Alfresco.
When any of these protocols are used to access or upload content to the repository, access control is always enforced based on configured permissions, regardless of what protocol that is used.
The following table list some of the main protocols supported by Alfresco Content Services and links to more detailed documentation.
| Protocol | Description | Support Status |
|---|---|---|
| HTTP | The main protocol used to access the repository via for example the ReST APIs. | Standard in Alfresco Content Services and Community Edition. |
| WebDAV [18] | Web-based Distributed Authoring and Versioning is a set of HTTP extensions that lets you manage files collaboratively on web servers. It has strong support for authoring scenarios such as locking, metadata, and versioning. Many content production tools, such as the Microsoft Office suite, support WebDAV. Additionally, there are tools for mounting a WebDAV server as a network drive. | Standard in Alfresco Content Servicesand Community Edition. |
| FTP [19] | File Transfer Protocol - standard network protocol for file upload, download and manipulation. Useful for bulk uploads and downloads. | Standard in Alfresco Content Services and Community. |
| Alfresco Office Services [20] | Alfresco Office Services (AOS) allow you to access Alfresco Content Services directly from all your Microsoft Office applications. | Standard in Alfresco Content Services and Community Edition. |
| CMIS [21] | Alfresco fully implements both the CMIS [22] 1.0 and 1.1 standards to allow your application to manage content and metadata in an on-premise repository. | Standard in Alfresco Content Services and Community Edition. |
| IMAP [23] | Internet Message Access Protocol - allows access to email on a remote server. Alfresco Content Services can present itself as an
email server, allowing clients such as Microsoft Outlook, Thunderbird, Apple Mail and
other email clients to access the content repository, and manipulate folders and files
contained there. IMAP supports three modes of operation:
|
Standard in Alfresco Content Services and Community Edition. |
| SMTP [24] | It is possible to email content into the repository (InboundSMTP). A folder can be dedicated as an email target. | Standard in Alfresco Content Services and Community Edition. |
All the protocol bindings expose folders and documents held in the repository. This means a client tool accessing the repository using the protocol can navigate through folders, examine properties, and read content. Most protocols also permit updates, allowing a client tool to modify the folder structure, create and update documents, and write content. Some protocols also allow interaction with capabilities such as version histories, search, and tasks.
Internally, the protocol bindings interact with the repository services, which encapsulate the behavior of working with folders and files. This ensures a consistent view and update approach across all client tools interacting with the content application server.
A subsystem for file servers allows configuration and lifecycle management for each of the protocols either through property files or JMX.
This section covers the Web UI architecture in detail. There are a number of web clients available when accessing the repository. There is also the Application Development Framework that can be used to build domain specific web applications.
Alfresco has traditionally always offered a Web client called Share, which is still available. However, if a content management solution requires extensive customization to its user interface, which most do, then it is not recommended to customize Share. Develop instead a custom client with the Alfresco Application Development Framework, which is Angular based.
The Alfresco Application Development Framework [29], referred to as ADF, is built on top of the Angular 5 JavaScript framework. You can think of ADF as a library of Alfresco web components [30] that can be used to build a content management web application and/or a process management web application.
For a complete list of all components with documentation see the ADF Component Catalogue [31].
ArchitectureThese ADF components don’t talk directly to the ACS and APS backend services. There are some layers between them that are worth knowing about before you start coding. The ADF components talk to ADF services, which in turn talks to the Alfresco JS API [32], which internally calls ACS and APS via their respective ReST APIs. You could use the both the ADF services and the Alfresco JS API directly from your application if there is no ADF component available to do what you want. In fact, you will quite frequently have to use the ADF services in your application to fetch content nodes, process instances, task instances etc.
The following picture illustrates the architecture of
an ADF solution: 
The ADF components and services are implemented in Angular, which in turn is implemented in TypeScript. The Alfresco JavaScript library is pure JavaScript and could be used with any other JavaScript framework.
Application GeneratorUsing the App Generator is simple. Install the Yeoman [34] tool. Then install the App Generator as follows:
$ sudo npm install generator-alfresco-adf-app -g
Password:
+ generator-alfresco-adf-app@2.3.0
added 243 packages in 5.438s
Running the generator is easy:
$ yo
? 'Allo Martin! What would you like to do? (Use arrow keys)
Run a generator
❯ Alfresco Adf App
──────────────
Update your generators
Install a generator
Find some help
Clear global config
Select the 'Alfresco Adf App' generator and follow instructions.
The Alfresco JavaScript API is not normally used directly. Instead the Alfresco Application Developement Framework (ADF) is used, which uses the JavaScript API indirectly. But there are situations when it might be necessary to use the JavaScript API directly, such as when ADF cannot be used. ADF is based on Angular and if another JavaScript library such as React has been adopted, then it is beneficial to use the Alfresco JavaScript API directly from React.
The Alfresco JavaScript library abstracts the Alfresco Content Services (ACS) ReST API and the Alfresco Process Services (APS) ReST API, so a lot of work has been done to make it smooth to use the Alfresco ReST APIs from a third party JavaScript library. For example, authentication with both ACS and APS is handled automatically by the Alfresco JavaScript library.
For more information about the Alfresco JavaScript API, and examples of how to use it, have a look here [32].
Alfresco Share (share.war) is a web application that runs on the Java Platform. In a development environment it is usually deployed and run on top of Apache Tomcat. Share is built up of a main menu that leads to pages, which is similar to most other web applications that you might come across. However, there is one special page type called Dashboard that contains dashlets. A Dashboard page can be configured by the end-user, who can add, remove, and organize the dashlets on the page.
Share pages and dashlets are implemented with something called web scripts, which is basically REST-based APIs. These APIs are called Surf web scripts when you are dealing with Alfresco Share. There is also repository web scripts that are used to extend the repository web application (alfresco.war) with REST-based APIs. Surf Web Scripts are referred to as Presentation Web Scripts and the repository web scripts as Data Web Scripts.Share web scripts, pages, and dashlets are implemented with a user interface (UI) development framework called Surf. This framework was originally developed by Alfresco, then donated to the Spring Source foundation, and finally brought back into Alfresco products. It provides a way of breaking a HTML page into re-usable component parts. Surf is built on top of the Spring Web MVC technology, which in turn uses the Spring Framework.
Developers can also add completely new pages and dashlets to the Share UI when content should be viewed or handled in a specific way. Sometimes it is also required to modify existing pages. To customize the Share UI developers use so called Extension Points [35], which are supported ways of injecting new custom code that should alter the functionality of the Share web application.
The following picture gives an overview of the Alfresco Share application architecture, note that not all available extension points are illustrated in this picture:
Share gets the content that it should display in pages and dashlets by calling repository web scripts, which returns JSON or XML that can be incorporated into the presentation. The presentation is actually put together with two different kinds of JavaScript frameworks, Yahoo UI library (YUI) and Aikau, which is based on Dojo. An Aikau page is based on Surf but it makes page composition much easier than with pure Surf pages.
You can focus solely on Aikau if the only thing you are going to do is add new stuff to the Share UI. However, if you need to alter behavior of existing pages, then you might also need to get up to speed on the details of the Surf page model, as only the following has been converted to Aikau:
The following sections get into a bit more details around Surf pages and Aikau pages.
The layout of a Share page is defined with the Surf development framework, which is a server side framework (Surf deep dive [36]). This means that the involved files are processed on the server side (compared to Browser processing of JavaScript files). Surf is based on the Model View Controller (MVC) pattern where the controller(s) is mostly implemented in server side JavaScript (The Rhino JavaScript engine is included on the server side). The template is written in FreeMarker, and the model is a hash map that is set up in the controller(s) and available in the template.
Each page template defines one or more regions for things like header, footer, body, navigation, see the following picture:
To be able to reuse regions we can scope them to page, template, or global usage:
Each region is implemented as a reusable component. A component implementation is done with a Surf web script, which is the same thing as the REST-based request and response model, the predominant Web Service design model. The component web scripts will typically return HTML fragments that make up different parts of the page:
With all these different objects we might expect there to be some form of model that makes up the whole Surf UI development framework. It looks like this:
/WEB-INF/classes/alfresco
/site-data
/chrome
/components
...
global.header.xml
/component-types
/configurations
/content-associations
/extensions
/page-associations
/pages
...
documentlibrary.xml
...
search.xml
...
task-details.xml
...
/page-types
/template-instances
1-column.xml
2-columns.xml
3-columns.xml
...
content-viewer.xml
...
search.xml
...
/template-types
/themes
The Site Data model defines the page in XML [38], like in the
following example for Search
(alfresco/tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/pages/search.xml):
<?xml version='1.0' encoding='UTF-8'?>
<page>
<title>Search</title>
<title-id>page.search.title</title-id>
<description>Search view</description>
<description-id>page.search.description</description-id>
<template-instance>search</template-instance>
<authentication>user</authentication>
<components>
<!-- Title -->
<component>
<region-id>title</region-id>
<url>/components/title/search-title</url>
</component>
<!-- Search -->
<component>
<region-id>search</region-id>
<url>/components/search/search</url>
</component>
</components>
</page>
Here we can see that some components [39] have been
defined inline in the search page definition, instead of in the /components
directory as separate files. The name of the page definition file is implicitly setting the
page id to search. A corresponding template
instance [40] file is expected to be present in the template-instances
directory. In our case it will be a file called search.xml: <?xml version='1.0' encoding='UTF-8'?> <template-instance> <template-type>org/alfresco/search</template-type> </template-instance>It will have a link to the physical template that contains the layout of the page. The template files are located under a different directory called /templates, which is on the same level as the site-data directory:
/WEB-INF/classes/alfresco
/site-data
/templates
/org
/alfresco
1-column.ftl
2-columns.ftl
3-columns.ftl
...
content-viewer.ftl
...
search.ftl
...
The search.ftl template file looks like this with the regions
etc:
<#include "include/alfresco-template.ftl" />
<@templateHeader />
<@templateBody>
<@markup id="alf-hd">
<div id="alf-hd">
<@region scope="global" id="share-header" chromeless="true"/>
</div>
</@>
<@markup id="bd">
<div id="bd">
<div class="yui-t1">
<div id="yui-main">
<@region id="search" scope="page" />
</div>
</div>
</div>
</@>
</@>
<@templateFooter>
<@markup id="alf-ft">
<div id="alf-ft">
<@region id="footer" scope="global" />
</div>
</@>
</@>
The search page reuses the global header and footer components and then defines a
page specific region called search. The web script to call for the search component is
already defined in the page definition XML above (that is,
/components/search/search). The controller file for the search Web
Script looks like this
(alfresco/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/components/search/search.get.js):
/**
* Search component GET method
*/
function main()
{
// fetch the request params required by the search component template
var siteId = (page.url.templateArgs["site"] != null) ? page.url.templateArgs["site"] : "";
var siteTitle = null;
if (siteId.length != 0)
{
// Call the repository for the site profile
var json = remote.call("/api/sites/" + siteId);
...
This is server side JavaScript code that sets up a model with data for the template.
The template looks like this
(alfresco/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/components/search/search.get.html.ftl):
<@markup id="css" >
<#-- CSS Dependencies -->
<@link href="${url.context}/res/components/search/search.css" group="search"/>
</@>
<@markup id="js">
<#-- JavaScript Dependencies -->
<@script src="${url.context}/res/components/search/search-lib.js" group="search"/>
<@script src="${url.context}/res/components/search/search.js" group="search"/>
</@>
<@markup id="widgets">
<@createWidgets group="search"/>
</@>
<@markup id="html">
<@uniqueIdDiv>
<#assign el=args.htmlid>
<#assign searchconfig=config.scoped['Search']['search']>
<div id="${el}-body" class="search">
<#assign context=searchconfig.getChildValue('repository-search')!"context">
<#if searchQuery?length == 0 && context != "always">
<div class="search-sites">
...
The template is where we will find references to client side code/resources. The
css and js sections above points to the client side CSS
and JS that should be part of the <head> section in the web page, and
downloaded and executed by the browser to create the user interface. So as we are starting
to talk about the client side, let's dig into it a bit more in the next section.To get an idea of the differences between the old school Surf pages, and the new Surf pages called Aikau, this example implements a simple page in both client side frameworks. The thing that might be a bit confusing to start with is that Aikau pages are also old school Surf pages under the hood. An Aikau page actually uses a predefined Surf page as a starting point. Start with an old school Hello World page and see how to add it to the Share UI.
Hello World Old School Surf Page
The following steps are needed to add a Surf Page:
Next, have a look at how to implement the same Hello World page with Aikau.
Hello World Aikau Page
To implement the Hello World page in Aikau we have to go through the following steps:
As you can imagine, there are loads of extension points that you can use in the Share UI to build a customized version of the user interface. In this article we have looked at the major ones, which are old school Surf Pages, Aikau Surf pages, Aikau widgets, web scripts, Surf Module extensions, and dashlets. I know we did not explicitly look at how to implement dashlets, but it is the same thing as implementing a Web Script.
There are many more extension points though, for example the Document Library page in a site can be extended via something called Document Library Actions. It is important to know about these supported extension points, and follow them, as otherwise your code might not work in a future release of Alfresco Content Services, and you might have trouble getting the support you need.
Here is a list of each supported extension point in Share, for a comprehensive description of each one go to the Share Extension Points [35] section (OOTB = Out-of-the-box functionality):
| Extension Point Name |
|---|
| Share Configuration [43] |
| Form Controls [44] |
| Form Filters [45] |
| Form Field Validation Handlers [46] |
| Evaluators [47] |
| Site Presets [48] |
| Share Themes [49] |
| Document Library [50] |
| Surf Extension Modules [51] |
| Surf Web Scripts [52] |
| Surf Web Script JavaScript Root Objects [53] |
| Surf Pages [54] |
| Surf Dashlets [55] |
| Surf Widgets [56] |
| Aikau Menus [57] |
| Aikau Pages [58] |
| Aikau Dashlets [59] |
| Aikau Widgets [60] |
| Modifying OOTB Surf Pages [61] |
| Modifying OOTB Surf Dashlets [62] |
| Modifying OOTB Surf Widgets [63] |
| Modifying OOTB Aikau Pages [64] |
| Modifying OOTB Aikau Dashlets [65] |
| Modifying OOTB Aikau Widgets [66] |
| Modifying OOTB Surf Web Scripts [67] |
Let's see how we can implement a Hello World page with the old school Surf Page framework.
The following steps are needed to add a Surf Page:
Let's start out with the page definition file, create a file called helloworldhome.xml in the alfresco/tomcat/shared/classes/alfresco/web-extension/site-data/pages directory. You will have to create the site-data and pages directories. We are not using a build project to be able to focus solely on Surf.
<?xml version='1.0' encoding='UTF-8'?> <page> <title>Hello World Home</title> <title-id>page.helloworldhome.title</title-id> <description>Hello World Home Description</description> <description-id>page.helloworldhome.description</description-id> <template-instance>helloworldhome-three-column</template-instance> <authentication>none</authentication> </page>
Here we are defining the title and description of the page both hard-coded in the definition, and as references to a properties file with labels (i.e. the title-id and description-id elements). The page will not require any authentication, which means we cannot fetch any content from the Alfresco Repository from it. It is also going to use a three column template, or that is the idea, you can name the template instance whatever you want.
<?xml version='1.0' encoding='UTF-8'?> <template-instance> <template-type>org/alfresco/demo/helloworldhome</template-type> </template-instance>This file just points to where the FreeMarker template for this page will be stored. So create the alfresco/tomcat/shared/classes/alfresco/web-extension/templates/org/alfresco/demo directory path. Then add the helloworldhome.ftl template file to it:
This is just a test page. Hello World!
page.helloworldhome.title=Hello World page.helloworldhome.description=Hello World Home DescriptionThis file just points to where the FreeMarker template for this page will be stored. We also need to tell Alfresco Share about the new resource file, rename the custom-slingshot-application-context.xml.sample to custom-slingshot-application-context.xml, it is located in the web-extension directory. Then define the following bean:
<bean id="org.alfresco.demo.resources" class="org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent">
<property name="resourceBundles">
<list>
<value>alfresco.web-extension.messages.helloworldhome</value>
</list>
</property>
</bean>
To test this page you will have to restart Alfresco. It can then be accessed
via the http://localhost:8080/share/page/helloworldhome. The page does not
look very exciting:
<#include "/org/alfresco/include/alfresco-template.ftl" />
<@templateHeader></@>
<@templateBody>
<@markup id="alf-hd">
<div id="alf-hd">
<@region scope="global" id="share-header" chromeless="true"/>
</div>
</@>
<@markup id="bd">
<div id="bd">
<h1>This is just a test page. Hello World!</h1>
</div>
</@>
</@>
<@templateFooter>
<@markup id="alf-ft">
<div id="alf-ft">
<@region id="footer" scope="global" />
</div>
</@>
</@>
What we are doing here is first bringing in another FreeMarker file called alfresco-template.ftl that contains, you guessed it, FreeMarker template macros. We then use these macros (elements starting with @) to set up the layout of the page with header and footer. The header and footer content is fetched via the share-header and footer global scope components (Web Scripts). To view the result of our change we need to restart the server again, after this we should see the following:
<#include "/org/alfresco/include/alfresco-template.ftl" />
<@templateHeader></@>
<@templateBody>
<@markup id="alf-hd">
<div id="alf-hd">
<@region scope="global" id="share-header" chromeless="true"/>
</div>
</@>
<@markup id="bd">
<div id="bd">
<@region id="body" scope="page" />
</div>
</@>
</@>
<@templateFooter>
<@markup id="alf-ft">
<div id="alf-ft">
<@region id="footer" scope="global" />
</div>
</@>
</@>
We have called the new region body and set page scope for it. This requires us to define a new component for this region. This can be done either in the page XML, or as a separate file in the site-data/components directory, we will do the latter. Create the components directory and add a file called page.body.helloworldhome.xml to it:
<?xml version='1.0' encoding='UTF-8'?> <component> <scope>page</scope> <region-id>body</region-id> <source-id>helloworldhome</source-id> <url>/components/helloworld/body</url> </component>
The component file names follow a naming convention: global | template | page>.<region-id>.[<template-instance-id | page-id>].xml The URL for this component points to a Web Script that will return the Hello World message. Start implementing it by creating a descriptor file called helloworld-body.get.desc.xml located in the alfresco/tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/demo directory:
<webscript>
<shortname>helloworldbody</shortname>
<description>Returns the body content for the Hello World page.</description>
<url>/components/helloworld/body</url>
</webscript>
Note that the URL is the same as we set in the component definition. Now implement the controller for the Web Script, create a file called helloworld-body.get.js in the same place as the descriptor:
model.body = "This is just a test page. Hello World! (Web Scripting)";
The controller just sets up one field in the model with the Hello World message. Now implement the template for the Web Script, create a file called helloworld-body.get.html.ftl in the same place as the descriptor:
<h1>${body}</h1>
Restart the server. Then access the page again, you should see the Hello World message change to "This is just a test page. Hello World! (Web Scripting)".
To summarize a bit, the following is a picture of all the files that were involved in creating this Surf page the old school way:
What you could do now is extend the Hello World page with some more sophisticated presentation using the YUI library. If you do that you end up with the pattern for how most of the old school Share pages have been implemented.
Next we will have a look at how to implement the same Hello World page the new way with Aikau [42].
Let's see how we can implement a Hello World page with the new Aikau framework.
The following steps are needed to add an Aikau Page:
OK, this might be a bit confusing, starting with a web script and then selecting a Surf page? If you have read through the Share architecture [76] page then you will remember that an Aikau page is based on a predefined Surf Page. So when you implement an Aikau page you are actually bypassing all the Site Data model stuff, and you go directly to the Web Script implementation that does the real job of fetching content and defining the presentation.
Start implementing the Aikau Page web script by creating a descriptor file called helloworld-aikau.get.desc.xml located in the alfresco/tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/demo directory:
<webscript>
<shortname>Hello World</shortname>
<description>Hello World page definition</description>
<family>Share</family>
<url>/helloworld</url>
</webscript>
Now implement the controller for the Web Script, create a file called helloworld-aikau.get.js in the same place as the descriptor:
model.jsonModel = {
widgets: [
{
id: "SET_PAGE_TITLE",
name: "alfresco/header/SetTitle",
config: {
title: "Hello World"
}
},
{
id: "DEMO_SIMPLE_MSG",
name: "example/widgets/HelloWorldTextWidget"
}
]
};
The controller is where the main work is done when it comes to implementing the layout of the page. If you do not need any custom widgets then it might even be the only major thing you need to implement to get the Aikau page up and running. Now implement the template for the web script, create a file called helloworld-aikau.get.html.ftl in the same place as the descriptor:
<@processJsonModel />
The template just kicks off the processJsonModel FreeMarker template macro, which will, as it says, process the JSON model and assemble the page components.
Our page model contains an example widget that we need to implement. It is specified to be at the example/widgets package path. Dojo is the JavaScript framework used behind the scenes, and we need to tell it about the new package path. This can be done via a Spring Surf Module extension. Create a file called example-widgets.xml and put it in the alfresco/tomcat/shared/classes/alfresco/web-extension/site-data/extensions directory:
<extension>
<modules>
<module>
<id>Example Aikau Widgets</id>
<version>1.0</version>
<auto-deploy>true</auto-deploy>
<configurations>
<config evaluator="string-compare" condition="WebFramework" replace="false">
<web-framework>
<dojo-pages>
<packages>
<package name="example" location="js/example"/>
</packages>
</dojo-pages>
</web-framework>
</config>
</configurations>
</module>
</modules>
</extension>
Now we can start implementing the Aikau Widget that should return the Hello World message. To do that we need to implement a new Dojo JavaScript class called HelloWorldTextWidget. The widget is pure client side resource stuff so we need to add the files involved into the exploded Share web app (this is just because we are not using a build project). Create a file called HelloWorldTextWidget.js and put it in the alfresco/tomcat/webapps/share/js/example/widgets directory:
define(["dojo/_base/declare",
"dijit/_WidgetBase",
"alfresco/core/Core",
"dijit/_TemplatedMixin",
"dojo/text!./HelloWorldTextWidget.html"
],
function(declare, _Widget, Core, _Templated, template) {
return declare([_Widget, Core, _Templated], {
templateString: template,
i18nRequirements: [ {i18nFile: "./HelloWorldTextWidget.properties"} ],
cssRequirements: [{cssFile:"./HelloWorldTextWidget.css"}],
buildRendering: function example_widgets_HelloWorldTextWidget__buildRendering() {
this.helloWorldMsg = this.message('hello.world');
this.inherited(arguments);
}
});
});
This widget is based on an HTML template defined in a file called HelloWorldTextWidget.html, create this file in the same place as the Widget class:
<div class="helloWorldMsgStyle">${helloWorldMsg}</div>
The widget also uses a property called hello.world that needs to be available in a resource file called HelloWorldTextWidget.properties, create it in the same place as the Widget class:
hello.world=This is just a test page. Hello World! (Aikau)
Finally the widget template uses a CSS style called helloWorldMsgStyle that needs to be available in a resource file called HelloWorldTextWidget.css, create it in the same place as the Widget class:
.helloWorldMsgStyle {
border: 1px #000000 solid;
padding: 1em;
width: 100px;
background-color:lightgrey;
}
Now restart Alfresco Content Services and then access the page with the http://localhost:8080/share/page/hdp/ws/helloworld URL. You should see the following page in Share:
The page we choose as a basis (that is, the Hybrid Dynamic Surf Page - hdp) provides both the header and the footer for the Share web application. If you want to see the page stand-alone you can use the dp page as a basis.
So when we are working with Aikau pages we do not have to bother about the Site Data model and all the different kinds of XML files. We just create a web script where the controller will contain the complete layout of the page. And then the page content will go into an auto-generated region on the Surf page we select.
Surf is a Spring framework extension for building new Spring framework applications or plugging into existing Spring web MVC (Model, View, Controller) applications. Spring Web MVC provides separation between the application Model, View, and Controller (known as MVC). You can use Surf with other popular Spring Web MVC technologies including Tiles, Grails, and Web Flow.
Surf's object model lets you define pages, templates, components, and themes using XML. The Spring application picks up new files and processes them through scripts and templates to produce the view, and writes scripts using server-side JavaScript and Groovy. Templates are written using FreeMarker. You can build both page-centric and content-centric websites using Surf, and it provides out-of-the-box support for rendering content delivered through content delivery services, such as CMIS, Atom, and RSS.
Semantic content represents the domain specific content that should be displayed on the web page. This can be for example project information,document information, customer information, discussion thread, wiki page data, workflow task information. This content is typically authored, approved, and published.
Semantic content describes what should be rendered. It contains the approved message but it does not contain any formatting information. It is represented in a structured data format, such as JSON or XML. The following code is an example of JSON text for a biography:{
"author": "Pablo Neruda",
"country": "Chile", "image": "pablo_neruda.jpg",
"description": "Pablo Neruda is adored in South America for his romantic prose.",
"popular_works": ["Cien sonetos de amor", "Confieso que he vivido"]
}
This code does not contain any formatting like HTML tags or other markup, just simple data. This type of content is usually fetched by a Spring Surf Web Script dynamically.
Presentation content are files that describe presentation configuration for a website, it is represented in XML and FreeMarker template files. Presentation content comprises configuration that tells the Surf rendering engine how the Web page or page component should look and feel.
A website presentation framework, such as Surf, looks to this content to figure out how to display the page. For example, the following XML code configures a Surf Web Script for rendering a biography to end users and tells the web script to render a link to the full article as well as to show the image of the author.
<component>
<url>/content/display/biography</url>
<properties>
<link-title-to-full-article>true</link-title-to-full-article>
<show-image>true</show-image>
</properties>
</component>
These properties are custom properties that are just passed on to the Web Script implementation. This component definition tells Surf to call this Web Script (i.e. /content/display/biography) to render the biography.
The end-to-end rendering flow is illustrated in the following figure.
The website user then sees the poet's content. Rending a complete Web page with more stuff then just the biography, such as title, footer, header etc, will loop through step 4 - 7 multiple times.
This means that Surf applications can consist of either single-tier or dual-tier applications. The following figure shows three valid configurations for Surf. The standalone configuration on the left shows, all the presentation and semantic content stored as part of the Surf web application. It is self-contained and has everything that it needs so that requests can be services entirely from the web application in the presentation tier. This is a perfectly acceptable configuration. Surf imposes no requirements, it does not require a database, any local persistence, or even a user session.
MVC applications use a dispatcher to handle requests for an application. It looks at the URL to determine which controller to invoke to set up a model, and then which view to invoke to render the model.
The dispatcher uses mappings (usually URL mappings) to determine which controllers to invoke for the incoming URL. It also uses mappings to figure out which view to invoke to render the response back. A controller contains business logic that should run before the response is generated. It can do things like query a database or call out to a service. Its job is to place this data into the model. A view contains rendering logic responsible for building the response that the end user receives. It looks to the data in the model to inform its rendering process.
The following figure illustrates the process:
The main benefit of the MVC pattern is that it clearly separates the business and rendering logic. This modularizes your application architecture, allowing you to plug in new views and new controllers. It provides reuse, as many views can share a single controller, or many controllers can share a single view.
Based on Spring configuration, Java beans implement controllers, views, the model, and the mappings between URIs and handlers. Spring Web MVC is very extensible, letting you write your own Java code, plug in new beans, or rewire things through configuration.
The dispatcher for a Spring Web MVC application is the dispatcher servlet, which handles the request, executes the MVC pattern, and tries to identify a controller to handle the incoming request. A controller is a Plain Old Java Object (POJO) registered with the Spring framework. In the Spring framework, the model is a simple map of named properties. The controller computes these, and when finished, hands the model back to the dispatcher servlet. The dispatcher servlet then tries to determine a view to use to render the model to the end user. It consults a registry of view resolvers and asks each of them if they can handle the incoming request URI. If it finds a matching view resolver, it is used to produce a view object, rendering the model to the end user.
Typically, Spring Web MVC application developers focus most of their effort writing controllers and views in Java, which are then wired together with Spring configuration XML.
You can define views of pages including specific pages, page formats, and page types.
http://localhost:8080/surf/<page-id>
http://localhost:8080/surf?p=<page-id>
If Surf finds this page, it looks at the page XML configuration to determine which template to use to render the output. Each page can have multiple templates keyed by format. A page might have a default template that it uses for HTML output to a browser, but it can have another template configured that it uses for output to a wireless device.
http://localhost:8080/surf/<page-id>?f=<format-id>
http://localhost:8080/surf?p=<page-id>&f=<format-id>
This allows you to have different markup for different intended formats, such as for small display devices or integration purposes. Surf pages are also locale aware. This lets you finely adjust your site’s pages for different languages and localization needs. When you make a request for a page, Surf will do its best to find a match for your browser’s locale. If a locale match cannot be made, Surf will fall back to a specified default locale.
http://localhost:8080/surf/pt/<page-type-id>
http://localhost:8080/surf?pt=<page-type-id>
Surf lets you group pages into page types. By requesting a page type, Surf will determine which page to use to satisfy your request. Surf defines a login page type. Your site might have two themes, such as a normal theme and a holiday theme. You can also have two distinct login pages, such as a normal login page and a holiday login page.
When the holiday theme is active, you would like Surf to resort to using the holiday login page. All you have to do is switch the theme for the site. None of the links or URLs change at all. The URLs in this example, will always take you to the theme’s designated login page.
http://localhost:8080/surf/pt/login
http://localhost:8080/surf?pt=login
As before, you can request a particular format of the login page type by using a format parameter. Here are two URLs that request the wireless format of the login page type.
http://localhost:8080/surf/pt/login?f=wirelesshttp://localhost:8080/surf?pt=login&f=wireless
When Surf looks at a URI and determines the request, it starts the process of handling the view. The request might be for a specific page, a content item of type “article”, or a specific region of the current page (for example, in an AJAX request). Regardless of the request, the objective will eventually produce markup and send it out to the response. The key to making this happen is the template, which provides the basic layout of the response to the browser.
The following figure shows three pages for a sample website. Two of the pages are similar with the same page layout. They have four regions on the page, whereas the first page has only three regions. As such, you can describe these three pages with two templates. The templates are shown underneath the pages.
The first template defines three regions with placeholder names (HEADER, BODY, FOOTER). The second template defines four regions (HEADER, MENU, CONTENT, FOOTER). The HEADER and FOOTER regions are common across all three pages. You can define the two templates in Surf and define regions along with region scope to allow reuse across templates, as illustrated in the following figure.
In this figure, the region scope defines the entire website with only two templates and five scoped regions. There are three scopes: global, template, and page. Regions in the global scope need to be configured only once. Then, their configuration is reused by any templates or pages that include them. In this case, the HEADER and FOOTER regions are defined once in the global scope. Their content appears the same on all of the pages of the site.
Regions in the template scope need to be configured once per template. Any pages that use the template then reuse their configuration. In this case, the MENU region is defined in the template scope for one of the templates, but not the other. Thus, the two pages on the right side that use this template will have the MENU region in common. Regions in the page scope must be configured once per page, and their configurations are not reused. In this case, the BODY and CONTENT regions are in the page scope. This allows the two right-hand pages to be slightly different, but only in the CONTENT region.
The region tag defines regions on a template with the scope, such as page, template, or global. The following examples show how this is done in FreeMarker:
Globally scoped header region: <@region id="header" scope="global" /> Template scoped navigation region: <@region id="navigation" scope="template" /> Page scoped content region: <@region id="content" scope="page" />
A template defines the basic structure of the rendered view, and then defines regions into which to include additional presentation. The following figure shows an example of the template that defines four regions: HEADER, MENU, CONTENT, and FOOTER. Sample code after the figure suggests how you could weave this into a FreeMarker template. It is up to Surf to resolve what to place in each of these regions when the template is rendered.
<html>
<head>
${head}
</head>
<body>
<div class="header">
<@region id="header" scope="global" />
</div>
<div class="menu">
<@region id="menu" scope="template" />
</div>
<div class="content">
<@region id="content" scope="page" />
</div>
<div class="footer">
<@region id="footer" scope="global" />
</div>
</body>
</html>
When the template is processed, each of its region tags executes and attempts to look up something that should be included in that location in the template. The region tag is replaced by the output of something that is bound into that place in the template.
Templates and scoped regions make it possible to reuse web scripts. You can have as many web scripts as you like, each encapsulating a unique bit of application functionality.
For example:
A template brings several web scripts together into an overall markup structure. Here, you are rendering a page; however, the same concepts apply for any kind of view rendered from Surf using a template. Surf lets you define regions in various scopes and then resolves these upon request. This makes your site definition efficient and easier to manage by promoting reuse. Alfresco Share is an example of a Surf application whose pages are constructed through reuse of templates. All three scopes are used. The following figure provides an example of how this fits together.
You can make changes to Alfresco Share pages by tweaking FreeMarker templates and web scripts. In Surf, web scripts not only provision remote interfaces to your applications, but also provide your application's presentation logic. These are presentation tier web scripts. Surf orchestrates them so they can all live together on a single view and interoperate against a common request context.
There are many more capabilities, such as pre-processing controllers to generate markup that should be injected into different parts of a page (for example, the <head> of an HTML page). Surf also provides additional web script and template API root-scoped objects and methods.
Presentation content consists of templates, scripts, and XML files that Surf can pick up without a server restart.
Surf consults presentation content when it renders the user interface. Surf's presentation content consists of three kinds of files:
Objects describe things like pages, page hierarchy, chrome, or components that are reused across many pages. XML files define objects that are generally short. A single Surf application will have many XML files to define its objects. When Surf starts up, it looks for all these small XML fragments and gathers them to form a complete registry of all of the objects.
Example of the XML for a Page object:
<?xml version='1.0' encoding='UTF-8'?>
<page>
<id>mypage</id>
<title>My First Page</title>
<description>This is an example of the XML for a Page</description>
</page>
A Spring project generally maintains these XML files as part of its project resources. They can reside under the WEB-INF directory or inside the classpath. Users can also manage these files inside the Alfresco Content Services server, where XML files can be individually managed, authorized, and approved as part of a lifecycle process. Once approved, these files are available to the Surf application.
This markup is generally HTML for a website. Templates are applied to the current request context or model. Templates are often files that contain a composite of the output markup and processing tags. The tags execute and generate markup that is injected into the template at the location of the tag. This pattern is common for template types such as FreeMarker, PHP, and XSL.
Surf supports several useful tags out of the box. One commonly used tag is the region tag, which tells the template to look up a component and render its output at the location of the tag.
Here is an example of what a FreeMarker template responsible for rendering a page looks like in Surf:
<html>
<head>
${head}
</head>
<body>
<div class="header">
<@region id="header" />
</div>
<div class="body">
<@region id="body" />
</div>
</body>
</html>
A Spring project generally maintains these template files as part of its project resources. They can reside under the WEB-INF directory or inside the classpath. Users can also manage these files inside a content application server.
Surf lets you reuse web scripts and bind them together into unlimited numbers of pages. The scripts are lightweight, making them easy to assemble and deploy.
Declarative web scripts implement a Model-View-Controller pattern. They have a single descriptor XML file that tells the web script dispatcher how to behave. Declarative web scripts have their own template views and optional scriptable controllers. You write new views by writing new template files. You write new controllers by writing new script files. Your scriptable controllers populate the model variable (a map). Your view uses the model during render. Surf allows you to merge your web scripts into the rendering of the overall page. that is, Surf lets your web script MVC participate in the overall Spring MVC.
Surf provides each web script with the appropriate context and runtime environment to render in the context of the overall request. The output of each web script merges with the output of the template to form the final markup. This markup is returned from the Spring MVC view.
For example:
Rather than produce 100% of the output itself, the rendering template occasionally delegates work to the web script runtime when the region tags execute. The web script runtime executes miniature, scriptable MVC processes whose output merges into the overall rendition. The web script runtime can use and take advantage of the full request, user, and page context. You can build web scripts to define component implementations that can be accessed either standalone or stitched into an overall page presentation. A component can be like a widget or a gadget; something that you can plug into a website on one or more pages as a reusable bit of application functionality that participates in the overall page experience.
Web scripts can also be invoked standalone in that they can run outside the context of a page. You can surface components in menus or refresh portions of a web page using AJAX callbacks. Surf also provides portlet capabilities that wrap web scripts and components as JSR-268 portlets and dropped into portal servers.
A Spring project generally maintains web script files as part of its project resources. They could reside under the WEB-INF directory or inside the classpath. Users can also manage these files inside a content application server.
Web script developers often work with remote sources of data. Surf makes it easy to reach out to these information sources and pull together feeds of data.
These data sources are typically RESTful providers, CMIS repositories, or proprietary in nature. Furthermore, each data source might require a unique set of credentials to work with the data source.
Surf lets you define connectors responsible for communicating with endpoints where a data source lives, such as a server residing at an HTTP address. Connectors connect to an endpoint and communicate with it.
Connectors are wired together with authenticators so that they can effectively handshake and establish credentials with endpoints. This pattern abstracts away any of the manual management of connection state that you would otherwise need to perform. Using authenticators, connectors manage user identity and session state to the endpoint. This is automatically managed for the duration of the user session in the Surf application itself.
Connectors and endpoints are both defined through simple configuration as part of Surf's remote configuration block.
Declaring an endpoint is fairly simple. It will look something like this:
<config evaluator="string-compare" condition="Remote">
<remote>
<endpoint>
<id>springsurf</id>
<name>Alfresco Surf</name>
<connector-id>http</connector-id>
<endpoint-url>http://www.springsurf.org</endpoint-url>
</endpoint>
</remote>
</config>
This defines an endpoint named springsurf. When talking to this endpoint, a connector of type http should be used. The data source lives at www.springsurf.org:8080. Since nothing else is provided, this is assumed to be an unauthenticated endpoint.
Surf provides a number of out-of-the-box connectors. The http connector lets you connect to HTTP or HTTPS endpoints. To assert an identity to the endpoint, you can adjust the configuration:
<config evaluator="string-compare" condition="Remote">
<remote>
<endpoint>
<id>springsurf</id>
<name>Alfresco Surf</name>
<connector-id>http</connector-id>
<endpoint-url>http://www.springsurf.org</endpoint-url>
<identity>declared</identity>
<username>USERNAME</username>
<password>PASSWORD</password>
</endpoint>
</remote>
</config>
The credentials for an http connector are passed through using basic authentication. The values USERNAME and PASSWORD are just placeholders for your own values. With an endpoint defined, you can code against the endpoint and use it without worrying about managing connection state and asserting credentials. You could use the following Web script controller code to retrieve something from the springsurf endpoint:
// get a connector to the springsurf endpoint
var connector = remote.connect("springsurf");
// place text file into the model
var txt = connector.get("/sample/helloworld.txt");
model.txt = txt;
The remote root-scope variable provides various methods and accessors for working with connectors. When it is used, the connection mechanics are abstracted away and your web script code becomes highly portable from one environment to another, as well as reusable across many users.
Surf provides credential management on behalf of users who access content using connectors. If a connector needs to know which credentials to attach to a given request during an authentication handshake, it can call upon the credential vault.
Surf's default credential vault is runtime-only; it is populated and used at runtime. If you restart the server, the credentials are lost and the user must provide their credentials again the next time the connector is used. Surf lets you override the credential vault implementation. It provides a number of additional credential vaults out of the box you can use or base your implementations on. These include a filesystem– persistent credential vault and a credential vault (where your credentials are stored in an Alfresco Content Services-managed file).
To use the credential vault, you inform the endpoint that its identity is driven from the current user. You can make this change to your endpoint definition:
<config evaluator="string-compare" condition="Remote">
<remote>
<endpoint>
<id>springsurf</id>
<name>Alfresco Surf</name>
<connector-id>http</connector-id>
<endpoint-url>http://www.springsurf.org</endpoint-url>
<identity>user</identity>
</endpoint>
</remote>
</config>
Connectors to this endpoint will look for the user’s credentials in the credential vault. If credentials are not found and the endpoint requires authentication, the connection can fail. However, if credentials are available in the vault, they will be applied and the connector will access the endpoint on behalf of the developer without the need for manual login.
Authenticating connectors are connectors that have authenticators plugged into them. An authenticator is a class that knows how to perform an authentication handshake with a specific kind of service or application.
For example, MediaWiki provides a REST-based means for authenticating. You pass in your user credentials and it hands back an HTTP cookie. This cookie must be applied to every subsequent request, as MediaWiki looks to it to inform the application of who is making the request.
Alfresco Content Services has a similar REST-based means for authenticating. It is slightly different in that the RESTful parameters are not the same as those of MediaWiki. Also, Alfresco Content Services hands back a ticket in an XML return payload. This ticket must be applied to the HTTP headers of every subsequent call so that Alfresco Content Services knows who is making the request. Every application has a slightly different way of handling its authentication. For this reason, Surf makes it easy to write your own authenticators and plug them into your connectors entirely through configuration.
You define authenticators through configuration as well:
<authenticator>
<id>alfresco-ticket</id>
<name>Alfresco Authenticator</name>
<description>Alfresco Authenticator</description>
<class>org.alfresco.connector.AlfrescoAuthenticator</class>
</authenticator>
You can then bind them to connectors using configuration, or you can write your own connectors:
<connector>
<id>alfresco</id>
<name>Alfresco Connector</name>
<description>Connects to Alfresco using ticket-based authentication</description>
<class>org.alfresco.connector.AlfrescoConnector</class>
<authenticator-id>alfresco-ticket</authenticator-id>
</connector>
The alfresco-ticket authenticator and the alfresco connector are both available to Surf developers out of the box to connect to an Alfresco Content Services instance. All you need to do is define an endpoint that points to an Alfresco Content Services instance and uses the alfresco connector. Alfresco Content Services connectors use an authenticator to perform a handshake ahead of any actual interaction. The handshake establishes who the user is and then sets up the connector session so that subsequent requests contain the appropriate connection information (cookies, request headers, and so forth). The endpoint definition looks like this:
<endpoint>
<id>alfresco</id>
<name>Alfresco REST API</name>
<description>Alfresco REST API</description>
<connector-id>alfresco</connector-id>
<endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
<identity>user</identity>
</endpoint>
This endpoint is named alfresco. It uses an alfresco connector and will draw credentials from the user’s credential vault. This is all defined in configuration. You could use the alfresco endpoint to talk to an Alfresco Content Services instance and access its remote API. For example, you can interact with the CMIS API on the repository. Here is an example of retrieving XML from the CMIS API:
// get a connector to the alfresco endpoint
var connector = remote.connect("alfresco");
// place CMIS text onto the model
model.cmis = connector.get("/api/path/workspace/SpacesStore");
By simply coding to the remote object, you do not need to worry about how to connect to the endpoint or pass along user state.
The remote root-scoped object lets you connect to remote services and retrieve data feeds.
The basic pattern is to use the remote object to get a connector to a specific endpoint, which is identified by endpoint ID. For example:
var connector = remote.connect(ENDPOINT_ID);
By filling in ENDPOINT_ID with the correct value, you have a connector to the remote service. The connector variable is an object with additional methods describing all the ways you can work with the endpoint.
The following methods are the basic HTTP method types that support the essential CRUD (create, read, update, delete) operations of most RESTful services. You can use these to work with services right within your web scripts.:
In the following sections you will see that two locations are specified:
It's important to note that the alfresco/web-extension/site-data directory will be processed after the alfresco/site-data directory. Usually core Alfresco Content Services objects would be located in alfresco/site-data directory, and third-party overrides/extensions would be located in alfresco/web-extension/site-data.
<component>
<!-- Required -->
<scope>page | template | global</scope>
<region-id>REGION_ID</region-id>
<source-id>SOURCE_ID</source-id>
<!-- Optional -->
<url>URL</url>
<component-type-id>COMPONENT_TYPE_ID</component-type-id>
<chrome>CHROME_ID</chrome>
</component>
This component binds the web script with the URL /sample/content to the paged-scoped region named content on the page home. It therefore has the ID page.content.home.
classpath:/alfresco/web-extension/site-data/compnents/page.content.home.xml
<?xml version="1.0" encoding="utf-8"?>
<component>
<id>page.content.home</id>
<scope>page</scope>
<region-id>content</region-id>
<source-id>home</source-id>
<url>/sample/content</url>
</component>
This example binds the web script with the URL /sample/header to the template-scoped region named header on the home template. It therefore has the ID template.header.home.
classpath:/alfresco/web-extension/site-data/compnents/template.header.home.xml
<?xml version="1.0" encoding="utf-8"?>
<component>
<id>template.header.home</id>
<scope>template</scope>
<region-id>header</region-id>
<source-id>home</source-id>
<url>/sample/header</url>
</component>
This example binds the web script with the URL /sample/footer to the global-scoped region named footer. It therefore has the ID global.footer.
classpath:/alfresco/web-extension/site-data/compnents/global.footer.xml
<?xml version="1.0" encoding="utf-8"?>
<component>
<id>global.footer</id>
<scope>global</scope>
<region-id>footer</region-id>
<source-id>global</source-id>
<url>/sample/footer</url>
</component>
This example binds the web script with the URL /sample/content to the page-scoped region named content on the page home. It informs Surf to wrap the Component with a custom component Chrome when it renders. It also provides a few custom properties that the web script can use while it executes
classpath:/alfresco/web-extension/site-data/compnents/page.content.home.xml
<?xml version="1.0" encoding="utf-8"?>
<component>
<id>page.content.home</id>
<scope>page</scope>
<region-id>content</region-id>
<source-id>home</source-id>
<url>/sample/content</url>
<chrome>sample-chrome</chrome>
<properties>
<view>FULL</view>
<style>formal</style>
</properties>
</component>
<configuration>
<source-id>SOURCE_ID</source-id>
</configuration>
The following file defines the Surf site configuration. It describes a Configuration object that is bound to the site source ID.
classpath:/alfresco/web-extension/site-data/configurations/default.site.configuration.xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<title>My Web Site</title>
<source-id>site</source-id>
<properties>
<root-page>welcome</root-page>
</properties>
</component>
Pages can specify whether they require user authentication before rendering. Unauthenticated users will not be able to render the page.
Pages also have optional types that allow them to be dispatched by page type rather than Page ID. Pages have one or more template instances associated with them. This allows them to render distinctly for different intended output formats (for example, HTML, PDF, or wireless).
<page>
<!-- Optional authentication setting -->
<authentication>none | user</authentication>
<!-- Optional page type ID (otherwise assumes generic) -->
<page-type-id>PAGE_TYPE_ID</page-type-id>
<!-- Use this to associate a default template -->
<template-instance>TEMPLATE_ID</template-instance>
<!-- Use this to associate a template to this page for a given format -->
<template-instance format="FORMAT_ID">TEMPLATE_ID</template-instance>
</page>
The following file defines a page called "products". Only authenticated users are allowed to access the page. When the page is asked to render in the default format, it looks to the template instance with the ID landing1. When the page is asked to render in the print format, it looks to the template instance with the ID landing1-print.
Were you to set up the landing1-print template, you would be able to request the print format for this page using the following URL:
http://localhost:8080/webapp/page/products?f=print
classpath:/alfresco/web-extension/site-data/pages/products.xml
<?xml version="1.0" encoding="utf-8"?>
<page>
<id>products</id>
<title>Products Page Title</title>
<description>Products Page Description</description>
<authentication>user</authentication>
<template-instance>landing1</template-instance>
<template-instance format="print">landing1-print</template-instance>
</page>
For simple cases where the template instance is not required to store additional configuration, it may remain a very lightweight pointer to the template file. For more advanced cases, the template instance may store render-time information concerning how to lay out elements on the page.
<template-instance>
<template-type>TEMPLATE_TYPE_ID</template-type>
</template-instance>
classpath:/alfresco/web-extension/site-data/template-instances/landing1.xml
<?xml version="1.0" encoding="utf-8" ?>
<template-instance>
<id>landing1</id>
<template-type>landing</template-type>
<properties>
<columns>2</columns>
<rows>3</rows>
</properties>
</template-instance>
When the framework needs to render a template instance, it considers the template type and merges its properties forward. The uri of the template instance overrides the uri of the template type.
<template-type>
<!-- Required "view" processor -->
<processor mode="view">
<id>PROCESSOR_ID</id>
<!-- Optional Uri -->
<uri>PROCESSOR_URI</uri>
</template-type>
The following file defines a template type that is used by template instances to invoke the FreeMarker processor.
classpath:/alfresco/web-extension/site-data/template-types/freemarker.xml
<?xml version="1.0" encoding="utf-8" ?>
<template-type>
<id>freemarker</id>
<title>FreeMarker Template Type</title>
<processor mode="view">
<id>freemarker</id>
</processor>
</template-type>
A theme captures default settings for the rendering framework. Different themes can have different rendering behaviors.
In the following sections you will see that two locations are specified:
<theme>
<!-- Optional page type overrides -->
<page-types>
<page-type>
<id>PAGE_TYPE_ID</id>
<page-id>PAGE_ID</page-id>
</page-type>
</page-types>
</theme>
The following file defines a theme that overrides the login page type to include a different default page. When this theme is used, Surf will render back the default-login-page Page when the login page type is requested.
classpath:/alfresco/web-extension/site-data/themes/default.xml
<?xml version="1.0" encoding="utf-8"?>
<theme>
<id>default</id>
<page-types>
<page-type>
<id>login</id>
<page-id>default-login-page</page-id>
</page-type>
</page-types>
</theme>
Specific information:
One of the problems that has affected upgrades of Alfresco Content Services in the past is that the end-user's browser can end up using cached copies of JavaScript and CSS files that have been updated during the upgrade. Surf has a service called the "DependencyHandler" which solves this specific problem.
The approach taken is to append a unique checksum to the end of each requested JavaScript and CSS dependency, where the checksum is generated from the contents of the file. If file content is changed the checksum generated will be different. The checksum associated with the file is cached for the lifecycle of the web server - this means that it does not need to be generated for each request. Surf performance has actually been enhanced by this mechanism because Surf also caches the location from which the dependency was retrieved Surf can retrieve dependencies from a number of different locations, for example, JAR files, class path, file system, remote location, and so on.
This feature is enabled by default in the webapps/share/WEB-INF/surf.xml file:
<web-framework> ... <use-checksum-dependencies>true</use-checksum-dependencies> ... </web-framework>
In order to make use of the Dependency Handler you will need to use the <@script>, <@link> and <@checksumResource> FreeMarker directives in your template instance and web script files, for example:
<@script src="${url.context}/res/yui/yahoo/yahoo.js"></@script>
<@link rel="stylesheet" type="text/css" href="${url.context}/res/css/base.css" />
<@checksumResource src="${url.context}/res/css/ipad.css"/>
These examples are taken from the resources.get.html.ftl file where the ${url.context} is a FreeMarker variable set to the application context, for example share.
The Dependency Handler is capable of dealing with production (minified) and debug versions of files. The Spring application context configuration for the bean allows you to specify the different file suffices that can be used for both production and debug versions and the Dependency Handler will work through the different suffices until it finds a matching file. This means that Surf will always be able to fall back to the debug version of the code if a minified version does not exist. By default the debug suffices are:
The production suffices are:
You can change these suffices by overriding the definition for the dependency.handler bean in the Spring application context in case you want to add, remove or re-order the default entries.
The current limitation of this solution is that it only works with static requests from the page and not dynamic requests made from a script. However, many JavaScript libraries provide their own solution to this problem (for example TinyMCE).
Much of the performance hit associated with a browser loading a web page comes from the multiple HTTP Requests (and returns) that are required to load multiple resources required by the page, particularly image files. One solution to this is to combine the images into a so called CSS Sprite - this means that a single HTTP request is then required for a page with multiple images. CSS is then used to locate sub-sections of the CSS Sprite on the web page. While this provides a performance boost, especially for image rich pages, it still requires an HTTP request to obtain the CSS Sprite file. Also, the technique requires some preparation on the part of the web page developer.
An alternative to the CSS Sprite is to use Data URIs. Data URIs effectively allow data to be embedded within the CSS stylesheet itself. This data can be image data. The advantage of this approach is that no additional HTTP Requests are required for images beyond the one to fetch the CSS stylesheet itself. This represents an additional performance boost, and is more convenient for the web page developer, as it does not require the potentially tricking positioning code required by the CSS Sprite approach (although in practice this is somewhat alleviated by web page design tools).
While it might seem that embedding image data into a CSS file has the potential to make CSS files unweildy, the image data is typically Base64 encoded and gzipped to make it far more compact.
With regards Share, while the CSS Sprite could be applied to Share pages, it has the potential to break existing Share customizations, so this appraoch is not used in Share. The approach taken instead is to use the Data URI approach to embed images in CSS stylesheets.
Surf can now automatically produce CSS data images by simply adding the following line to its configuration file. For Share this configuration file is located in webapps/share/WEB-INF/surf.xml.
<web-framework>
...
<generate-css-data-images>true</generate-css-data-images>
...
</web-framework>
Providing that checksum dependencies are also enabled [100] then all images reference by CSS files will be embedded as data within those CSS files. In addition to eliminating HTTP requests for images, when an image changes, the CSS checksum will change so the browser will not use stale cached images. The Dependency Handler service defers some of this work to a dedicated CssDataImage service which can be overridden in the Spring application context if required. All images are cached for the life-cycle of the server so that performance is not impeded when requesting the same image multiple times.
This information expands on FreeMarker template attributes and directives.
The documentlist.get.html.ftl template uses the group attribute in the <@link>, <@script>, <@inlineScript> and <@createWidgets> directives. This attribute determines the order in which dependency requests and JavaScript code are output into the rendered HTML page.
Surf supports the ability to aggregate multiple files into a single resource to reduce the number of HTTP requests made by the client, in order to increase page loading performance. The group attribute is used to determine how dependencies are aggregated into the generated resources. Managing the groups is important because once generated a resource is cached on the server to improve response times for subsequent requests. If a single group were to be used then only one HTTP request would be made per page, but the performance gained through reduced requests would be lost to server side aggregation for each request.
In order for the same Share code to be able to support different Surf operation modes the group attribute is also applied when processing individual dependency requests. Groups are output in the order they are requested and all the dependency requests and code are output for each group in turn.
By way of example, for the following HTML:
<@script src="/aaa.js" group="1"/> <@script src="/bbb.js" group="2"/> <@script src="/ccc.js" group="3"/> <@script src="/ddd.js" group="2"/> <@script src="/eee.js" group="1"/>
The output is:
<script src="/aaa.js"></script> <script src="/eee.js"></script> <script src="/bbb.js"></script> <script src="/ddd.js"></script> <script src="/ccc.js"></script>
Note that /eee.js is the second requested import despite appearing last in the list and that /ccc.js is last despite it appearing 3rd. This is because all of group "1" is output before any of group "2", and all of group "2" is output before group "3".
Given files A.js and B.js and a WebScript template containing the following:
<@script src="${url.context}/res/A.js" group="calc"/>
<@inlineScript group="calc">
// A comment between imports
</@>
<@script src="${url.context}/res/B.js" group="calc">
When the final page is rendered in the source you would see an import like this:
<script type="text/javascript" src="/share/res/A.js"></script>
<script type="text/javascript">//<![CDATA[
// A comment between imports
//]]></script>
<script type="text/javascript" src="/share/res/B.js"></script>
Note that the JavaScript from the <@inlineScript> directive is placed between the two imports because they are in the same group. The same is true for any custom directive that outputs JavaScript, for example the <@createWidgets> directive.
To enable the use of aggregate dependencies you will need to make a Surf configuration change. By default the capability is disabled in Surf and is unlikely to ever enabled by default in future releases of Alfresco Content Services.
To enable it you set the following line within the Surf configuration file, webapps/share/WEB-INF/surf.xml:
<web-framework>
…
<aggregate-dependencies>true</aggregate-dependencies>
…
</web-framework>
If you do enable dependency aggregation then you can expect the following behaviour to occur. If the file A.js contains:
var a = 1;
and the file B.js contains:
var c = a + b;
and you have a WebScript template containing the following:
<@script src="${url.context}/res/A.js" group="calc"/>
<@inlineScript group="calc">
var b = 1;
</@>
<@script src="${url.context}/res/B.js" group="calc">
When the final page is rendered in the source you would see an import like this:
<script type="text/javascript" src="/share/res/20146f7250123ea2437a0d16d5c323.js"></script> <!-- Group Name: "calc" -->
The source of that file would contain:
var a = 1; var b = 1; var c = a + b;
The resource name is an MD5 checksum generated from the combined source code. The generated resource is cached on the server so that it doesn't need to be generated each time. If extra content is added to the group (even dynamically by a module) then the resource will be regenerated and the checksum will naturally change to ensure that the browser requests a different file.
The <client-debug> setting located in webapps/share/WEB-INF/classes/alfresco/share-config.xml, will work when enabled, even when using aggregation. An aggregated resource will still be produced but each aggregated file will be separated by a comment similar to the following:
/*Path=A.js*/
This will allow you to determine the source file in which errors occur when debugging.
Previous versions of Alfresco Share relied on the use of the ${head} FreeMarker model property to output all the dependency requests generated on the first pass of all the web script *.head.ftl files. This property is populated during this first pass and then output in <head> HTML element defined in the alfresco-template.ftl template. Current code also contains a reference to that property, as this is used to support legacy *.head.ftl files and dependencies defined through any <dependencies> elements in extension module configuration. There are also two new directives: <@outputJavaScript/> and <@outputCSS/>.
As their names suggest these directives are used to output the JavaScript and CSS dependency requests made by using the <@link>, <@script>, <@inlineScript>, and <@createWidgets> directives. The output directives act as placeholders in extensibility model and accumulate requests to output content as the remainder of the Surf page is processed - only when the page has completely been processed is their final content rendered into the output stream.
Towards the end of the alfresco-template.ftl file you will also see a commented out directive <@relocateJavaScript>. The purpose of this directive is to change the location in the page where JavaScript output is rendered. It is suggested to move JavaScript to the end of a page to increase page performance. It is only possible to use this directive if there is no hard-coded <script> elements on the page that depend on imported files or JavaScript dependencies output by using the ${head} property. When uncommented though you will see that it produces a very clean source file for your page with all the JavaScript located at the end. The <@relocateJavaScript> directive is available should you wish to use to in custom Surf pages.
The two main categories of API that are available to use when interacting with the Alfresco Repository is the remote and the embedded APIs.
Remote APIs
The main remote Application Programmaing Interface (API) is the Alfresco ReST API [14], which should be the first place you go to when you want to interact with the Alfresco Repository remotely. If portability is very important, than have a look at the CMIS ReST API [21], which is a standard implemented by many ECM vendors.
Embedded APIs
The embedded APIs have traditionally been used a lot to build customizations that run inside the same JVM as the Alfresco Repository. There are both a Public Java API [101] and a Repository JavaScript API [102]. Before using the embedded APIs a thorough investigation should be done to rule out the possibility of building the extension with a remote a remote API. It is not recommended to build embedded extensions unless it is absoutely necessary. They make it difficult during upgrades and can quite easily have unintended side effects on core repository functionality, such as file upload.
For an overview of all APIs navigate to this page [11].
Links:
[1] https://docs.alfresco.com/../concepts/dev-system-arch-platform.html
[2] https://docs.alfresco.com/../concepts/dev-system-arch-web-ui.html
[3] https://docs.alfresco.com/../concepts/api-about.html
[4] https://docs.alfresco.com/../concepts/dev-arch-overview.html
[5] https://docs.alfresco.com/../concepts/dev-platform-arch.html
[6] https://docs.alfresco.com/../concepts/content-modeling-about.html
[7] https://docs.alfresco.com/../concepts/dev-protocols.html
[8] https://docs.alfresco.com/../concepts/spring-fw-modularity.html
[9] https://docs.alfresco.com/../concepts/alfresco-arch-about.html
[10] https://docs.alfresco.com/dev-platform-extension-points.html
[11] https://docs.alfresco.com/dev-api-intro.html
[12] https://docs.alfresco.com/../references/dev-extension-points-content-model.html
[13] http://dev.alfresco.com/resource/AlfrescoOne/5.0/PublicAPI/
[14] https://docs.alfresco.com/../pra/1/topics/pra-welcome.html
[15] https://docs.alfresco.com/../references/dev-extension-points-actions.html
[16] https://docs.alfresco.com/process-services1.10/topics/developmentGuide.html
[17] https://docs.alfresco.com/admintools-cmm-intro.html
[18] https://docs.alfresco.com/troubleshoot-webdav.html
[19] https://docs.alfresco.com/fileserv-ftp-intro.html
[20] https://docs.alfresco.com/aos/concepts/aos-intro.html
[21] https://docs.alfresco.com/../pra/1/topics/cmis-welcome.html
[22] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=cmis
[23] https://docs.alfresco.com/imap-intro.html
[24] https://docs.alfresco.com/email-intro.html
[25] https://docs.alfresco.com/../concepts/dev-system-arch-web-ui-app-dev.html
[26] https://docs.alfresco.com/../concepts/dev-extensions-share-architecture-extension-points.html
[27] https://docs.alfresco.com/../concepts/dev-system-arch-web-ui-app-dev-adf.html
[28] https://docs.alfresco.com/../concepts/dev-system-arch-web-ui-app-dev-js-api.html
[29] https://github.com/Alfresco/alfresco-ng2-components
[30] https://alfresco.github.io/adf-component-catalog/
[31] https://alfresco.github.io/adf-component-catalog
[32] https://github.com/Alfresco/alfresco-js-api
[33] https://github.com/Alfresco/generator-ng2-alfresco-app
[34] http://yeoman.io
[35] https://docs.alfresco.com/dev-extensions-share-extension-points-introduction.html
[36] https://docs.alfresco.com/surf-fwork-intro.html
[37] https://docs.alfresco.com/../references/surf-object-xml-reference.html
[38] https://docs.alfresco.com/../references/surf-object-xml-reference-page.html
[39] https://docs.alfresco.com/../references/surf-object-xml-reference-component.html
[40] https://docs.alfresco.com/../references/surf-object-xml-reference-template-instance.html
[41] https://docs.alfresco.com/dev-extensions-share-architecture-extension-points-intro-surf-pages.html
[42] https://docs.alfresco.com/dev-extensions-share-architecture-extension-points-intro-aikau-pages.html
[43] https://docs.alfresco.com/dev-extensions-share-configuration.html
[44] https://docs.alfresco.com/dev-extensions-share-form-controls.html
[45] https://docs.alfresco.com/dev-extensions-share-form-filters.html
[46] https://docs.alfresco.com/dev-extensions-share-form-field-validation-handlers.html
[47] https://docs.alfresco.com/dev-extensions-share-evaluators.html
[48] https://docs.alfresco.com/dev-extensions-share-site-presets.html
[49] https://docs.alfresco.com/dev-extensions-share-themes.html
[50] https://docs.alfresco.com/dev-extensions-share-doclib-actions.html
[51] https://docs.alfresco.com/dev-extensions-share-surf-extension-modules.html
[52] https://docs.alfresco.com/dev-extensions-share-surf-web-scripts.html
[53] https://docs.alfresco.com/dev-extensions-share-surf-web-script-js-root-objects.html
[54] https://docs.alfresco.com/dev-extensions-share-surf-pages.html
[55] https://docs.alfresco.com/dev-extensions-share-surf-dashlets.html
[56] https://docs.alfresco.com/dev-extensions-share-surf-widgets.html
[57] https://docs.alfresco.com/dev-extensions-share-aikau-menus.html
[58] https://docs.alfresco.com/dev-extensions-share-aikau-pages.html
[59] https://docs.alfresco.com/dev-extensions-share-aikau-dashlets.html
[60] https://docs.alfresco.com/dev-extensions-share-aikau-widgets.html
[61] https://docs.alfresco.com/dev-extensions-share-override-ootb-surf-pages.html
[62] https://docs.alfresco.com/dev-extensions-share-override-ootb-surf-dashlets.html
[63] https://docs.alfresco.com/dev-extensions-share-override-ootb-surf-widgets.html
[64] https://docs.alfresco.com/dev-extensions-share-override-ootb-aikau-pages.html
[65] https://docs.alfresco.com/dev-extensions-share-override-ootb-aikau-dashlets.html
[66] https://docs.alfresco.com/dev-extensions-share-override-ootb-aikau-widgets.html
[67] https://docs.alfresco.com/dev-extensions-share-override-ootb-surf-webscripts.html
[68] https://docs.alfresco.com/../concepts/dev-extensions-share-architecture-extension-points-intro-surf-pages.html
[69] https://docs.alfresco.com/../concepts/dev-extensions-share-architecture-extension-points-intro-aikau-pages.html
[70] https://docs.alfresco.com/../concepts/surf-fwork-intro.html
[71] https://docs.alfresco.com/../concepts/dev-extensions-share-advanced-surf-topics.html
[72] http://spring.io/
[73] http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html
[74] https://dojotoolkit.org/
[75] https://github.com/dojo/dijit
[76] https://docs.alfresco.com/dev-extensions-share-architecture-extension-points.html
[77] https://docs.alfresco.com/../concepts/surf-types-of-content%28replace-surf-concepts%29.html
[78] https://docs.alfresco.com/../concepts/surf-content-delivery.html
[79] https://docs.alfresco.com/../concepts/surf-mvc.html
[80] https://docs.alfresco.com/../concepts/spring-web-mvc.html
[81] https://docs.alfresco.com/../concepts/surf-view-fwork-intro.html
[82] https://docs.alfresco.com/../concepts/surf-pres-content.html
[83] https://docs.alfresco.com/../concepts/surf-connectors-intro.html
[84] https://docs.alfresco.com/../tasks/surf-page-view.html
[85] https://docs.alfresco.com/../concepts/surf-templates-regions.html
[86] https://docs.alfresco.com/../concepts/surf-components.html
[87] https://docs.alfresco.com/../concepts/surf-objects.html
[88] https://docs.alfresco.com/../concepts/surf-templates.html
[89] https://docs.alfresco.com/../concepts/surf-webscripts.html
[90] https://docs.alfresco.com/../concepts/surf-connectors-endpoints.html
[91] https://docs.alfresco.com/../concepts/surf-credentials.html
[92] https://docs.alfresco.com/../concepts/surf-authenticators.html
[93] https://docs.alfresco.com/../concepts/surf-remote-api.html
[94] https://docs.alfresco.com/../references/surf-object-xml-reference-configuration.html
[95] https://docs.alfresco.com/../references/surf-object-xml-reference-template-type.html
[96] https://docs.alfresco.com/../references/surf-object-xml-reference-theme.html
[97] https://docs.alfresco.com/../concepts/dev-extensions-share-surf-checksums.html
[98] https://docs.alfresco.com/../concepts/dev-extensions-share-css-data-image-support.html
[99] https://docs.alfresco.com/../concepts/dev-extensions-share-aggregate-dependencies.html
[100] https://docs.alfresco.com/dev-extensions-share-surf-checksums.html
[101] https://docs.alfresco.com/java-public-api-list.html
[102] https://docs.alfresco.com/API-JS-intro.html