There is a separate section in the documentation dedicated to Configuring Alfresco Share [58]. This configurations typically goes into the share-config-custom.xml file. The following is an example of stuff that you can configure in this file:

Note that a lot of the other extension points that require coding also involve configuration, so it is a good idea to read up on the configuration bit before starting any development with the other extension points.

• aio/share-jar/src/main/resources/META-INF/share-config-custom.xml - Share configuration related to a specific Share module extension, such as Document Library Action configuration, form configuration, aspect and type configuration.

• Share configuration introduction [58]
• Document Library configuration [60]

• Making custom types visible [61]
• Making custom aspects visible [62]
• Controlling search results [63]
• Controlling user name and password length [64]
• Setting repository location [65] (If the Share webapp and the repository webapp runs in different application servers)
• Remove persistent cookies [66]
• Document Library actions, metadata templates, and indicators [67]
• Document Library views [68]

<div class="form-field">
   <#if form.mode == "view">
      <div class="viewmode-field">
         <#if field.mandatory && !(field.value?is_number) && field.value == "">
            <span class="incomplete-warning"><img src="${url.context}/res/components/form/images/warning-16.png" title="${msg("form.field.incomplete")}" /><span>
         </#if>
         <span class="viewmode-label">${field.label?html}:</span>
         <#if field.control.params.activateLinks?? && field.control.params.activateLinks == "true">
            <#assign fieldValue=field.value?html?replace("((http|ftp|https):\\/\\/[\\w\\-_]+(\\.[\\w\\-_]+)+([\\w\\-\\.,@?\\^=%&:\\/~\\+#]*[\\w\\-\\@?\\^=%&\\/~\\+#])?)", "<a href=\"$1\" target=\"_blank\">$1</a>", "r")>
         <#else>
            <#if field.value?is_number>
               <#assign fieldValue=field.value?c>
            <#else>
               <#assign fieldValue=field.value?html>
            </#if>
         </#if>
         <span class="viewmode-value"><#if fieldValue == "">${msg("form.control.novalue")}<#else>${fieldValue}</#if></span>
      </div>
   <#else>
      <label for="${fieldHtmlId}">${field.label?html}:<#if field.mandatory><span class="mandatory-indicator">${msg("form.required.fields.marker")}</span></#if></label>
      <input id="${fieldHtmlId}" name="${field.name}" tabindex="0"
             <#if field.control.params.password??>type="password"<#else>type="text"</#if>
             <#if field.control.params.styleClass??>class="${field.control.params.styleClass}"</#if>
             <#if field.control.params.style??>style="${field.control.params.style}"</#if>
             <#if field.value?is_number>value="${field.value?c}"<#else>value="${field.value?html}"</#if>
             <#if field.description??>title="${field.description}"</#if>
             <#if field.control.params.maxLength??>maxlength="${field.control.params.maxLength}"<#else>maxlength="1024"</#if> 
             <#if field.control.params.size??>size="${field.control.params.size}"</#if> 
             <#if field.disabled && !(field.control.params.forceEditable?? && field.control.params.forceEditable == "true")>disabled="true"</#if> />
      <@formLib.renderFieldHelp field=field />
   </#if>
</div>

These standard form control implementations can be found in the tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/form/controls directory. The two FreeMarker root objects that contain most of the information that we need when implementing the control is the form object and the field object. These objects get their data from the form and field definitions. And you can also implement Form Filters [111] to add extra properties that can be used in the form control implementation.

The following form definition shows the use of the Text Field form control:

<config evaluator="node-type" condition="cm:content">
      <forms>
         <!-- Default form configuration for the cm:content type -->
         <form>
            <field-visibility>
               <show id="cm:name" />
               <show id="cm:title" force="true" />
               ...               
            </field-visibility>
            <appearance>
               <field id="cm:name">
                 <control>
                    <control-param name="maxLength">255</control-param>
                 </control>
               </field>
               <field id="cm:title">
                  <control template="/org/alfresco/components/form/controls/textfield.ftl" />
               </field>
               ...               
            </appearance>
         </form>

The field cm:title is using the textfield.ftl form control. You can also leave out the form control specification, like is shown here for the cm:name field, and let the forms engine select a matching form control based on field data type.

Implementing a custom form control is as easy as creating a new FreeMarker template file and putting it somewhere under the alfresco/web-extension/site-webscripts/ directory. Here is an example of a custom form control for a Due Date field that should be editable sometimes and read-only sometimes, it is stored in org/alfresco/training/components/form/controls/duedate.ftl:

<#-- This Date control implementation checks a property that is set up in a Form Filter to see
     if the due date should be displayed as read-only or not -->
<#if form.data['prop_dueDateReadOnly'] == true>
    <#-- Bring in standard info.ftl -->
    <#include "/org/alfresco/components/form/controls/info.ftl" />
<#else>
    <#-- Bring in standard date.ftl -->
    <#include "/org/alfresco/components/form/controls/date.ftl" />
</#if>

This custom form control uses a custom property called prop_dueDateReadOnly that would need to be set up in a Form Filters [111]. This form control would then be used as follows:

<config evaluator="node-type" condition="acme:document">
      <forms>
        <form>
          <field-visibility>
            ...
            <show id="acme:dueDate" />
          </field-visibility>
          <appearance>
            ...
            <field id="acme:dueDate" set="info" label-id="acme.due.date">
                <control template="/org/alfresco/training/components/form/controls/duedate.ftl" />
            </field>
          </appearance>
        </form>
      </forms>
    </config>

Best practice is to put the file in a directory that explains what the file is for, such as for example:

tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/training/components/form/controls

• Customizing Form Controls [100]
• Form Control Reference [110]
• Forms [112]

• Adding a custom Form Control [107]
• Configuring a Form Control [104]

The JavaScript function signature for a validation handler looks like this:

/**
 * Validation handler for a field.
 * 
 * @param field {object} The element representing the field the validation is for
 * @param args {object} Object containing arguments for the handler
 * @param event {object} The event that caused this handler to be called, maybe null
 * @param form {object} The forms runtime class instance the field is being managed by
 * @param silent {boolean} Determines whether the user should be informed upon failure
 * @param message {string} Message to display when validation fails, maybe null
 * @static
 */
function handler-name(field, args, event, form, silent, message)   

The built in "mandatory" validation handler is defined as follows:

Alfresco.forms.validation.mandatory = function mandatory(field, args, event, form, silent, message)

The field parameter is usually the HTML DOM element representing the field's value, which is normally an HTML input DOM element, so that the value property can be accessed. The structure of the args parameter is dependent on the handler being implemented. By default, these will be the parameters of the constraint defined on the field.

The handler is responsible for taking the value from the field and uses the args parameter to calculate whether the current value is valid or not, returning true if it is valid and false if it is not.

Now, to implement a validation handler you would need to first create a JavaScript function that does the validation. To do email address validation via RegExp, it could look something like this:

if (typeof MyCustomNamespace == "undefined" || !MyCustomNamespace) {
    var MyCustomNamespace = {};
}

MyCustomNamespace.forms.validation.checkEmailValidity =
    function checkEmailValidity(field, args, event, form, silent, message) {
    var valid = true;

    valid = YAHOO.lang.trim(field.value).length !== 0;
    if (valid) {
        var re = /^([\w-]+(?:\.[\w-]+)*)@((?:[\w-]+\.)*\w[\w-]{0,66})\.([a-z]{2,6}(?:\.[a-z]{2})?)$/i;
        valid = re.test(field.value);
    }

    return valid;
}   

After this, make sure the JavaScript file is loaded when the form is loaded, which can be set as follows in share-config-custom.xml when defining the form:

<config>
    <forms>
        <dependencies>
            <js src="/js/email-form-field-validation-handler.js"/>
        </dependencies>
    </forms>
</config>

Then, use the field value validation handler as follows in the form definition:

<config><forms><form>
  ...
  <appearance>
    <field id="acme:emailAddress">
     <constraint-handlers>
       <constraint type="MANDATORY" validation-handler="MyCustomNamespace.forms.validation.checkEmailValidity" event="keyup"/>
     </constraint-handlers>
    </field>

• aio/share-jar/src/main/resources/META-INF/resources/share-jar/js/{custom path} - validation handler JavaScript files
• aio/share-jar/src/main/resources/META-INF/share-config-custom.xml - form definitions with validation handlers

• Forms Reference [110]: see the constraint-handlers description
• Forms [112]

An evaluator is used by other extension points, such as Document Library Actions and Surf Extension Modules, to control when they should display or hide something. Custom evaluators are either configured or coded in Java. The following is an example of an evaluator that is configured as a Spring Bean:

<bean id="evaluator.doclib.metadata.hasExposure"
      parent="evaluator.doclib.action.propertyNotNull">  
   <property name="property" value="exif:exposureTime"/>
</bean>   

In this case a new custom evaluator with ID evaluator.doclib.metadata.hasExposure is created. It is based on the out-of-the-box propertyNotNull evaluator, which takes a property parameter with the content model property that should be checked for null. This evaluator is now ready to use in for example a Document Library Action definition.

If the evaluator is a bit more complex, and there is no existing evaluator that it can be based on, then we can implement the evaluator in Java as in the following example:

import org.alfresco.error.AlfrescoRuntimeException;
import org.alfresco.web.evaluator.BaseEvaluator;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;

public class CheckIfDocIsEmailedEvaluator extends BaseEvaluator {
    private static Log logger = LogFactory.getLog(CheckIfDocIsEmailedEvaluator.class);
    private static final String ASPECT_EMAILED = "cm:emailed";

    @Override
    public boolean evaluate(JSONObject jsonObject) {
        try {
            JSONArray nodeAspects = getNodeAspects(jsonObject);
            if (nodeAspects == null) {
                logger.info("No aspects found");
                return false;
            } else {
                if (nodeAspects.contains(ASPECT_EMAILED)) {
                    logger.info("Has been emailed");
                    return true;
                } else {
                    logger.info("Has NOT been emailed");
                    return false;
                }
            }
        } catch (Exception err) {
            throw new AlfrescoRuntimeException("JSONException whilst running action evaluator: " + err.getMessage());
        }
    }
}

This evaluator needs to be declared as a Spring bean too as follows:

<bean id="org.alfresco.training.evaluator.doclib.action.isEmailed"
          class="org.alfresco.training.documentlibrary.action.evaluator.CheckIfDocIsEmailedEvaluator" />
    

An evaluator is used by referring to it via the Spring Bean ID, as in the following example when declaring a Document Library Action:

<action id="org.alfresco.training.doclib.action.sendAsEmail"
        icon="email"
        type="javascript"
        label="actions.training.alfresco.sendAsEmail">
    <param name="function">onActionFormDialog</param>
    <param name="itemKind">action</param>
    <param name="itemId">send-as-email</param>
    <param name="mode">create</param>
    <param name="destination">{node.nodeRef}</param>
    <param name="successMessage">message.send-as-email.success</param>
    <param name="failureMessage">message.send-as-email.failure</param>
    <evaluator negate="true">org.alfresco.training.evaluator.doclib.action.isEmailed</evaluator>
</action>    

Note here how you can negate the outcome of the evaluation. Which means that in this case we want to show the Send As Email document library action in the UI if an email has not been sent.

Custom evaluator implementations in Java does not lend themselves to be manually deployed into the application server. Use a Share AMP [114] project instead.

• aio/share-jar/src/main/resources/alfresco/web-extension/share-jar-slingshot-application-context.xml - the Spring Bean definition goes into this file
• aio/share-jar/src/main/java/{custom package path} - the Java implementation of the evaluator goes into this directory

• See the Rating Extension Point for example evaluator [115]
• Predefined evaluators for Document Library [116]
• Configuring Evaluators for the Document Library [67]
• Extension Module Deployment and Evaluators [117]

• Creating a Custom Evaluator [118]
• Selecting an Evaluator for an Extension Module [119]
• Sub-Component Evalution [120]
• Improving Sub-Component Evalution [121]

• Sub component evaluations [122]

When you access a site the Dashboard layout, with the dashlets in different columns, is determined by the Site Preset that has been set for the site type. It looks something like this for the Collaboration site type:

<?xml version='1.0' encoding='UTF-8'?>
              <presets>
              <!-- Well known preset used to generate the default Collaboration Site dashboard -->
              <preset id="site-dashboard">
              <components>         
              <!-- title -->
              <component>
              <scope>page</scope>
              <region-id>title</region-id>
              <source-id>site/${siteid}/dashboard</source-id>
              <url>/components/title/collaboration-title</url>
              </component>
              <!-- navigation -->
              <component>
              <scope>page</scope>
              <region-id>navigation</region-id>
              <source-id>site/${siteid}/dashboard</source-id>
              <url>/components/navigation/collaboration-navigation</url>
              </component>
              <!-- dashboard components -->
              <component>
              <scope>page</scope>
              <region-id>component-1-1</region-id>
              <source-id>site/${siteid}/dashboard</source-id>
              <url>/components/dashlets/colleagues</url>
              <properties>
              <height>504</height>
              </properties>
              </component>
              <component>
              <scope>page</scope>
              <region-id>component-2-1</region-id>
              <source-id>site/${siteid}/dashboard</source-id>
              <url>/components/dashlets/docsummary</url>
              </component>
              <component>
              <scope>page</scope>
              <region-id>component-2-2</region-id>
              <source-id>site/${siteid}/dashboard</source-id>
              <url>/components/dashlets/activityfeed</url>
              </component>
              </components>
              <pages>
              <page id="site/${siteid}/dashboard">
              <title>Collaboration Site Dashboard</title>
              <title-id>page.siteDashboard.title</title-id>
              <description>Collaboration site's dashboard page</description>
              <description-id>page.siteDashboard.description</description-id>
              <template-instance>dashboard-2-columns-wide-right</template-instance>
              <authentication>user</authentication>
              <properties>
              <sitePages>[{"pageId":"documentlibrary"}]</sitePages>
              </properties>
              </page>
              </pages>
              </preset>
              ...    

Here is some Surf component configuration again. If you are not up to speed on Surf and the Share architecture, then read the Architecture section [8]. The first two component definitions sets the title and navigation bar for the site. The rest of the component definitions sets the different dashlets that should be displayed on the Dashboard. The last pages section is used to include the Dashboard page with layout and the different site pages.

This site preset looks like this:

The default preset configuration for Share is specified in the tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/presets/presets.xml file.

When a new custom page has been added to Share it is not automatically visible in the navigation bar after a site has bee created. To have a custom page be part of every new site that is created you can override the site preset for the site type.

Here is an example of how to add a custom page to a site:

<preset id="site-dashboard">
              <components>         
              ...
              </components>
              <pages>
              <page id="site/${siteid}/dashboard">
              <title>Collaboration Site Dashboard</title>
              <title-id>page.siteDashboard.title</title-id>
              <description>Collaboration site's dashboard page</description>
              <description-id>page.siteDashboard.description</description-id>
              <template-instance>dashboard-2-columns-wide-right</template-instance>
              <authentication>user</authentication>
              <properties>
              <sitePages>[{"pageId":"documentlibrary"},{"pageId":"helloworld"}]</sitePages>
              </properties>
              </page>
              </pages>
              </preset>

In this case we have added a custom page called helloworld to the site, and this page will be directly accessible from inside the site.

Note: When you have set up a site preset, or a user preset, and it has been used by a site or a user. Then those site presets are stored in the database for the site and user. So you cannot change by redefining presets.xml.

• Adding a new Preset [123] - this tutorial is not really about site presets, but it starts off by setting up a new user preset.

• Create and Edit Site Dialog [124]

The look and feel of the Share user interface is determined by what theme that is currently active, it provides the default CSS and image assets used across all pages. There are number of themes available out-of-the-box:

• Light Theme (Default)
• Google Docs
• Green
• Blue
• High Contrast Black
• Yellow

You set the theme for the whole Share UI, but you can also configure a theme per site.

It is possible to create a new custom theme based on one of these existing themes. The way to do that is to start by copying one of the themes under alfresco/tomcat/webapps/share/themes directory to a new directory under share-amp/src/main/amp/web/themes. Then update it with a new Theme ID and define the new Theme for Surf by adding a file to the alfresco/web-extension/site-data/themes directory. This XML file looks something like this:

<?xml version='1.0' encoding='UTF-8'?>
<theme>
    <title>My Red Theme</title>
    <title-id>theme.redTheme</title-id>
</theme>   

When a custom theme has been created based on an existing theme it is time to configure the look and feel for it. This involves two steps as the Share UI contains both Aikau components and YUI components, and they are styled in different ways. See the tutorials section for more information on this.

It would mean copying all the theme resource files into tomcat/webapps/share/themes, which means the files would be gone after a re-deployment or upgrade. Use a Share AMP [114] project instead.

• aio/share-jar/src/main/resources/META-INF/themes - the theme's resource files goes here, pretty much the stuff you copy from alfresco/tomcat/webapps/share/themes
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/themes - the theme XML file goes here

• Introduction to Share themes [125]

• Adding a custom Share Theme [93]

• Share Header Colour Customization [126] - Customizing the Share header via LESS variable override
• Why Alfresco 5.0.d will be a game changer for UI development [127] - Aikau is from now on in its own JAR
• Install new Share theme via JAR file [128]
  Note: This tutorial does not include information about how to style Aikau components, such as the header.

The Document Library in Share is probably the most comprehensive Surf page (note that it has not yet been converted to Aikau) in the whole application. You will have a number of extension points available so you can customize according to customer requirements.

The following list describes the different Document Library sub-extension points:

Most of these sub-extension points are actually part of the Share Configuration [9] extension point as they are applied via XML configuration in share-config-custom.xml. It is really just the Actions sub-extension point that will involve coding.

The following picture shows an example of how the Document Actions looks like in the UI:

If you are viewing a Folder instead of a file you will be looking at Folder Actions.

There are a number of ways in which these Document Library actions can be implemented. The following picture illustrates:

So an action can be implemented as a client side JavaScript function that calls a repository action or a web script via AJAX. And an action can also just link directly to an existing Share Page. And finally, it is possible to have an action link to an external page.

Next picture shows you the views:

The Detailed View is currently active and the drop down to the right shows you the other available views. An indicator looks like this for a file:

In this case a workflow was started, and there is a little icon indicating that this file is part of a workflow. The default metadata template for files looks like this:

• tomcat/shared/classes/alfresco/web-extension/share-config-custom.xml (Untouched by re-depolyments and upgrades)
• The following locations are inside the exploded Share WAR, so not recommended, use a Share AMP [114] SDK project instead:
• tomcat/webapps/share/components/documentlibrary/actions - DocLib Action JavaScript implementation and icon go here
• tomcat/webapps/share/components/documentlibrary/indicators - status indicators icons go here

• aio/share-jar/src/main/resources/META-INF/share-config-custom.xml - configuration for actions, indicators, views etc
• Or even better, put all the configuration in a Surf Extension Module:
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions/doclib-actions-extension-modules.xml - configuration for actions, indicators, views etc
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components/documentlibrary - DocLib Action JavaScript implementation code
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components/documentlibrary/actions - DocLib Action icons go here
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components/documentlibrary/indicators - Status Indicators icons go here

• See the Rating Extension Point for example DocLib action, form, and evaluator [115]
• The Site Document Library [129]
• Extending the Alfresco Share Document Library [130]

• Follow links to Tutorials below, they each have links to source code

• Adding a new Document Library action [131]
• Adding a menu item to the "Create..." menu in DocLib [132]
• Override and extension examples [67]
• Customizing document library views [68]
• Configure aspect visibility [80]
• Jeff Potts Alfresco Developer Series: Adding Repo and DocLib actions [133] - a very thorough walk-through of how to develop Repository Actions and Document Library actions, a must read.

• Share Document Library Extensions in v4.0 [134]

Surf Extension Modules are the main tool to use when adding, updating, or hiding content in the Share User Interface (UI). They can be deployed and un-deployed during runtime. A module is defined in XML and stored in the site-data/extensions directory.

Working with these extension modules assume a certain knowledge of the Surf UI development framework. Make sure that you have read through the Share Architecture [8] section and the Surf deep dive [135] section.

• Adding content to a Surf page [137]
• Removing/hiding content from a Surf page [138]
• Conditionally controlling rendering of content on Surf page [120]
• Customizing (Web Script Properties) the footer text for a Surf page [139]
• Customizing (Web Script Controller) the WebView dashlet on the Dashboard page [123]
• Customizing (Web Script Template) the footer text for a Surf page [140]
• Extend an out-of-the-box Surf Widget (YUI) [141]
• Add a new menu item to "Create..." menu in DocLib [132]
• Customizing the Share Header Style (Aikau) [142]
• Adding JS packages (Aikau) [143]

• Share Architecture [8]
• Presentation Web Scripts (Surf) vs Data Web Scripts (Repository) [150]

The simplest Web Script you can write consist of a descriptor and a template. The descriptor will tell you what URL that should be used to invoke the Web Script. And the template is used to assemble the output returned from the Web Script. This kind of Web Script is very static to its nature and will always return the exact same content. Most Web Scripts also include a controller that is used to dynamically assemble a map of data that is then processed by the template to produce the final output. The data that the controller produces could come from anywhere as the controller can be implemented in both JavaScript and Java. Any content from the repository that should be included is however fetched via a repository web script (also called a Data web script), as the Surf Web Script controller does not have direct access to the repository (that is, it does not have access to root objects such as companyhome).

The following picture illustrates how a Presentation web script and a Data web script work together to generate the user interface (this is how most of the Share user interface is generated):

As we can see in the above figure a Surf Web Script is not called directly from the browser (with http://localhost:8080/share/service/...) but instead indirectly via either a Surf Page [20] or a Surf Dashlet [21]. Surf web scripts are also used when constructing Aikau Pages [24] and Aikau Dashlets [25].

The JavaScript controller can fetch content from different remote sources, such as the repository and Web Services on the Internet. To do this the controller uses a special root object called remote [152], which can be used to authenticate and connect to a remote service.

// Most services will require an API Key
// You can get one for the openweathermap API here: http://openweathermap.org/appid
var apiKey = "Put your API Key here.....";
// Get weather for London in JSON structure
var londonWeatherURL = "http://api.openweathermap.org/data/2.5/weather?q=London,uk&APPID=" + apiKey;
var connector = remote.connect("http");
var JSONString = connector.get(londonWeatherURL);

// create json object from data
var londonWeatherJSON = jsonUtils.toObject(JSONString);
model.weather = londonWeatherJSON["weather"];  

Note the use of the http connector [152] when communicating with external Web Services. Now, to create a Web Script you also need a descriptor, which is defined in XML and looks something like this:

<webscript>
   <shortname>London Weather</shortname>
   <description>Simple Surf Web Script fetching London weather information</description>
   <family>Share</family>
   <url>/tutorial/london-weather</url>
</webscript>   

The template for a Web Script is defined in FreeMarker and looks something like this:

<div>
<#if weather?exists>
    <h1>London Weather Today</h1>
<h2>${weather[0].description}</h2>
<#else>
    Could not access weather information.
</#if>
</div>

The London weather web script does not need any authentication with Alfresco Community Edition so it could actually be called directly from the browser with the http://localhost:8080/share/service/tutorial/london-weather URL, and we should see a response similar to:

London Weather Today

light rain

It is more likely though that we would use this Web Scrip as a basis for a Surf Dashlet [21].

If we instead want to fetch and present data from the repository, we will most likely call an out-of-the-box repository web script, although it is common to implement and use your own repository web scripts. To connect and call an Alfresco repository web script (that is, Data web script) you will do something like this:

var filterValue = args.filter;
if (filterValue == null) {
   filterValue = "";
}
var connector = remote.connect("alfresco");
var peopleJSONString = connector.get("/api/people?filter=" + filterValue);
var peopleJSON = jsonUtils.toObject(peopleJSONString);

model.people = peopleJSON["people"];
model.filterValue = filterValue;  

For this controller to successfully pass on authentication information when making the repository web script call it need to be called in context of a Surf Page [20] or a Surf Dashlet [21]. Note the use of the alfresco connector [152] when communicating with a repository, This connector assumes that you will call the older deprecated v0 REST API [153] (http://localhost:8080/alfresco/service). We use it here as the feature of searching for people is not yet available in the v1 REST API.

We should use the v1 REST API [154] as much as possible, which requires a different connector called alfresco-api. Here is an example controller that uses the v1 API to get all the sites in the Repository:

var siteJSON = {}
var connector = remote.connect("alfresco-api");
var result = connector.get("/-default-/public/alfresco/versions/1/sites");
if (result.status.code == status.STATUS_OK) {
    var siteJSON = jsonUtils.toObject(result);
}

model.sites = siteJSON["list"]["entries"];

<#if sites?? && (sites?size > 0)>
<h1>Search Result:</h1>
    Found ${sites?size} sites.
    <#list sites as s>
        <br/>
        <a href="${url.context}/page/site/${s.entry.id}">${s.entry.title}</a>
    </#list>
<#else>
    Did not find any sites.
</#if>

var connector = remote.connect("alfresco-api");

// Get some stuff via CMIS REST API
var topFolderContentAsJSONString = connector.get("/-default-/public/cmis/versions/1.1/browser/root");

// Query via CMIS REST API
var queryStatement = encodeURIComponent("select * from cmis:document where cmis:name like 'Project%'");
var cmisQuery = "cmisselector=query&q=" + queryStatement + "&searchAllVersions=false&includeAllowableActions=false&includeRelationships=none&skipCount=0&maxItems=10";
var queryResult = connector.get("/-default-/public/cmis/versions/1.1/browser?" + cmisQuery);

var topFolderContentJSON = jsonUtils.toObject(topFolderContentAsJSONString);
var docs = jsonUtils.toObject(queryResult);

model.topContent = topFolderContentJSON["objects"];
model.docs = docs["results"];

<#if topContent?? && (topContent?size > 0)>
<h1>Top Folders:</h1>
    Found ${topContent?size} content items in the top folder (/Company Home).
<#list topContent as tc>
        <br/>
${tc.object.properties["cmis:name"].value}
    </#list>
<#else>
    Did not find any content items in the top folder (root).
</#if>

<#if docs?? && (docs?size > 0)>
<h1>Search Result:</h1>
    Found ${docs?size} documents.
<#list docs as d>
        <br/>
${d.properties["cmis:name"].value}
    </#list>
<#else>
    Did not find any documents.
</#if>

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ (Untouched by re-depolyments and upgrades)
• tomcat/webapps/share/components/ (when web resources are included you need to put them directly into the exploded webapp, this is NOT recommended. Use a Share AMP [114] project instead)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components (when web resources such as CSS and JS are included)

• Presentation Tier Web Scripts [155]
• Where to put your Web Scripts [156] (When trying them out without a build project)
• Controller Root Objects [157] (Root objects that can be used in the JavaScript controller)
• Template Root Objects [158] (Root objects that can be used when the main FreeMarker template for a Page is rendered)
• Component Root Objects [159] (Root objects that can be used when the FreeMarker template is rendered for a Page Component Web Script)
• Caching approach [160] - HTTP Response caching and Web Scripts (from repository web script section but still applicable)

  Important. There are two types [150] of web scripts, Repository Web Scripts [161] and Surf Web Scripts [155]. When you work with Surf web scripts you have access to different content (root objects [162]) then when using repository web scripts.

• Custom Surf Pages, Surf Dashlets, and Surf Web Scripts [163]

• XML Configuration [164] - Additional XML configuration for Web Script (from repository web script section but still applicable)
• Cache Control [165] - Additional Cache control configuration for Web Script (from repository web script section but still applicable)
• POST data processing [166] - Additional Cache control configuration for Web Script (from repository web script section but still applicable)
• Exploring the Root Objects [167]

• Share Architecture [8]

Build a Repository JAR instead.

• Spring Surf Root Object Reference [157] (Have a look at what root objects are already there)

Surf pages are the "old school" pages that most of the Share UI is built up around. But more and more pages are converted to Aikau pages [24]. All files involved in defining a Surf page are stored under /site-data and /templates.

Putting together a Surf page involves a lot of objects, such as page, template-instance, component, and so on. This is called the siteData [181] model and the following picture illustrates how these objects play together:

The definition of a Surf page [182] is done in XML and looks like this in a Hello World example:

<?xml version="1.0" encoding="UTF-8"?>
<page>
    <title>Hello World</title>
    <title-id>page.helloworld.title</title-id>
    <description>Hello World Description</description>
    <description-id>page.helloworld.description</description-id>
    <template-instance>helloworldhome-three-column</template-instance>
    <authentication>none</authentication>
</page>   

Page definition file names follow a naming convention: <page-id>.xml, the above page definition could be stored in a file called helloworld.xml under site-data/pages.

The page definition refers to a template instance [183] that links to the physical template, it is defined in XML:

<?xml version="1.0" encoding="UTF-8"?>
<template-instance>
    <template-type>org/alfresco/training/helloworld-1-column</template-type>
</template-instance>   

Template instance definition file names follow a naming convention: <template-instance-id>.xml, the above template instance definition could be stored in a file called helloworld-1-column.xml under site-data/template-instances.

The physical template is defined in FreeMarker and looks something like this:

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

Template files are stored under /templates.

The page is built up of different regions, and each region is defined for a specific scope, such as global or page. If the scope is page then we always need to implement the rendition for the region. This is done via a component [184], which is defined in XML:

<?xml version="1.0" encoding="UTF-8"?>
<component>
    <url>/components/helloworld/body</url>
</component>

The component just points to a Surf Web Script [18] that should render the HTML for the page region.

A Surf page is processed and generated via the Spring MVC framework. The following picture gives an overview of how it works:

As we can see in the picture, all dynamic content that should go onto the page is fetched indirectly via Surf Web Scripts, which can get the content from either the Alfresco Repository or from some other remote Web Service.

• tomcat/shared/classes/alfresco/web-extension/site-data/pages/ - Page definition
• tomcat/shared/classes/alfresco/web-extension/site-data/template-instances/ - Template instance pointing to FreeMarker template
• tomcat/shared/classes/alfresco/web-extension/site-data/components/ - Components fetching content and rendering presentation for a specific region in the physical template
• tomcat/shared/classes/alfresco/web-extension/templates - FreeMarker template location

For component Web Script file locations see: Web Script [18] section.

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/pages/
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/template-instances/
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/components/
• aio/share-jar/src/main/resources/alfresco/web-extension/templates

• Introduction to Surf Pages [185]) - This page contains a walk-through on how to create a Surf page, and it also has links to a page that shows how to create the same page with Aikau.
• Spring Surf Framework Guide [135] - Deep dive into the Surf framework
• Site Date Model Reference [181] - Details around all the model objects such as page, component, and template-instance.
• Surf root objects [157]
• Component rendering root objects [159]
• Template rendering root objects [158]

• Custom Surf Pages, Surf Dashlets, and Surf Web Scripts [163]

• Adding a new Surf page. [186]
• Making a new Surf page the default page. [187]
• Adding content to a Surf page [137]
• Removing/hiding content from a Surf page [138]
• Conditionally controlling rendering of content on Surf page [120]
• Exploring root objects that can be used in a template. [167]

• Adding a Surf page and making it the landing page [188]
• Adding a Surf page and making it the login page [189]
• Checksum dependencies for page resources [190]
• CSS Data Image Support in pages [191]

The following picture shows a User Dashboard with a number of Dashlets, such as My Sites and My Tasks:

You can implement your own custom dashlets that can be added to either the User Dashboard or the Site Dashboard.

The controller of the dashlet presentation web script will usually call a Data web script on the repository side to get the content that should be displayed in the dashlet.

Let's look at an example of a custom dashlet, the following picture shows a Member Directory dashlet that can be used to search the User/People directory:

This dashlet is implemented using a presentation web script, which in turn uses a Data web script to get the people matching the Search Filter parameter. The following picture illustrates:

In this case we have a Spring Surf Web Script on the Share side that will, in its controller, call a repository web script (that is Data Web Script) to get a list of person records in JSON format. The controller looks something like this:

// Get args from the Share page URL
var filterValue = page.url.args["filter"];
var connector = remote.connect("alfresco");
var peopleJSONString = connector.get("/api/people?filter=" + filterValue);

// create json object from data
var peopleJSON = jsonUtils.toObject(peopleJSONString);
model.people = peopleJSON["people"];  

The controller makes use of a special root object called remote [152], which is used to connect to a remote service, such as the repository, and get data. The JSON data is returned from a repository web script) (that is, a Data web script), which in its controller uses the public API to fetch person information matching passed in Search Filter (that is, filter).

The repository web script uses a root object called people to search for person info. This root object is Alfresco Community Edition specific and is only available in repository web scripts.

Now, to create a dashlet web script you also need a descriptor, which is defined in XML and looks something like this:

<webscript>
    <shortname>Member Directory</shortname>
    <description>Provide Search of people and display in a list</description>
    <family>user-dashlet</family>
    <url>/components/dashlets/member-directory</url>
</webscript>   

The descriptor looks like any other web script descriptor except the family parameter, which can have the following values:

<#-- JavaScript Dependencies
<@markup id="js">
</@>
-->

<#-- Stylesheet Dependencies
<@markup id="css">
</@>
 -->

<#-- Surf Widget creation
<@markup id="widgets">
    <@createWidgets group="dashlets"/>
</@>
-->

<@markup id="html">
    <@uniqueIdDiv>
        <#assign id = args.htmlid?html>
        <#assign dashboardconfig=config.scoped['Dashboard']['dashboard']>

        <div class="dashlet">
            <div class="title">${msg("member.directory.dashletName")}</div>
            <div id="${id}-memberdir" class="body">

                <div class="toolbar">
                    <div class="actions">
                        <form name="input"
                              action="${url.context}/page/user/${context.user.id}/dashboard"
                              method="get">
                        ${msg("member.directory.searchFilter")}: <input type="text" name="filter" />
                            <input type="submit" value="Search" />
                        </form>
                    </div>
                </div>

                <p valign="top">
                    <span>${msg("member.directory.searchResult")}</span>
                    <#list people as p>
                        <br/>
                        <a href="${url.context}/page/user/${p.userName}/profile">
                        ${p.firstName} ${p.lastName} (${p.email})
                        </a>
                    </#list>
                </p>

            </div>
        </div>
    </@>
</@>   

Here we are not using any custom client side JavaScript or CSS. Instead we use a simple HTML only based UI with default out-of-the-box styling. In the markup you will see references to i18n labels such ${msg("member.directory.searchResult")}. These messages are defined in the web script properties file as follows:

member.directory.dashletName=Member Directory
member.directory.searchFilter=Search Filter
member.directory.searchResult=Search Result   

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ (Untouched by re-depolyments and upgrades)
• tomcat/webapps/share/components/dashlets/ (when web resources are included you need to put them directly into the exploded webapp, this is NOT recommended.)

Best practice is to put the files in a directory that explains what they are for, such as for example:

tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/training/components/dashlets

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts/{custom path}
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components/dashlets (when web resources such as CSS and JS are included)

• Share Extras Project [193] - Contains loads of Dashlets, good place to go and look at how different types of Dashlets can be implemented.

• Custom Surf Pages, Surf Dashlets, and Surf Web Scripts [163]

• Share Extras Project [193] - Look at the source code for the dashlets in this project

We are going to look at implementing a custom Surf widget. To do this we will implement a very simple Hello World Dashlet that uses a Surf Widget.

The Dashlet will contain a Button that when clicked shows a message. The click handler and pop-up message will be handled by the Surf widget.

The finished Dashlet will look something like this:

When the user clicks the "Click Me!" button it will display a message in grey that fades away. If you hover over the Dashlet it will show a "?" for help in the toolbar. It will also be possible to resize the Dashlet. The Web Script controller looks like this:

// Dashlet widgets
var widgets = [];

// Main component
widgets.push({
    id: "HelloWorld",
    name: "MyCompany.dashlet.HelloWorld",
    options: {
        componentId: instance.object.id
    }
});

// Resizer
widgets.push({
    id : "DashletResizer",
    name : "Alfresco.widget.DashletResizer",
    initArgs : ["\"" + args.htmlid + "\"","\"" + instance.object.id + "\""],
    useMessages: false
});

// Title bar actions
var actions = [];
actions.push({
    cssClass: "help",
    bubbleOnClick:
    {
        message: msg.get("dashlet.help")
    },
    tooltip: msg.get("dashlet.help.tooltip")
});
widgets.push({
    id : "DashletTitleBarActions",
    name : "Alfresco.widget.DashletTitleBarActions",
    useMessages : false,
    options : {
        actions: actions
    }
});

model.widgets = widgets;   

The controller will put together a list of Spring Surf widgets that we can use. The first one is called MyCompany.dashlet.HelloWorld and this is the custom widget that we need to implement.

Here is the implementation of the Hello World widget:

/**
 * MyCompany root namespace.
 *
 * @namespace MyCompany
 */
if (typeof MyCompany == "undefined" || !MyCompany) {
    var MyCompany = {};
}

/**
 * MyCompany dashlet namespace.
 *
 * @namespace MyCompany.dashlet
 */
if (typeof MyCompany.dashlet == "undefined" || !MyCompany.dashlet) {
    MyCompany.dashlet = {};
}

/**
 * Sample Hello World dashboard component.
 *
 * @namespace MyCompany.dashlet
 * @class MyCompany.dashlet.HelloWorld
 * @author
 */
(function () {
    /**
     * YUI Library aliases
     */
    var Dom = YAHOO.util.Dom,
        Event = YAHOO.util.Event;

    /**
     * Alfresco Slingshot aliases
     */
    var $html = Alfresco.util.encodeHTML,
        $combine = Alfresco.util.combinePaths;


    /**
     * Dashboard HelloWorld constructor.
     *
     * @param {String} htmlId The HTML id of the parent element
     * @return {MyCompany.dashlet.HelloWorld} The new component instance
     * @constructor
     */
    MyCompany.dashlet.HelloWorld = function HelloWorld_constructor(htmlId) {
        return MyCompany.dashlet.HelloWorld.superclass.constructor.call(this, "MyCompany.dashlet.HelloWorld", htmlId);
    };

    /**
     * Extend from Alfresco.component.Base and add class implementation
     */
    YAHOO.extend(MyCompany.dashlet.HelloWorld, Alfresco.component.Base,
        {
            /**
             * Object container for initialization options
             *
             * @property options
             * @type object
             */
            options: {},

            /**
             * Fired by YUI when parent element is available for scripting
             *
             * @method onReady
             */
            onReady: function HelloWorld_onReady() {
                this.widgets.testButton = Alfresco.util.createYUIButton(this, "testButton", this.onButtonClick);
            },

            /**
             * Button click event handler
             *
             * @method onButtonClick
             */
            onButtonClick: function HelloWorld_onButtonClick(e) {
                Alfresco.util.PopupManager.displayMessage(
                    {
                        text: "Button clicked in Hello World Dashlet!"
                    });
            }
        });
})();   

This widget will create a YUI button and attach it to the element in the UI with the testButton id. The UI markup looks like this in the Web Script template:

<#-- JavaScript Dependencies -->
<@markup id="js">
    <@script type="text/javascript" src="${url.context}/res/components/dashlets/helloworld.js" group="dashlets"/>
</@>

<#-- Stylesheet Dependencies
<@markup id="css">
    <@link rel="stylesheet" type="text/css" href="${url.context}/res/components/dashlets/helloworld.css" group="dashlets"/>
</@>
-->

<#-- Widget creation -->
<@markup id="widgets">
    <@createWidgets group="dashlets"/>
</@>

<@markup id="html">
    <@uniqueIdDiv>
        <#assign el = args.htmlid?html>
        <#assign dashboardconfig=config.scoped['Dashboard']['dashboard']>

        <div class="dashlet">
            <div class="title">
            ${msg("hello.world.dashletTitle")}
            </div>
            <div class="body">
                <button id="${el}-testButton">${msg('hello.world.buttonLabel')}</button>
            </div>
        </div>
    </@>
</@>
   

Now, to create a Dashlet Web Script you also need a descriptor, which is defined in XML and looks something like this:

<webscript>
    <shortname>Hello World</shortname>
    <description>Hello World Dashlet</description>
    <family>dashlet</family>
    <url>/components/dashlets/helloworld</url>
</webscript>   

Here we are not using any custom client side CSS. Instead we use out-of-the-box styling. In the markup you will see references to i18n labels such ${msg("hello.world.buttonLabel")}. These messages are defined in the Web Script properties file as follows:

hello.world.dashletTitle=Hello World
hello.world.buttonLabel=Click Me!   

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ (Untouched by re-depolyments and upgrades)
• tomcat/webapps/share/components/ (when web resources are included you need to put them directly into the exploded webapp, this is NOT recommended.)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts/{custom path}
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/components (when web resources such as CSS and JS are included)

• Customizing widget instantiation [194]

• Custom Surf Pages, Surf Dashlets, and Surf Web Scripts [163]

• Customizing Surf Widget Instantiation [141]

• Display pop-up a message every time that a Document Library filter is changed [195]
• The technique behind customizing Share widgets [196]
• Referencing JavaScript objects declared in the FreeMarker template in the widget instantiation metadata [197]
• More on FreeMarker directives affecting widget instantiation [198]

The main menu and title in Share is implemented in Aikau, it looks like this:

Adding and removing menu items from the menu is a common task. To do this we use a Surf Extension Module [17]. It will look something like this:

<extension>
  <modules>
    <module>
      <id>Add custom menu item to header</id>
      <version>1.0</version>
      <auto-deploy>true</auto-deploy>  
      <customizations>
        <customization>
          <targetPackageRoot>org.alfresco.share.header</targetPackageRoot>
          <sourcePackageRoot>com.example.header</sourcePackageRoot>
        </customization>
      </customizations>
    </module>
  </modules>
</extension>   

So we are targeting the /share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header/share-header.get.js web wcript controller file, which implements the menu JSON model. Now, if we want to for example add a menu item we need to create a file with the same name and put it in alfresco/web-extension/site-webscripts/com/example/header. The file will look like this:

var headerMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_APP_MENU_BAR");
if (headerMenu != null) {
    headerMenu.config.widgets.push({
        id: "HEADER_CUSTOM_PROFILE_LINK",
        name: "alfresco/menus/AlfMenuBarItem",
            config: {
                label: "My profile",
                targetUrl: "user/" + encodeURIComponent(user.name) + "/profile"
            }
    });
}   

This is all that is required to extend an existing JSON model. We're using widgetUtils to find the HEADER_APP_MENU_BAR widget. Once we have it, we simply push a widget into it.

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ - put the files that are overriding here
• tomcat/shared/classes/alfresco/web-extension/site-data/extensions - put the Extension Module here.

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts - put the files that are overriding here
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - put the Extension Module here.

• Creating an Aikau page with Menus [200]
• Aikau Widget Reference [201] - this is the place to look for menu widgets that you can use.

• Customizing the Admin Tools Menu [202]
• Customizing the Sites Menu [203]
• Removing Menu Items [204]
• Aikau Tutorials on GitHub [205]

• Creating a simple Aikau page with Cascading Menu [206]
• Extending the Share Main Menu [207]

Aikau pages are the new type of pages that the Share UI will use in the future. Currently only the following pages are implemented in Aikau:

The web scripts controller is where all the fun happens. It is where you define your page layout in JSON, including all the Aikau Widgets that make up the page. It will look something like this for a Hello World page:

model.jsonModel = {
    widgets: [
        {
            id: "SET_PAGE_TITLE",
            name: "alfresco/header/SetTitle",
            config: {
                title: "Hello World"
            }
        }
    ]
};   

The template will be very simple and the only thing it does is this:

<@processJsonModel />   

It basically just processes the JSON model that we set-up in the controller. Here we have used an out of the box Aikau widget called alfresco/header/SetTitle, and the only thing left to do is to create the web scripts descriptor:

<webscript>
    <shortname>Hello World</shortname>
    <description>Hello World page definition</description>
    <family>Share</family>
    <url>/helloworld</url>
</webscript>   

An Aikau page is processed and generated via the Spring Surf and Spring MVC framework. The following picture gives an overview of how it works:

As we can see in the picture, all dynamic content that should go onto the page is fetched indirectly via Aikau Widgets, which can get the content from either the repository or from some other remote Web Service. Worth noting here is that we are actually using a Surf Page when we are invoking an Aikau page, in the Hello World example we are used the hybrid dynamic page (hdp) to get the Share header and footer included.

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ (Untouched by re-depolyments and upgrades)
• tomcat/shared/classes/alfresco/web-extension/site-data/extensions (Untouched by re-depolyments and upgrades)
• tomcat/webapps/share/js/ (when web resources are included, such as Aikau Widgets, you need to put them directly into the exploded webapp, this is NOT recommended.)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts - Aikau page web scripts
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension modules with Dojo package definitions
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/js/<dojo package> - web resources, such as Aikau Widgets

• Introduction to Aikau Pages [208] - This page contains a walk-through on how to create an Aikau page, and it also has links to a page that shows how to create the same page with old-school Surf.
• Introduction to Aikau [209]
• Creating an Aikau page with Menus [200]
• Aikau Widget Reference [201] - this is the place to look for widgets that you can use in your pages.

• Adding new AMD packages for Aikau Widgets [143]
• Aikau Tutorials on GitHub [205]

• Creating a simple Aikau page with Cascading Menu [206]
• Creating a simple Aikau page with a button on it. [210]
• Aikau background and concepts [211]
• Deep dive into Dojo, Dijit, and Aikau development [212]
• Aikau Tutorial [213]

The preferred new way of adding custom Share dashlets is via the new Aikau UI development framework. An Aikau dashlet is defined via a Surf web script in the same way you define an Aikau page. The controller with the JSON model contains one widget referencing a dashlet widget, which in turn can use any other number of Aikau widgets to build up the dashlet content.

Let's say we wanted to implement a simple Hello World dashlet in Aikau that looks like this:

This dashlet contains the following Aikau Widgets [26]: the dashlet itself, two toolbar widgets, a vertical layout widget, a logo widget, and a Hello widget. To implement it start with the Surf Web Script [18].

The web script controller is where we specify what Aikau Widget that is implementing the dashlet, it is called acmedashlet/HelloDashlet in this case. The controller will look something like this for the above Hello World dashlet:

model.jsonModel = {
    rootNodeId: args.htmlid,
    pubSubScope: instance.object.id,
    /* Include Aikau services here, for example :
    services: [
        { name: "alfresco/services/ReportService" },
        { name: "alfresco/services/NavigationService" }
    ],*/
    widgets: [
        {
            id: "HELLO_DASHLET",
            name: "acmedashlets/HelloDashlet"
        }
    ]
};

Note that we can include service widgets here too if they are needed, in our case we are just showing a Hello World message so we don't need any services. The dashlet class HelloDashlet.js lives in a JavaScript package called acmedashlets. So for the AMD loader to actually find this class we need to configure a Surf extension module with this information as follows:

<extension>
    <modules>
        <module>
            <id>add-aikau-dashlet-share - ACME Dashlet and 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="acmedashlets" location="js/tutorials/dashlets"/>
                                <package name="acmewidgets" location="js/tutorials/dashlets/widgets"/>
                            </packages>
                        </dojo-pages>
                    </web-framework>
                </config>
            </configurations>
        </module>
    </modules>
</extension>

Here we have also configured another package called acmewidgets for any other Aikau widgets that we will use as content in our dashlet. These packages points to physical locations in our produced artifact. So we need to put these widgets at specific paths in our AMP project. For example, the dashlet JavaScript file called HelloDashlet.js need to be located in the share-amp/src/main/amp/web/js/tutorials/dashlets directory.

The Surf web script template will be very simple and the only thing it does is this process the JSON model defined in the controller:

<@markup id="widgets">
    <@processJsonModel group="share-dashlets" rootModule="alfresco/core/Page"/>
</@>

<@markup id="html">
    <div id="${args.htmlid?html}"></div>
</@>

To complete the Surf web script a descriptor is also needed:

<webscript>
    <shortname>Hello Dashlet</shortname>
    <description>A dashlet that displays an Alfresco logo and a Hello message</description>
    <family>dashlet</family>
    <url>/tutorials/dashlets/hello</url>
</webscript>

define(["dojo/_base/declare",
        "alfresco/core/Core",
        "alfresco/core/I18nUtils",
        "alfresco/dashlets/Dashlet"],
    function(declare, AlfCore, I18nUtils, Dashlet) {

        return declare([Dashlet], {
            additionalCssClasses: "mediumpad",
            bodyHeight: 200,
            componentId: "component.hello-dashlet",
            i18nScope: "tutorials.dashlets.HelloDashlet",
            i18nRequirements: [{i18nFile: "./i18n/HelloDashlet.properties"}],

            widgetsForTitleBarActions: [
                {
                    id: "HELLO_DASHLET_ACTIONS",
                    name: "alfresco/html/Label",
                    config: {
                        label: "Title-bar actions"
                    }
                }
            ],

            widgetsForToolbar: [
                {
                    id: "HELLO_DASHLET_TOOLBAR",
                    name: "alfresco/html/Label",
                    config: {
                        label: "Toolbar"
                    }
                }
            ],

            widgetsForToolbar2: [
                {
                    id: "HELLO_DASHLET_TOOLBAR2",
                    name: "alfresco/html/Label",
                    config: {
                        label: "Toolbar2"
                    }
                }
            ],

            widgetsForBody: [
                {
                    id: "HELLO_DASHLET_VERTICAL_LAYOUT",
                    name: "alfresco/layout/VerticalWidgets",
                    config: {
                        widgetWidth: 50,
                        widgets: [
                            {
                                id: "HELLO_DASHLET_ALFRESCO_LOGO_WIDGET",
                                name: "alfresco/logo/Logo",
                                config: {
                                    logoClasses: "alfresco-logo-only"
                                }
                            },
                            {
                                id: "HELLO_DASHLET_HELLO_WIDGET",
                                name: "acmewidgets/HelloDashletWidget"
                            }
                        ]
                    }
                }
            ]

        });
    });

There are a number of properties here that are defined in the base dashlet class alfresco/dashlets/Dashlet, they can be used for the following:

To implement this widget we need to create a JavaScript file called HelloDashletWidget.js and put it in the /js/tutorials/dashlets/widgets directory. The source code for the widget looks like this:

define(["dojo/_base/declare",
    "dijit/_WidgetBase",
    "alfresco/core/Core",
    "dijit/_TemplatedMixin",
    "dojo/text!./templates/HelloDashletWidget.html"
],
function(declare, _Widget, Core, _Templated, template) {
    return declare([_Widget, Core, _Templated], {
        templateString: template,
        i18nRequirements: [ {i18nFile: "./i18n/HelloDashletWidget.properties"} ],
        cssRequirements: [{cssFile:"./css/HelloDashletWidget.css"}],

        buildRendering: function org_tutorials_dashlets_HelloDashletWidget__buildRendering() {
            this.greeting = this.message('hello-label');

            this.inherited(arguments);

        }
    });
});      

<div class="hello-dashlet-widget">${greeting}</div>

hello-label=Hello Dashlet!

.hello-dashlet-widget {
    border: 4px #000000 solid;
    padding: 1em;
    width: 100px;
}      

• tomcat/shared/classes/alfresco/web-extension/site-webscripts/ (Untouched by re-depolyments and upgrades)
• tomcat/shared/classes/alfresco/web-extension/site-data/extensions (Untouched by re-depolyments and upgrades)
• tomcat/webapps/share/js/ (when web resources are included, such as Aikau Widgets, you need to put them directly into the exploded webapp, this is NOT recommended.)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts - Aikau dashlet web scripts
• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension modules with Dojo package definitions
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/js/<dojo package> - web resources, such as the dashlet Widget and other Aikau Widgets making up the content.

• Introduction to Aikau [209]
• Aikau Widget Reference [201] - this is the place to look for widgets that you can use in your dashlets.

• Hello World dashlet implementation [215]

• Adding new AMD packages for Aikau Widgets [143]
• Aikau Tutorials on GitHub [205]

Aikau menus, pages, and dashlets are all using Aikau widgets to build their user interface. An Aikau Widget contains both JavaScript, HTML, CSS, and resource properties to form a self contained component. Aikau widgets are implemented as Dojo classes and uses classes from the Dijit widget library. Alfresco Share comes with a lot of Aikau widgets out of the box such as for example:

For a full list of widgets, and documentation, see Aikau Widget Library [201]. If there is no widget here that fits your needs then you implement your own custom Aikau widget. Let's take an example of a simple page with a custom HelloWorld widget, the page JSON looks like this:

model.jsonModel = {
    widgets: [
        {
            id: "SET_PAGE_TITLE",
            name: "alfresco/header/SetTitle",
            config: {
                title: "Hello World"
            }
        },
        {
            id: "DEMO_SIMPLE_MSG",
            name: "example/widgets/HelloWorldTextWidget"
        }
    ]
};      

Here we got a custom widget called HelloWorldTextWidget in the Dojo AMD package exmaple/widgets. To implement this widget we need to create a JavaScript file called HelloWorldTextWidget.js and put it in the /js/example/widgets directory. The implementation of the widget looks like this:

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

            }
        });
});      

<div class="helloWorldMsgStyle">${helloWorldMsg}</div>

hello.world=This is just a test page. Hello World! (Aikau)

.helloWorldMsgStyle {
    border: 1px #000000 solid;
    padding: 1em;
    width: 100px;
    background-color:lightgrey;
}      

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

Best practice is to put the file in a directory that explains what the file is for, such as for example:

tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/training/components/form/controls

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension modules with Dojo package definitions (i.e. the JavaScript packages where the Widgets live)
• aio/share-jar/src/main/resources/META-INF/resources/share-jar/js/<dojo package> - web resources, such as Aikau Widgets

• Introduction to Aikau [209]
• Aikau Widget Reference [201] - Look here before you start creating widgets, one might exist that does what you want.

• Adding new AMD packages for Aikau Widgets [143]
• Aikau Tutorials on GitHub [205]

• Aikau background and concepts [211]
• Creating custom Aikau Widgets [216]
• Deep dive into Dojo, Dijit, and Aikau development. [212] - lots of information around creating Aikau widgets
• Aikau Tutorial [213]

The preferred way of modifying out-of-the-box Surf Web Scripts is by using Surf Extension Modules [17] to target the Web Script that should be replaced:

<extension>
    <modules>
        <module>
            <id>Customize a Web Script</id>
            <version>1.0</version>
            <auto-deploy>true</auto-deploy>
            <customizations>
                <customization>
                    <targetPackageRoot>The path to the out-of-the-box Web Script you are overriding, such as org.alfresco.components.dashlets</targetPackageRoot>
                    <sourcePackageRoot>The path to your Web Script customizations, such as org.alfresco.tutorials.customization.webscript.controller</sourcePackageRoot>
                </customization>
            </customizations>
        </module>
    </modules>
</extension>

The Web Script files in your package should have the same names as the original ones that you are overriding. The Extension Modules section has all the details.

Out-of-the-box Surf Web Scripts used to be overridden by putting the modified files under alfresco/web-extension/site-webscripts/org/alfresco/... directory using the exact same path. This approach is no longer needed.

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Store extension modules here
• aio/share-jar/src/main/resources/alfresco/web-extension/site-webscripts - Your Web Script overrides are stored here under a custom package path

• Surf Web Scripts [18]
• Surf Extension Modules [17]

• See Surf Extension Modules [17]

The preferred way of modifying Surf pages is by using Surf Extension Modules [17] to target the component that should be replaced or hidden. It is also possible to add components to a page this way. The Extension Modules section has all the details.

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Store extension modules here

• Surf Pages [20]

• See Surf Extension Modules [17]

The preferred way of modifying Surf dashlets is by using Surf Extension Modules [17] to target the component that should be replaced or hidden. It is also possible to add components to a dashlet this way. The Extension Modules section has all the details.

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Store extension modules here

• Surf Dashlets [21]

• See Surf Extension Modules [17]

The preferred way of modifying Surf widgets is by using Surf Extension Modules [17] to target the component that has the widget that should be replaced or hidden. It is also possible to add widgets to a page this way. The Extension Modules section has all the details.

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Store extension modules here

• Surf Widgets [22]

• See Surf Extension Modules [17]

Now, if we want to modify an existing page we need to grab hold of it in the Web Script controller, this will look like this:

var widget = widgetUtils.findObject(model.jsonModel.widgets, "id", "FCTSRCH_SEARCH_RESULTS_LIST");
if (widget && widget.config && widget.config.widgets) {
   widget.config.widgets.push( {
...   

This is all that is required to extend an existing JSON model. We're using widgetUtils to find the FCTSRCH_SEARCH_RESULTS_LIST widget. Once we have it, we simply push widgets into it.

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension module goes here

• Aikau Pages [24]
• Introduction to Aikau [209]
• Aikau Widget Reference [217] - this is the place to look for widgets that you can use in your dashlets.

• Aikau Tutorials on GitHub [205]
• Adding new AMD packages for Aikau Widgets [143]

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension modules go here

• Aikau Dashlets [25]
• Introduction to Aikau [209]
• Aikau Widget Reference [201] - this is the place to look for widgets that you can use in your dashlets.

• Aikau Tutorials on GitHub [205]
• Adding new AMD packages for Aikau Widgets [143]

• tomcat/shared/classes/alfresco/web-extension/site-data/extensions/ (Untouched by re-depolyments and upgrades)

• aio/share-jar/src/main/resources/alfresco/web-extension/site-data/extensions - Extension modules go here

• Aikau Widgets [26]
• Aikau Widget Reference [201] - this is the place to look for widgets that you can use in your dashlets.
• Introduction to Aikau [209]

• Aikau Tutorials on GitHub [205]
• Adding new AMD packages for Aikau Widgets [143]