Appendix E. Surf Quick Reference

The Surf platform lets you define objects to describe elements like pages, template instances, component bindings, and themes. These objects are consulted at delivery time to render views for your Spring Web application.

OBJECT DEFINITIONS

This appendix provides a guide for developers who wish to customize or build new Surf applications. This includes the customization or addition of new features to Alfresco Share.

The Surf object types are covered in detail. For each object type, sample code is provided to illustrate the XML structure required to define them as files on disk. The recommended locations for each file are also provided.

For more information on these APIs and future releases, please visit: http://www.springsurf.org

COMMON OBJECT PROPERTIES

All Surf objects share some properties in common. The following code shows the basic structure of a Surf object XML file. It has a single mandatory id field. The remainder of the properties are optional.

Surf objects provide support for internationalization for the title and description fields (using the title-id and description-id identifiers, respectively).

<object>

   <!-- mandatory id field -->
   <id>ID</id>
<!-- Optional title (direct or i18n) -->
   <title>TITLE</title>
   <title-id>TITLE-ID</title-id>

   <!-- Optional description (provided or i18n key) -->
   <description>DESCRIPTION</description>
   <description-id>DESCRIPTION-ID</description-id>

   <!-- Optional custom properties -->
   <properties>
      <CUSTOM_KEY>CUSTOM_VALUE</CUSTOM_KEY>
   </properties>

</chrome>

Chrome

Chrome is the decoration around a region or a component in a page. It defines the borders around something being rendered. Chrome is frequently used to create visual separation of regions on the page or to offer configuration controls around content or components being displayed.

Locations

classpath:/alfresco/site-data/chrome
classpath:/alfresco/web-extension/site-data/chrome

Definition

<chrome>
   <processor mode="view">
      <id>PROCESSOR_ID</id>
      <uri>PROCESSOR_URI</uri>
   </processor>
</chrome>

Properties

  • <processor>—Identifies the rendition processor to use

    Valid PROCESSOR_ID values include freemarker, jsp, and a custom ID. With the FreeMarker processor, PROCESSOR_URI should identify the path to the FTL file relative to the /templates directory. With the JSP processor, PROCESSOR_URI should identify the path to the JSP file relative to the Web application root.

Example: Chrome for a Region

The following file defines a Chrome instance that points to a FreeMarker template file that will be used to frame or wrap the output of a region:

classpath:/alfresco/web-extension/site-data/chrome/sample-region-chrome.xml

<?xml version="1.0" encoding="UTF-8"?>
<chrome>
   <id>sample-region-chrome</id>
   <title>Sample Region Chrome</title>
   <processor mode="view">
      <id>freemarker</id>
      <uri>sample/region-chrome.ftl</uri>
   </processor>
</chrome>

The Chrome is rendered by the FreeMarker file sample/region-chrome.ftl. Here is what it might look like. The <@regionInclude/> tag informs the Chrome template of where to insert the region output within your markup.

<div id="${htmlid}" class="sample-region-chrome">
   <@regionInclude/>
</div>

To include a Chrome that wraps around a region, all you need to then do is identify the Chrome ID in the <@region/> tag in your page's template. A very simple template file that renders a single region may look like this:

classpath:/alfresco/web-extension/templates/sample/page-template.ftl

<html>
   <body>
      <@region id="content" chrome="sample-region-chrome" />
   </body>
</html>

Example: Chrome for a Component Binding

The following file defines a Chrome instance that points to a FreeMarker template file that will be used to frame or wrap the output of a component:

classpath:/alfresco/web-extension/site-data/chrome/sample-component-chrome.xml

<?xml version="1.0" encoding="UTF-8"?>
<chrome>
   <id>sample-component-chrome</id>
   <title>Sample Component Chrome</title>
   <processor mode="view">
      <id>freemarker</id>
      <uri>sample/component-chrome.ftl</uri>
   </processor>
</chrome>

The Chrome is rendered by the FreeMarker file sample/component-chrome.ftl. Here is what it might look like. The <@componentInclude/> tag informs the Chrome template of where to insert the component output within your markup.

classpath:/alfresco/web-extension/templates/sample/component-chrome.ftl

<div id="${htmlid}" class="sample-component-chrome">
   <@componentInclude/>
</div>

To include a Chrome that wraps around a region, all you need to then do is identify the Chrome ID in the component's XML definition. This might look something like this:

<component>
   <id>global.header</id>
   <scope>global</scope>
   <region-id>header</region-id>
   <source-id>global</source-id>
   <url>/header</url>
   <chrome>sample-component-chrome</chrome>
</component>

Component Type

Component types contain information that is common across many component instances of the same type. A component type defines one or more rendering processors. It may also define properties that all components of the given type will receive at render time.

When the framework needs to render a component, it considers the component type and merges its properties forward. The uri of the component instance overrides the uri of the processor of the component type.

Locations

classpath:/alfresco/site-data/component-types
classpath:/alfresco/web-extension/site-data/component-types

Definition

<component-type>
   <processor mode="view">
      <id>PROCESSOR_ID</id>

      <!-- optional uri -->
      <uri>PROCESSOR_URI</uri>
   </processor>
</component-type>

Properties

  • <processor>—Identifies the rendition processor to use

    Valid PROCESSOR_ID values include freemarker, jsp, and a custom ID. With the FreeMarker processor, PROCESSOR_URI should identify the path to the FTL file relative to the /templates directory. With the JSP processor, PROCESSOR_URI should identify the path to the JSP file relative to the Web application root.

Example: Web Script Component Type

The following file defines a component type that invokes the Web script processor to render components of this type.

classpath:/alfresco/web-extension/site-data/component-types/webscript.xml

<?xml version="1.0" encoding="UTF-8"?>
<component-type>
   <title>Web Script Component Type</title>
   <processor mode="view">
      <id>webscript</id>
   </processor>
</component-type>

Example: Sample Custom Type

The following file defines a custom component type that invokes a custom processor to render components of this type. The custom processor must be defined as a Surf processor via a Spring bean that is registered through Spring configuration. Surf will pass the context and the properties to the processor.

classpath:/alfresco/web-extension/site-data/component-types/custom-type.xml

<?xml version="1.0" encoding="UTF-8"?>
<component-type>
   <processor mode="view">
      <id>custom-processor-id</id>
   </processor>
   <properties>
      <serviceUri>/external/feed/uri</serviceUri>
      <resultSet>30</resultSet</30>
   </properties>
</component-type>

Component

Component instances describe bindings between a region and a rendering engine that is responsible for generating the component's markup. Typically, the rendering engine will be the Surf Web script engine.

Locations

classpath:/alfresco/site-data/components
classpath:/alfresco/web-extension/site-data/components

Definition

<component>
   <id>COMPONENT_ID</id>

   <!-- required -->
   <scope>page|template|global</scope>
   <region-id>REGION_ID</region-id>
   <source-id>SOURCE_ID</source-id>
<!-- optional properties -->
   <url>URL</url>
   <component-type-id>COMPONENT_TYPE_ID</component-type-id>
   <chrome>CHROME_ID</chrome>
</component>

Properties

  • <id>—Component IDs follow a specific convention:

    • For page and templated scoped region bindings, the ID convention is:

      <scope>.<region-id>.<source-id>

    • For bindings to regions in the global scope, the id convention is:

      global.<region-id>

  • <scope>—The scope of the binding (page, template, or global).

  • <region-id>—The name of the region that is being bound.

  • <source-id>—The ID of the page or template instance to which the component is bound. For the global scope, this should be set to global.

Optional Properties

  • <url>—The Web script URL (if a Web script is being rendered)

  • <component-type-id>—The ID of the component type for this component

  • <chrome>—The ID of the Chrome used to frame this component's presentation

Example: Page Scope Binding

This example binds the Web script with URL /sample/content to the page-scoped region named content on the page home. It therefore has the ID page.content.home.

classpath:/alfresco/web-extension/site-data/components/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>

Example: Template Scope Binding

This example binds the Web script with 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/components/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>

Example: Global Scope Binding

This example binds the Web script with URL /sample/footer to the global-scoped region named footer. It therefore has the ID global.footer.

classpath:/alfresco/web-extension/site-data/components/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>

Example: Custom Page Scope Binding

This example binds the Web script with 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/components/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

Configuration files let you store arbitrary XML descriptions for use in your custom Surf objects. In most cases, the only time you will need to construct one of these objects is when describing the site configuration. An example of a site configuration follows.

Locations

classpath:/alfresco/site-data/configurations
classpath:/alfresco/web-extension/site-data/configurations

Definition

<configuration>
  <source-id>SOURCE_ID</source-id>
</configuration>

Properties

  • <source-id>—Tags the configuration as pertaining to an arbitrary ID. Surf will automatically look for configuration where source-id is site.

Example: Site 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>
</configuration>

Content Association

Content associations are mappings between content and presentation. They inform Surf which page or template instances to use when a request is made to render content with a specific type or instance ID.

Locations

classpath:/alfresco/site-data/content-associations
classpath:/alfresco/web-extension/site-data/content-associations

Definition

<content-association>
   <source-id>SOURCE_ID</source-id>
   <source-type>SOURCE_TYPE</source-type>
   <dest-id>TEMPLATE_ID|PAGE_ID</dest-id>
   <assoc-type>template|page</assoc-type>
<!-- optional format id -->
   <format-id>FORMAT_ID</format-id>
</content-association>

Properties

  • <source-id>—The ID of the content item or content type

  • <dest-id>—The ID of either the template instance or page to render

Optional Properties

  • <source-type>—The type of source (either content or contenttype).

  • <assoc-type>—The type of associated destination. The type is either template or page. If this is not specified, the default value is template.

  • <format-id>—The ID of the format for which this association is valid. If the ID is not specified, the default format is default.

Example: Configuring a Display Page for Alfresco Content

The following file associates a display page with an Alfresco content type. The content type is cm:content and has its namespace fully qualified out.

classpath:/alfresco/web-extension/site-data/content-associations/cm_content.xml

<?xml version="1.0" encoding="UTF-8"?>
<content-association>
   <source-id>{http://www.alfresco.org/model/content/1.0}content</source-id>
   <dest-id>view-content-page</dest-id>
   <assoc-type>page</assoc-type>
</content-association>

Page Association

Page associations define a relationship between a source Page and a destination Page. The association between these Pages is of a specific type.

Often, page associations are used to define hierarchical relationships between pages in a site. They describe relationships between a parent Page and a child Page. In this case, the relationship is of type "child" in that the destination Page is a child of the source Page.

Locations

classpath:/alfresco/site-data/page-associations
classpath:/alfresco/web-extension/site-data/page-associations

Definition

<page-association>
   <source-id>SOURCE_ID</source-id>
   <dest-id>DEST_ID</dest-id>
   <assoc-type>ASSOC_TYPE</assoc-type>
   <order-id>ORDER_ID</order-id>
</page-association>

Properties

  • <source-id>—The ID of the source Page, which is typically the parent Page

  • <dest-id>—The ID of the destination Page, which is typically the child Page

Optional Properties

  • <assoc-type>—The kind of association. The default association type is child.

  • <order-id>—The order or index in which this page association should appear among the full collection of associations from this source-id and of this type.

Example: Child Page Association

The following file associates a child Page with an ID of products to a parent Page with an ID of home.

classpath:/alfresco/web-extension/site-data/page-associations/home-products.xml

<?xml version="1.0" encoding="UTF-8"?>
<page-association>
  <id>home-products</id>
  <source-id>home</source-id>
  <dest-id>products</dest-id>
  <assoc-type>child</assoc-type>
</page-association>

Page Type

Page types contain information that is common across many page instances of the same type. Page types encapsulate common configuration settings and properties.

One example of a page type is login. When Surf is asked to go to the login page type, it checks the current theme and default framework settings to determine which page instance to render.

In this fashion, Surf can support multiple login pages. You might imagine one page for employees, one page for customers, and one page for partners. Each page can be different and have a unique look and feel. They all achieve the same purpose.

Not every page instance in Surf will specify a page type. In fact, most will not. All pages are assigned a generic page type by default.

Locations

classpath:/alfresco/site-data/page-types
classpath:/alfresco/web-extension/site-data/page-types

Definition

<page-type>
   <id>PAGE_TYPE_ID</id>
</page-type>

Properties

There are no additional properties for this object type.

Example: Login Page Type with Custom Property

The following file defines the login page type and assigns a default property that will be picked up by all pages of type login.

classpath:/alfresco/web-extension/site-data/page-types/login.xml

<?xml version="1.0" encoding="UTF-8"?>
<page-type>
   <id>login</id>
   <properties>
      <allow-self-registration>true</allow-self-registration>
   </properties>
</page-type>

Page

A Page describes a URL-addressable destination that has been resolved and for which a view must be produced. A page aligns with the concept of a Web page from the end user's point of view. Pages are often arranged into page hierarchies that constitute a Web site's navigation structure.

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).

Locations

classpath:/alfresco/site-data/pages
classpath:/alfresco/web-extension/site-data/pages

Definition

<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>

Properties

  • <template-instance>—The IDs of one or more template instances that will be used to render this Page when requested for a given FORMAT_ID. If the format attribute is not supplied, it is assumed to have the value default.

Optional Properties

  • <authentication>—The level of authentication required in order for the end user to access this page. Valid authentication values are none or user (defaults to none).

  • <page-type-id>—The ID of the page type of this Page.

Example: Page with Authentication

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>
   <description>Products Page Description<description>
   <authentication>user</authentication>
   <template-instance>landing1<template-instance>
   <template-instance format="print">landing1-print<template-instance>
</page>

Template Instance

Template instances wrap configuration around a template file. The template file receives all the properties of the template instance and can use these properties to inform its rendering logic. This empowers a single template file to render differently based on the configuration stored in the template instance.

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.

Locations

classpath:/alfresco/site-data/template-instances
classpath:/alfresco/web-extension/site-data/template-instances

Definition

<template-instance>
   <template-type>TEMPLATE_TYPE_ID</template-type>
</template-instance>

Properties

  • <template-type>—The ID of the template type used to render this template instance. If a template path is provided here, the template type is assumed to be FreeMarker and the path is used for rendering.

Example: Landing Template with Configuration

The following file defines a template instance that wraps configuration around a template type. The template type is specified as a path and so the FreeMarker processor will be used.

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>

Template Type

Template types contain information that is common across many template instances of the same type. A template type defines one or more rendering processors. It may also define properties that all template instances of the given type will receive at render time.

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.

Locations

classpath:/alfresco/site-data/template-types
classpath:/alfresco/web-extension/site-data/template-types

Definition

<template-type>

   <!-- Required "view" processor -->
   <processor mode="view">
      <id>PROCESSOR_ID</id>

      <!-- optional uri -->
      <uri>PROCESSOR_URI</uri>
   </processor>

</template-type>

Properties

  • <processor>—Identifies the rendition processor to use

    Valid PROCESSOR_ID values include freemarker, jsp, and a custom ID. With the FreeMarker processor, PROCESSOR_URI should identify the path to the FTL file relative to the /templates directory. With the JSP processor, PROCESSOR_URI should identify the path to the JSP file relative to the Web application root.

Example: FreeMarker Template Processor

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>

Theme

Themes capture default settings for the rendering of elements in the request. A theme is a unique identifier as well as a collection of properties and page type overrides. When a theme is selected, its properties and its page type overrides apply to the request.

A theme captures default settings for the rendering framework. Different themes can have different rendering behaviors.

Locations

classpath:/alfresco/site-data/themes
classpath:/alfresco/web-extension/site-data/themes

Definition

<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>

Properties

  • <page-types>—One or more optional overrides that assign default page instances to be used when Surf asks for a Page of a particular type. Using this mechanism, themes can swap out different default Pages to significantly affect the look and feel.

Example

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>R
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.221.2.141