Alfresco Share provides a configurable web interface for working with documents, sites, workflows, metadata, searches and collaboration features in Alfresco Content Services.

For enterprise implementations, however, the default Share interface is rarely the end of the story.

Projects often require custom dashboards, new actions, organization-specific branding, additional metadata, custom menus, specialized dashlets and integration with external business applications.

This is where Alfresco Share customization becomes important.

In this practical guide, we'll explore how Alfresco Share can be extended using Surf, Share configuration, extension modules, dashlets, widgets and web scripts, while keeping customizations separate from the Alfresco product code.

What You Will Learn

By the end of this guide, you should understand:

Alfresco Share customization architecture
Share UI extension points
Surf framework fundamentals
share-config-custom.xml
Surf Extension Modules
Custom dashlet architecture
Share web scripts
FreeMarker templates
JavaScript and CSS customization
Document Library extensions
Packaging customizations
Deployment and troubleshooting
Upgrade-safe customization practices

French version: https://shikhanirankari.blogspot.com/2026/09/personnalisation-alfresco-share-dashlets-surf.html

1. Understanding Alfresco Share Architecture

Alfresco Share is the web collaboration interface commonly used with Alfresco Content Services.

A useful simplified architecture is:

Browser → Alfresco Share → Surf/Web Scripts → Alfresco Repository → Database/Content Store/Search

Share acts as the presentation layer while repository services manage content, metadata, permissions, workflows and other repository capabilities.

The official Alfresco documentation identifies a broad set of Share extension points, including Share configuration, Document Library extensions, themes, web scripts, Surf pages, Surf dashlets, Surf widgets and Surf Extension Modules.

2. Why Customize Alfresco Share?

Consider an organization using Alfresco for contract management.

The business may want to display:

Contract Number | Customer | Expiry Date | Contract Value | Approval Status

It may also require actions such as:

Submit for Approval

or:

Send to Legal Review

Instead of creating an entirely separate application, these capabilities can often be incorporated into Share.

Typical Alfresco Share customization requirements include:

Custom document actions
Additional metadata fields
Custom forms
Dashboard dashlets
Custom navigation
Branding
Conditional actions
Repository integrations
Custom search interfaces
Business-specific pages

3. Important Alfresco Share Extension Points

A Share implementation can be customized at several levels.

Requirement	Common Extension Mechanism
Change Share configuration	`share-config-custom.xml`
Add UI functionality	Surf Extension Module
Create dashboard component	Dashlet
Add page/component	Surf component
Retrieve dynamic data	Web Script
Render HTML	FreeMarker
Client-side behaviour	JavaScript
UI styling	CSS
Add Document Library action	DocLib Action
Conditional UI	Evaluator
Custom metadata display	Metadata Template

Understanding which extension point to use prevents unnecessary overrides.

4. What Is Apache Surf in Alfresco?

Surf provides the web framework behind much of the traditional Alfresco Share interface.

Instead of thinking of a Share page as one large HTML file, think of it as a composition of:

Pages → Templates → Regions → Components → Web Scripts

This modular architecture allows developers to extend specific pieces of the interface.

5. share-config-custom.xml

One of the best-known Share configuration files is:


share-config-custom.xml

It is commonly located under the Share extension configuration area, for example:


alfresco/web-extension/share-config-custom.xml

It can be used for various Share-level configuration requirements.

A simplified configuration structure looks like:


<alfresco-config>

    <config evaluator="string-compare"
            condition="DocumentLibrary">

        <!-- Custom Document Library configuration -->

    </config>

</alfresco-config>

The important principle is to place custom configuration in extension locations rather than modifying Alfresco's packaged files directly.

6. Surf Extension Modules

For many Share customizations, Surf Extension Modules provide a cleaner mechanism than directly modifying existing Share resources.

A basic conceptual module looks like:


<extension>
    <modules>

        <module>
            <id>My Share Customization</id>
            <version>1.0</version>
            <auto-deploy>true</auto-deploy>

            <customizations>

                <!-- Customization definitions -->

            </customizations>

        </module>

    </modules>
</extension>

Modules allow related UI customizations to be packaged together.

This is particularly useful when maintaining multiple customizations across DEV, SIT, UAT and Production environments.

Alfresco's official Document Library tutorial also demonstrates defining Document Library actions through a Surf Extension Module rather than directly modifying product resources.

7. Alfresco Share Dashlets

A dashlet is a small component displayed on an Alfresco dashboard.

Examples include:

My Tasks
My Activities
Recently Modified Documents
Site Activities
Custom reports
Business KPIs

An organization could create a custom dashlet such as:

Documents Expiring This Month

or:

Contracts Awaiting Approval

Typical Custom Dashlet Architecture

A dashlet commonly involves:


Descriptor
    ↓
Controller
    ↓
FreeMarker Template
    ↓
CSS / JavaScript
    ↓
Repository/API Data

8. Creating a Simple Share Web Script

Web scripts are fundamental building blocks in Alfresco extension development.

Alfresco describes repository web scripts as REST-oriented extension mechanisms that can be defined using descriptors, JavaScript and FreeMarker templates.

A web script normally contains files such as:


document-status.get.desc.xml
document-status.get.js
document-status.get.html.ftl

Descriptor


<webscript>

    <shortname>Document Status</shortname>

    <description>
        Returns document status information
    </description>

    <url>/custom/document-status</url>

    <format default="html"/>

    <authentication>user</authentication>

</webscript>

JavaScript Controller


model.title = "Document Status";
model.status = "Approved";

FreeMarker Template


<h2>${title}</h2>

<p>
    Current Status:
    <strong>${status}</strong>
</p>

The browser-facing component can then render the information supplied by the controller.

9. Repository Web Scripts vs Share Web Scripts

This distinction is important.

Repository Web Script

Runs against the Alfresco Repository tier and is commonly used to expose or process repository data.

Conceptually:


Client
   ↓
Repository Web Script
   ↓
Repository Services

Share Web Script

Runs in the Share tier and is primarily concerned with presentation and Share-side behaviour.

Conceptually:


Browser
   ↓
Share Web Script
   ↓
Share
   ↓
Repository API

In some customizations, Share calls repository web scripts through the Share proxy.

The official Alfresco Document Library tutorial demonstrates this approach, including calling a custom repository web script through Share.

10. Custom Document Library Actions

Document Library actions are among the most useful Share customizations.

For example, suppose users need:

Send for Legal Approval

against selected documents.

The action can be configured and then connected to JavaScript or repository-side logic.

Conceptually:


<action id="custom.sendForApproval"
        type="javascript"
        icon="approval">

    <param name="function">
        onSendForApproval
    </param>

</action>

The actual implementation can then call a repository action or web script.

A Document Library action generally requires some combination of:

Action configuration → Visibility → Icon → JavaScript → Evaluator → Repository operation

Alfresco's official tutorial describes essentially this pattern for custom Document Library actions.

Alfresco Document Library custom action using Share customization

11. Conditional Actions with Evaluators

Not every action should be displayed to every user or against every document.

For example:

Approve Contract

should perhaps appear only when:


Document Type = Contract
AND
Status = Pending Approval
AND
User has required permission

Evaluators allow Share extensions to control UI visibility based on conditions.

This improves both usability and security design, although server-side authorization must still protect the actual operation.

Never treat hiding a button in the UI as an authorization mechanism.

12. Customizing Metadata Display

Enterprise Alfresco installations frequently use custom content models.

For example:


acme:contract

with properties such as:


acme:contractNumber
acme:customerName
acme:expiryDate
acme:contractValue
acme:approvalStatus

Share can be configured to display these properties in forms and Document Library views.

A conceptual configuration might look like:


<field id="acme:contractNumber">
    <control template="/org/alfresco/components/form/controls/textfield.ftl"/>
</field>

This allows business metadata to become part of the user experience rather than remaining hidden at repository level.

13. JavaScript Widget Customization

Sometimes the requirement goes beyond configuration.

You might need to modify the behaviour of an existing Share widget.

The safer approach is generally to extend or replace behaviour through supported extension mechanisms rather than copying and editing Alfresco's original JavaScript.

Alfresco's documentation demonstrates customizing the Document List widget through a Surf Extension Module and custom JavaScript widget.

This reduces the maintenance burden during upgrades.

14. Styling Share with CSS

Custom CSS can be used for requirements such as:

Corporate branding
Button styling
Dashboard presentation
Fonts
Spacing
Headers
Navigation appearance

For example:


.custom-approval-button {
    padding: 8px 14px;
    border-radius: 4px;
    font-weight: 600;
}

Avoid editing Alfresco's original CSS files directly.

Keep custom styling inside your extension so it can be versioned, tested and removed independently.

15. Packaging Share Customizations

For enterprise environments, customizations should be treated as software—not as manual server changes.

A typical project structure may contain:


src/
 └── main/
     └── resources/
         ├── alfresco/
         │   └── web-extension/
         │       ├── share-config-custom.xml
         │       ├── site-data/
         │       └── site-webscripts/
         │
         └── META-INF/
             └── resources/
                 ├── css/
                 ├── js/
                 └── images/

The exact structure depends on the Alfresco version, SDK and packaging approach being used.

16. Recommended Enterprise Deployment Flow

Do not build or modify custom Share code directly in Production.

Use a controlled pipeline:


Developer Workstation
        ↓
Source Control
        ↓
Build
        ↓
DEV
        ↓
SIT
        ↓
UAT
        ↓
Pre-Production
        ↓
Production

Each environment should receive the same versioned artifact.

17. Upgrade-Safe Alfresco Share Customization

This is one of the most important areas in real enterprise projects.

Avoid


Editing files directly under webapps/share
Replacing Alfresco JARs
Changing product JavaScript directly
Changing original FreeMarker files
Making undocumented server changes

These approaches create technical debt and make upgrades considerably harder.

Prefer


Extension modules
Custom JARs
Custom configuration
Custom CSS/JavaScript resources
Web scripts
Supported Share extension points
Source-controlled deployment

A good customization should be something you can:

install → test → upgrade → disable → remove

without permanently altering the base product.

18. Common Alfresco Share Customization Problems

Custom module does not appear

Check:

Deployment status
Extension module configuration
Resource paths
XML syntax
Application logs

JavaScript changes don't appear

Check:

Browser cache
Share caches
Resource path
Minification/resource loading
Whether the correct extension is deployed

Dashlet isn't available

Check:

Dashlet descriptor
Web script registration
Component configuration
Template/controller naming
Server logs

Web Script returns 404

Verify the web script registration and URL.

For repository web scripts, also confirm that the descriptor is being discovered and that the correct repository context is being used.

19. Performance Considerations

A visually simple dashlet can still be expensive.

For example, avoid designs where every dashboard load executes:


Large repository query
+
multiple REST calls
+
expensive permission checks
+
large JSON response

Instead consider:

Smaller queries
Pagination
Appropriate caching
Asynchronous loading
Efficient repository APIs
Limiting returned properties
Avoiding unnecessary calls

Performance testing should include realistic repository volumes rather than only a nearly empty development environment.

20. Security Considerations

Share customization must not bypass repository security.

Always consider:

Authentication

Who is making the request?

Authorization

Does that user have permission to perform the operation?

Input validation

Never blindly trust values received from the browser.

Output encoding

Encode user-controlled values appropriately to reduce injection risks.

Repository permissions

Business operations should ultimately be protected on the server side.

A hidden UI action is not a security boundary.

21. Choosing the Right Customization Approach

A useful decision model is:


Need configuration only?
        ↓
share-config-custom.xml / extension configuration

Need new UI component?
        ↓
Surf component / Dashlet

Need new presentation logic?
        ↓
Share Web Script / Widget

Need repository data or operation?
        ↓
Repository API / Repository Web Script

Need Document Library functionality?
        ↓
DocLib Extension + Action

Need conditional UI?
        ↓
Evaluator

Choosing the smallest appropriate extension point generally results in a solution that is easier to maintain.

22. Example Enterprise Use Case

Imagine a financial organization using Alfresco to manage loan documents.

The requirement is:

Display all loan files waiting for compliance review on the user's dashboard and allow authorized users to open the document directly.

A possible architecture would be:


Custom Compliance Dashlet
          ↓
Share Web Script
          ↓
Repository API/Web Script
          ↓
Search for Pending Compliance Documents
          ↓
JSON Response
          ↓
FreeMarker / JavaScript Rendering
          ↓
User Dashboard

This combines several concepts covered in this guide without requiring changes to Alfresco's core product files.

23. Share Customization Checklist

Before releasing an Alfresco Share customization, verify:

✅ Custom code is separated from Alfresco product code
✅ Extension is source controlled
✅ No direct modification of deployed Share files
✅ Permissions are enforced server-side
✅ JavaScript/CSS resources load correctly
✅ Dashlets handle empty/error states
✅ Repository calls are optimized
✅ Logs contain no unexpected errors
✅ Customization has been tested across supported browsers
✅ Upgrade compatibility has been assessed
✅ Deployment and rollback procedures are documented

Conclusion

Alfresco Share can be extended far beyond its default user interface.

The key is not simply knowing JavaScript or XML. A maintainable implementation requires understanding how Share, Surf, web scripts, dashlets, widgets, configuration and repository services work together.

For relatively simple requirements, configuration may be enough. For richer requirements, Surf Extension Modules, custom dashlets, Document Library extensions and web scripts provide powerful extension mechanisms.

Most importantly, enterprise Alfresco customizations should remain modular, source-controlled, testable and upgrade-aware.

That approach makes future Alfresco upgrades considerably easier than modifying out-of-the-box Share resources directly.

📢 Need help with Java, workflows, or backend systems?

I help teams design scalable, high-performance, production-ready applications and solve critical real-world issues.

Services:

Java & Spring Boot development
Camunda Training / consulting
Alfresco Training / consulting
Workflow architecture guidance
Workflow implementation (Camunda, Flowable – BPMN, DMN)
Backend & API integrations (REST, microservices)
Document management & ECM integrations (Alfresco)
Performance optimization & production issue resolution
🔗 https://shikhanirankari.blogspot.com/p/professional-services.html
📩 Email: ishikhanirankari@gmail.com | info@realtechnologiesindia.com
🌐 https://realtechnologiesindia.com
✔ Available for quick consultations
✔ Response within 24 hours

🎥 Learn IT with Shikha on YouTube

Prefer learning through videos? Watch practical tutorials on Kafka, Camunda, Alfresco, Java, Spring Boot, Microservices and Enterprise Architecture.

▶ Subscribe to Learn IT with Shikha on YouTube

Alfresco Share Customization Guide: UI Extensions, Dashlets & Surf Configuration

What You Will Learn

1. Understanding Alfresco Share Architecture

2. Why Customize Alfresco Share?

3. Important Alfresco Share Extension Points

4. What Is Apache Surf in Alfresco?

5. share-config-custom.xml

6. Surf Extension Modules

7. Alfresco Share Dashlets

Typical Custom Dashlet Architecture

8. Creating a Simple Share Web Script

Descriptor

JavaScript Controller

FreeMarker Template

9. Repository Web Scripts vs Share Web Scripts

Repository Web Script

Share Web Script

10. Custom Document Library Actions

11. Conditional Actions with Evaluators

12. Customizing Metadata Display

13. JavaScript Widget Customization

14. Styling Share with CSS

15. Packaging Share Customizations

16. Recommended Enterprise Deployment Flow

17. Upgrade-Safe Alfresco Share Customization

Avoid

Prefer

18. Common Alfresco Share Customization Problems

Custom module does not appear

JavaScript changes don't appear

Dashlet isn't available

Web Script returns 404

19. Performance Considerations

20. Security Considerations

21. Choosing the Right Customization Approach

22. Example Enterprise Use Case

23. Share Customization Checklist

Conclusion

Recommended Articles

🎥 Learn IT with Shikha on YouTube

📢 Need help with Java, workflows, or backend systems?

I help teams design scalable, high-performance, production-ready applications and solve critical real-world issues.

Services:

🎥 Learn IT with Shikha on YouTube

Comments

Post a Comment

Popular posts from this blog

Top 50 Camunda BPM Interview Questions and Answers for Developers (2026 Guide)

10 BPMN Best Practices Every Camunda Developer Should Know

OOPs Concepts in Java | English | Object Oriented Programming Explained