Alfresco Surf and Web Editor [ 272 ] All of these applications are presently being built on top of the Surf platform. The Surf platform itself is a product that our community and customers may wish, and are encouraged, to use in building their own web applications. Alfresco Surf architecture Surf architecture shows a deep appreciation for the Web 2.0-inspired architecture and web application mash-ups. It's important to point out that although tools exist to reduce the need for technical skills, the platform does not eliminate or discourage access to its internals for those who need it. Surf utilizes the MVC pattern using various components and objects. MVC stands for Model-View-Controller. MVC pattern The Dispatcher Servlet can be considered as a controller. It is responsible for rendering the view. It considers the incoming request context and decides what and how to render. It constructs the page view by looking at the related model components or templates to render using different possible rendering engines. The dispatcher can receive requests for the following: • A specic page: A page ID may be given directly to the dispatcher. • A type of page: For instance, the user may be requesting the login page. The application may actually have several login pages (for customers, employees, and so on) and it must select one and render it back. • An object: An object ID may be given to the dispatcher. The dispatcher must then gure out which page to use to render this object. Download from Wow! eBook <www.wowebook.com> Chapter 9 [ 273 ] • The Surf model: This can be considered as the model of the MVC architecture. Model is an entity that holds data. The Surf platform uses a lightweight XML-driven model to store all model objects that implement the majority of common websites and web application object types. XML les are effectively bound together to allow a page to be loaded and rendered. You can also dene your own object model and extend the out-of-the-box object model. These include objects such as Pages, Templates, Components, Chromes, and Themes. The XML is stored in sub-directories in the specied location: <install- application>/WEB-INF/classes/alfresco/site-data . Within this directory, you will see the following sub-directories, one for each type of model object that is managed by the Surf platform: /site-data/chrome /site-data/component-types /site-data/components /site-data/configurations /site-data/content-associations /site-data/page-associations /site-data/page-types /site-data/pages /site-data/template-instances /site-data/template-types /site-data/themes View (Renderers): View is for the presentation layer. The model objects such as components, templates, and page can be rendered using any of Surf's supported rendering engines, which internally return data in HTML, XML, JSON, and many more. The view can be constructed using several rendering engines. These include: Web scripts: Web scripts are used most commonly to render components. Web scripts themselves follow MVC architecture. The Web scripts take advantage of JavaScript (behaving as a controller), FreeMarker (for presentation processing), and model objects (for business logic). They can be stored in the specied location: <install-application>/WEB-INF/classes/alfresco/site-webscripts. Download from Wow! eBook <www.wowebook.com> Alfresco Surf and Web Editor [ 274 ] JSP: The JSP renderer is used to render either components or templates, and provide you with access to the Java language and the Surf platform Java API. JSPs can be stored in the specied location: <install-application >/tomcat/webapps/ alfresco/jsp/components . FreeMarker: FreeMarkers can be stored in the specied location: <install- application>/WEB-INF/classes/alfresco/templates . By using the Surf framework you can create both single-tier and two-tier applications. Tiers can be considered as the physical deployment of different application layers. Single-tier application The user interface of a web application, the middleware, and the data access all are contained in one package. A system where all the layers are bundled together on a single server is generally single tier. Single-tier architecture has the interface, business logic, and database highly coupled. Installing Surf as is, with just the page layout and component framework, is single tier. A one-tier application also follows MVC. Here, model represents objects like pages, components, and templates, controller represents Dispatcher servlets, and renderer represents FTL and Web scripts. In this case, FTL code will be heavy, and rather than depending on other parties, it will call the User Interface framework optionally and will message data. It will also create data in the form of HTML or XML. If we have a complex User Interface, it is not advisable to keep the complete logic in one Web Script. In that case, we can develop the application using two tiers. Download from Wow! eBook <www.wowebook.com> Chapter 9 [ 275 ] Two-tier application With two-tier client/server architectures the user system interface (Client) is usually located on the user's desktop environment and the database management services are usually in a server that is a more powerful machine that services many clients. Processing management is split between the user system interface environment and the database management server environment. The client performs most of the business logic as well as the presentation, updating shared data by communication with the database. Here we separate the data retrieval and data presentation part. So, one set of web scripts (Data web script), will be responsible for data retrieval and sending them in JSON, XML (ATOM), or other serialized data format present on the Repository tier. Another set of web scripts (Presentation web script) with some UI framework, may be YUI (Yahoo User Interface), will call those Data web scripts and will be responsible for rendering data present on Presentation tier in HTML format. In case of two-tier FTL or presentation web scripts, the code will be minimal and will be more centric to creating data in JSON/XML format. Consider the client is on one server (Presentation tier) accessing the Alfresco repository on a different server (Repository tier) using remote calls. Alfresco Share and Web Editor are two-tier applications, as they remotely connect to a different Alfresco repository using remote calls. The Alfresco Web Editor performs most of the business logic and presentation. It uses the Alfresco repository to fetch and store the data using Alfresco web scripts. Download from Wow! eBook <www.wowebook.com> Alfresco Surf and Web Editor [ 276 ] Surf model objects In the Surf framework models are represented in the form of XML. XML les are effectively bound together to allow a page to be loaded and rendered. A model object contains information about site construction. Model denes pages, page layouts, and components within the page. We already had an overview about model in the previous section. Let's have an overview about these elements: Objects Description Conguration A Conguration object is a collection of XML, mostly used by the internal system. It is dened for a site. Component Type A Component Type is something that the website builder can grab at and instantiate in many places across the web application. They bind the new instances into pages by snapping them into regions (or slots). They can be considered as widgets. Component A Component is an instance of a Component Type that has been "bound" into a region. Template Instance It points to Free Marker renderer classes. Template Type It species FreeMarker or web scripts as the renderer. Template renderer It denes the look and feel of the page. Page A Page is the navigation page in a web application. It consists of templates and components. Page Association The Page Association objects allow you to link two pages together. Content Association It associates a document to the page. It can associate either a specic document or all documents of specic type and can be associated to a page instance or page type. Chrome Chrome describes border elements around a region or a component. Using Chrome, you can also include styling elements and drag-and-drop capabilities into a Page. Surf API We will learn some of the surf APIs used by presentation tier. The objects and methods are available to templates and components within Alfresco Surf. The main point to be noted is that these methods are not available for Repository-tier web scripts. Both FreeMarker template API and JavaScript API use the common object model. The list of commonly used root objects and methods is as follows: Download from Wow! eBook <www.wowebook.com> Chapter 9 [ 277 ] Root objects Properties and Methods Description context (context of current page) id The internal manage ID for the current request. pageId, page The ID of page and page object being rendered. templateId, template The ID of template and template object being rendered. theme, themeId The ID of theme and current theme object being rendered. user The current user. ContentId, content The ID of content and content object being rendered. properties Associative array of all context values. authenticated Returns true if current user is not a guest. user (current user) id User identier. properties Associative array of all user values. name, fullName, firstName, MiddleName, lastName, mail, telephone, mobilePhone, location, biography The details related to user identication. organization, jobTitle, companyPostcode, companyTelephone, compnayFax, companyEmail, companyAddress1, companyAddress2, companyAddress3 The details related to user's organization. skype, instantMsg The user's online contact details. save() Saves changes to the user's properties. getUser(userId) Retrieves user object. Download from Wow! eBook <www.wowebook.com> Alfresco Surf and Web Editor [ 278 ] Root objects Properties and Methods Description content (only available if an object ID is provided as part of the page URL) id The ID of content object. typeId The typeId of content object. properties Associative array of all object properties. timestamp The time when the object was loaded. endpointId The ID of endpoint from which object was loaded. isLoaded Whether the object is successfully loaded. statusCode, statusMessage The status code and message when the object is loaded. text, xml The content in text and XML format. Page (available within context of page renderer) url The URL helper object. id The ID of page object. title, titleId Title of Page denition. description, descriptionId Description of Page Denition. theme Theme ID. properties Properties of custom page denition. url context Page root context path. servletContext Page root servlet path. uri Page URI. url Page URL. queryString Query string for the URL. args Map of URL arguments. Download from Wow! eBook <www.wowebook.com> Chapter 9 [ 279 ] Root objects Properties and Methods Description remote (connect to remote services, that is, repository tier) endpointIds A string[] array of endpoints. connect Default end point connector. connect(endpointId) Connector to specied end point. call(uri) Invokes specic URI on default endpoint. GetEndpointName(endpointId), GetEn dpointDescription(endpointId) Gets the name and description for an end point. GetEndpointURL(endpointId) Gets the URL for an end point. sitedata (site construction helper) rootPage Root Page object for the website. siteConfiguration Conguration object for the website. components, pageAssocaiations, pages, templates, contentAssociations Arrays of all these objects. There are many more methods available. componentsMap, pageAssociationsMap, pagesmap, templatesMap Maps of all these objects. There are many more methods available. newPage(title,description), newTemplate(templateTypeId, title, description), newObject(objectId, objectTypeId) Creates new objects. There are many more methods. findComponents(scopeId, sourceId, regionId, componentTypeId), findChildPages(sourceId), findPageAssociations(sourceid, destId, assoctype) Looks up objects and returns array of results. There are many more methods available. associateTemplate(templateId, pageId), associatePage(sourceId, destId) Binds object together. There are many more methods available. unassociateTemplate(pageId), unassociatepage(sourceid, destId) Unbinds objects together. getPage(objectId), getTemplate(objectId) Looks up individual objects. Download from Wow! eBook <www.wowebook.com> Alfresco Surf and Web Editor [ 280 ] Rendering engines There are two most commonly used rendering engines—components and templates. Specic objects are available to these engines: Objects Template Components sitedata Yes Yes context Yes Yes instance Yes Yes user Yes Yes content Yes Yes page Yes Yes theme Yes Yes htmlid Yes Yes url Yes No head Yes No Design site navigation We will rst learn how to create a standalone application using the Surf framework without the use of Alfresco. For this you need to download surf.war and keep it in your web or application server. For this chapter, you can place the WAR le in the <install-alfresco>/tomcat/webapps folder. This doesn't mean that we are using Alfresco for our development. You can also place the WAR le in any standalone server. Start your server. You will nd that the surf.war le has exploded and the surf folder is created. You can see the following structure created by default: Download from Wow! eBook <www.wowebook.com> Chapter 9 [ 281 ] Design a page Follow the steps below to create a sample page: • Step 1: Go to the <install-alfresco>/tomcat/webapps/surf/WEB-INF/ classes/alfresco/site-data/configurations folder. • Step 2: Open the default.site.configuration.xml le. Insert the highlighted code as mentioned below to create our home page: <?xml version="1.0" encoding="UTF-8"?> <configuration> <title>Sample Site Configuration</title> <description>Sample Site Configuration</description> <source-id>site</source-id> <properties><root-page>index</root-page></properties> </configuration> • Step 3: Go to the <install-alfresco>/tomcat/webapps/surf/WEB-INF/ classes/alfresco/site-data/pages folder. • Step 4: Create a new le with the name given previously in the root-page tag. Create the index.xml le. Insert the following code: <?xml version='1.0' encoding='UTF-8'?> <page> <id>index</id> <title>CIGNEX | Open Source ECM, BPM , E Commerce , Portals </title> <description>Sample Cignex home page</description> <template-instance>index</template-instance> <authentication>none</authentication> </page> • Step 5: Go to the <install-alfresco>/tomcat/webapps/surf/WEB-INF/ classes/alfresco/site-data/template-instances folder. • Step 6: Create a new le with the name given previously in the template- instance tag. Create the index.xml le. Insert the following code: <?xml version='1.0' encoding='UTF-8'?> <template-instance> <template-type>index</template-type> </template-instance> • Step 7: Go to the <install-alfresco>/tomcat/webapps/surf/WEB-INF/ classes/alfresco/templates folder. Download from Wow! eBook <www.wowebook.com> . /site-data/component-types /site-data/components /site-data/configurations /site-data/content-associations /site-data/page-associations /site-data/page-types /site-data/pages /site-data/template-instances . encoding='UTF-8'?> <template-instance> <template-type>index</template-type> </template-instance> • Step 7: Go to the <install-alfresco>/tomcat/webapps/surf /WEB- INF/ classes/alfresco/templates . <properties><root-page>index</root-page></properties> </configuration> • Step 3: Go to the <install-alfresco>/tomcat/webapps/surf /WEB- INF/ classes/alfresco/site-data/pages