ALFRESCO SURF PAGES

[tushar115]

HI, I WANT toi understand below given ftl codes.  here why we use <@ markup> directive?  how the bindings done between  components and  region?


<#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>
   </@>
</@>

[steven_okennedy]

Hi

In Surf, the setup of a page covers more than just one file.  The starting point to look at should be the actual surf page configuration itself.  Basically the way surf works (simplified) is that you have a number of different entities
<ul>
<li>template - the ftl file that controls rendering a page.  Made up of html/ftl directives that will form the final page. Its used to specify the common static layout elements (often incl header & footer) and defining dynamic regions.  These regions are areas that will be populated using specific webscripts that get bound to them by the page/template-instance configuration. Regions can be scoped globally, at template instance level or at page level</li>
<li>template-instance - this is a configuration element that defines a specific use case for a template (the same template could be used multiple times with different scripts bound to different regions).  It's responsible for specifying the webscripts get bound to the template's regions in most cases.  In some cases, regions can also be bound by the page definitions as well allowing more than one page to share the same template instance.
<li>page definition - this is a config file that defines the page itself (title, description, authentication etc), specifies what template instance should be used and optionally can specify page level components that can be bound into the template</li>
</ul>

So in summary a page definition will point to a template instance. 
A template instance point to an actual template and will bind components (webscripts) to its regions
The template is the ftl file that controls what gets rendered and defines the regions that can be filled.
A single template can be used by more than one template-instance and a single template-instance can be used by more than one page, giving you a lot of flexibility.

To take a concrete example, look at the advanced search page.
<ul>
<li>The page definition is in share/WEB-INF/classes/alfresco/site-data/pages/advsearch.xml.  It uses the "search" template instance and also bind two components to the "title" and "search" regions.  The url given in each component is the url of a surf webscript that will be used to generate the html for each region</li>
<li>To find the template instance itslef, we go to share/WEB-INF/classes/alfresco/site-data/template-instance/ and find search.xml.  This doesn't bind any regions in this case (they are all handled by the page or are global regions), and just specifies that it should use the "org/alfresco/search" template</li>
<li>The template itself can be found using the path org/alfresco/search.ftl starting in the share/WEB-INF/classes/alfresco/templates/ directory and defines the outline of what is rendered as well as the regions themselves</li>

The markup tags are used by Share extensions so that you can easily reference key parts of the template and either add new elements before or after them, remove them completely or replace them with some alternative html markup.

You can see more about all of this here (http://docs.alfresco.com/5.1/concepts/dev-extensions-share-surf-pages.html)

One thing to bear in mind if you're looking to create new pages, is that generally speaking, the surf pages are becoming - probably not obsolete, but more of a legacy way of doing custom page creation.  The Aikau framework allows a much simpler mechanism for creating, laying out and rendering pages using a modular widget-based mechanism.  Have a look here (http://docs.alfresco.com/5.1/concepts/dev-extensions-share-architecture-extension-points-intro-aikau...)

Regards

Steven

[tushar115]

HOw Template instance bound component  to it's region ?

<component>
         <scope>page</scope>
         <region-id>title</region-id>
         <source-id>site/${siteid}/dashboard</source-id>
         <url>/components/title/collaboration-title</url>
      </component>
Also what is source-id in this Code  ?

[steven_okennedy]

Hi

The template instance binds components to regions in the same way as was done in the page example I mentioned earlier.  Taking a different example, e.g. the change-password tempalate-instance (share/WEB-INF/classes\alfresco/site-data/template-instances/change-password.xml) looks like this :

<template-instance>
   <template-type>org/alfresco/change-password</template-type>
   <components>

      <!– Title –>
      <component>
         <region-id>title</region-id>
         <url>/components/title/profile-title</url>
      </component>

      <!– Toolbar –>
      <component>
         <region-id>toolbar</region-id>
         <url>/components/profile/userprofile-toolbar</url>
      </component>

      <!– Change Password –>
      <component>
         <region-id>change-password</region-id>
         <url>/components/profile/change-password</url>
      </component>
   </components>
</template-instance>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

As well as specifying the template-type, this template instance also binds regions to specific webscripts using the component definitions.

If you're going to post some code and ask questions on it, it makes things a lot easier if you also specify where the code is from and where you found it.  It looks to me as if the code you specified is part of the presets.xml file. Presets are not page definitions but they are used to control the automatic creation of surf configuration for new sites, e.g. defining what the default dashboards look like and controlling what pages are available to use in the site. The source id in this case I believe references the particular page the preset is affecting (http://docs.alfresco.com/5.1/concepts/dev-extensions-share-site-presets.html)

Regards

Steven