Surf Object XML Quick Reference (SiteData) - Alfresco Content Services - 23.4 - 23.4 - Ready - Alfresco - external

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 is the Surf web script engine.

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

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

• <id> - Component IDs follow a convention:
  • For page and template scoped region bindings the convention is <scope>.<region-id>.<source-id>
  • For bindings to regions in the global scope the convention is global.<region-id>
• <scope> - The scope of the binding (page, template, 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.

• <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 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/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 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/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 the 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 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/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 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>
</component>

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

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 maybe 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>
</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.

File locations

In the following sections you will see that two locations are specified:

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