Alfresco Share fournit une interface web configurable permettant de gérer les documents, sites, workflows, métadonnées, recherches et fonctions collaboratives d’Alfresco Content Services.

Dans les implémentations d’entreprise, l’interface Share standard ne suffit cependant pas toujours.

Les projets nécessitent souvent des tableaux de bord personnalisés, de nouvelles actions, une identité visuelle propre à l’organisation, des métadonnées supplémentaires, des menus spécifiques, des dashlets métier ou encore des intégrations avec des applications externes.

C’est là que la personnalisation d’Alfresco Share devient essentielle.

Dans ce guide pratique, nous allons découvrir comment étendre Alfresco Share à l’aide de Surf, des modules d’extension, des dashlets, des widgets, des Web Scripts et de la configuration Share, tout en évitant de modifier directement le code standard d’Alfresco.

Ce que vous allez apprendre

À la fin de ce guide, vous comprendrez notamment :

l’architecture de personnalisation d’Alfresco Share ;
les principaux points d’extension de Share ;
les fondamentaux du framework Surf ;
le rôle de share-config-custom.xml ;
les Surf Extension Modules ;
l’architecture des dashlets personnalisés ;
les Web Scripts Share et Repository ;
les templates FreeMarker ;
les personnalisations JavaScript et CSS ;
les extensions de la Document Library ;
le packaging et le déploiement ;
les bonnes pratiques pour faciliter les mises à niveau.

English version: https://shikhanirankari.blogspot.com/2026/09/alfresco-share-customization-ui-dashlets-surf.html

1. Comprendre l’architecture d’Alfresco Share

Alfresco Share est l’interface web collaborative traditionnellement utilisée avec Alfresco Content Services.

Une architecture simplifiée peut être représentée ainsi :

Navigateur → Alfresco Share → Surf / Web Scripts → Alfresco Repository → Base de données / Content Store / Search

Share constitue principalement la couche de présentation, tandis que le Repository gère les contenus, métadonnées, permissions, workflows et autres services documentaires.

Alfresco propose plusieurs points d’extension pour Share, notamment la configuration Share, les extensions de la Document Library, les thèmes, les Web Scripts, les pages Surf, les dashlets, les widgets et les Surf Extension Modules.

2. Pourquoi personnaliser Alfresco Share ?

Prenons l’exemple d’une entreprise qui utilise Alfresco pour gérer ses contrats.

Elle peut souhaiter afficher :

Numéro du contrat | Client | Date d’expiration | Valeur | Statut d’approbation

Elle peut également avoir besoin d’actions métier telles que :

Envoyer pour approbation

ou :

Envoyer à la direction juridique

Au lieu de développer une application complètement indépendante, il est souvent possible d’intégrer ces fonctionnalités directement dans Share.

Les besoins courants de personnalisation incluent :

des actions documentaires personnalisées ;
des champs de métadonnées supplémentaires ;
des formulaires personnalisés ;
des dashlets de tableau de bord ;
une navigation personnalisée ;
le branding de l’entreprise ;
des actions conditionnelles ;
l’intégration avec le Repository ;
des interfaces de recherche personnalisées ;
des pages spécifiques aux processus métier.

3. Principaux points d’extension d’Alfresco Share

Une implémentation Share peut être personnalisée à plusieurs niveaux.

Besoin	Mécanisme d’extension courant
Modifier la configuration Share	`share-config-custom.xml`
Ajouter une fonctionnalité UI	Surf Extension Module
Créer un composant de dashboard	Dashlet
Ajouter une page ou un composant	Composant Surf
Récupérer des données dynamiques	Web Script
Générer du HTML	FreeMarker
Ajouter un comportement côté client	JavaScript
Personnaliser l’interface	CSS
Ajouter une action Document Library	DocLib Action
Affichage conditionnel	Evaluator
Afficher des métadonnées spécifiques	Metadata Template

Choisir le bon point d’extension permet d’éviter des personnalisations inutilement complexes.

4. Qu’est-ce que le framework Surf dans Alfresco ?

Surf est le framework web à la base d’une grande partie de l’interface traditionnelle Alfresco Share.

Au lieu de considérer une page Share comme un seul grand fichier HTML, il est préférable de la voir comme une composition :

Pages → Templates → Régions → Composants → Web Scripts

Cette architecture modulaire permet de personnaliser des parties précises de l’interface.

5. Configuration avec share-config-custom.xml

L’un des fichiers de configuration Share les plus connus est :


share-config-custom.xml

Il se trouve généralement dans la zone d’extension de Share, par exemple :


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

Il peut être utilisé pour différents besoins de configuration de l’interface Share.

Exemple simplifié :


<alfresco-config>

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

        <!-- Configuration personnalisée de la Document Library -->

    </config>

</alfresco-config>

Le principe important consiste à conserver les configurations personnalisées dans les emplacements d’extension au lieu de modifier directement les fichiers fournis par Alfresco.

6. Surf Extension Modules

Pour de nombreuses personnalisations de Share, les Surf Extension Modules constituent une approche plus propre que la modification directe des ressources existantes.

Exemple conceptuel :


<extension>
    <modules>

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

            <customizations>

                <!-- Définitions des personnalisations -->

            </customizations>

        </module>

    </modules>
</extension>

Ces modules permettent de regrouper plusieurs extensions UI au sein d’un même ensemble cohérent.

Cette approche est particulièrement intéressante lorsqu’une entreprise doit gérer ses personnalisations sur plusieurs environnements :

DEV → SIT → UAT → Préproduction → Production

7. Les dashlets dans Alfresco Share

Un dashlet est un petit composant affiché sur un tableau de bord Alfresco.

Par exemple :

My Tasks ;
My Activities ;
Recently Modified Documents ;
Site Activities ;
rapports personnalisés ;
indicateurs métier.

Une entreprise pourrait par exemple créer :

Contrats expirant ce mois-ci

ou :

Contrats en attente d’approbation

Architecture typique d’un dashlet personnalisé


Descripteur
     ↓
Contrôleur
     ↓
Template FreeMarker
     ↓
CSS / JavaScript
     ↓
Repository / API

8. Création d’un Web Script Share simple

Les Web Scripts constituent des éléments importants dans le développement d’extensions Alfresco.

Un Web Script peut notamment utiliser :


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

Descripteur


<webscript>

    <shortname>Document Status</shortname>

    <description>
        Returns document status information
    </description>

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

    <format default="html"/>

    <authentication>user</authentication>

</webscript>

Contrôleur JavaScript


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

Template FreeMarker


<h2>${title}</h2>

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

Le composant d’interface peut ensuite afficher les données préparées par le contrôleur.

9. Repository Web Scripts vs Share Web Scripts

Cette distinction est importante.

Repository Web Script

Il s’exécute au niveau du Repository Alfresco et permet généralement de récupérer ou de traiter des informations du référentiel.


Client
   ↓
Repository Web Script
   ↓
Repository Services

Share Web Script

Il fonctionne dans la couche Share et se concentre principalement sur la présentation et le comportement de l’interface.


Navigateur
   ↓
Share Web Script
   ↓
Alfresco Share
   ↓
Repository API

Dans certaines personnalisations, Share peut appeler des Web Scripts Repository via son mécanisme de proxy.

10. Actions personnalisées dans la Document Library

Les actions de la Document Library constituent l’un des cas d’utilisation les plus intéressants de la personnalisation Share.

Imaginons que les utilisateurs aient besoin de l'action :

Send for Approval

sur certains documents.

Une action peut être configurée puis reliée à du JavaScript ou à une logique exécutée côté Repository.

Exemple conceptuel :


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

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

</action>

Une action personnalisée implique généralement :

Configuration → Visibilité → Icône → JavaScript → Evaluator → Opération Repository

11. Actions conditionnelles avec les Evaluators

Toutes les actions ne doivent pas nécessairement être accessibles à tous les utilisateurs ou à tous les documents.

Par exemple :

Approve Contract

pourrait être affichée uniquement lorsque :


Type du document = Contract
ET
Status = Pending Approval
ET
Utilisateur = autorisé

Les Evaluators permettent de contrôler l’affichage d'éléments de l’interface selon certaines conditions.

Attention cependant :

Masquer une action dans l’interface ne constitue pas un mécanisme de sécurité.

Les permissions doivent également être vérifiées côté serveur.

12. Personnalisation de l’affichage des métadonnées

Les installations Alfresco d’entreprise utilisent fréquemment des modèles de contenu personnalisés.

Par exemple :


acme:contract

avec les propriétés :


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

Share peut être configuré afin d’afficher ces propriétés dans ses formulaires et dans la Document Library.

Exemple conceptuel :


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

Cela permet d’intégrer directement les métadonnées métier à l’expérience utilisateur.

13. Personnalisation des widgets JavaScript

Certains besoins dépassent la simple configuration.

Il peut alors être nécessaire de modifier le comportement d’un widget Share existant.

La meilleure approche consiste généralement à étendre le comportement à l’aide des mécanismes d’extension supportés, plutôt qu’à copier et modifier directement le JavaScript fourni par Alfresco.

Cette stratégie facilite considérablement les futures mises à niveau.

14. Personnalisation CSS d’Alfresco Share

Le CSS personnalisé peut répondre à des besoins tels que :

identité visuelle de l’entreprise ;
styles de boutons ;
présentation du dashboard ;
polices ;
espacements ;
en-têtes ;
navigation.

Exemple :


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

Évitez de modifier directement les fichiers CSS originaux d’Alfresco.

Conservez vos styles dans votre propre extension afin qu’ils puissent être versionnés, testés et supprimés indépendamment du produit.

15. Packaging des personnalisations Share

Dans un environnement d’entreprise, les personnalisations doivent être considérées comme du code applicatif versionné et non comme de simples modifications manuelles effectuées sur les serveurs.

Une structure de projet peut ressembler à :


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

La structure exacte dépend de la version d’Alfresco, du SDK et de la méthode de packaging utilisée.

16. Processus de déploiement recommandé

Il est déconseillé de développer ou de modifier directement les personnalisations sur le serveur de Production.

Préférez un processus contrôlé :


Poste développeur
       ↓
Source Control
       ↓
Build
       ↓
DEV
       ↓
SIT
       ↓
UAT
       ↓
Préproduction
       ↓
Production

Chaque environnement doit recevoir le même artefact versionné.

17. Personnalisation Share compatible avec les mises à niveau

C’est un point essentiel dans les projets Alfresco d’entreprise.

À éviter


Modifier directement webapps/share
Remplacer les JAR Alfresco
Modifier le JavaScript standard
Modifier directement les templates FreeMarker d'origine
Effectuer des changements manuels non documentés

Ces approches augmentent fortement la dette technique.

À privilégier


Extension Modules
JAR personnalisés
Configuration personnalisée
Ressources CSS / JavaScript personnalisées
Web Scripts
Points d'extension supportés
Déploiement depuis le contrôle de source

Une bonne personnalisation doit pouvoir être :

installée → testée → mise à niveau → désactivée → supprimée

sans altérer définitivement le produit standard.

18. Problèmes fréquents de personnalisation Alfresco Share

Le module personnalisé n’apparaît pas

Vérifiez :

le déploiement ;
la configuration du module ;
les chemins des ressources ;
la syntaxe XML ;
les logs de l’application.

Les modifications JavaScript n’apparaissent pas

Vérifiez :

le cache du navigateur ;
les caches Share ;
les chemins des ressources ;
le chargement des fichiers ;
le déploiement de la bonne version.

Le dashlet n’est pas disponible

Vérifiez :

le descripteur du dashlet ;
l’enregistrement du Web Script ;
la configuration du composant ;
les noms des templates et contrôleurs ;
les logs serveur.

Un Web Script renvoie HTTP 404

Vérifiez son URL et son enregistrement.

Pour un Repository Web Script, assurez-vous également que le descripteur a correctement été détecté.

19. Considérations de performance

Un dashlet visuellement simple peut néanmoins exécuter des traitements coûteux.

Évitez par exemple qu’un chargement de dashboard déclenche systématiquement :


Requête Repository volumineuse
+
plusieurs appels REST
+
contrôles de permissions coûteux
+
réponse JSON volumineuse

Préférez :

des requêtes ciblées ;
la pagination ;
un cache approprié ;
le chargement asynchrone ;
des API Repository efficaces ;
un nombre limité de propriétés retournées ;
la suppression des appels inutiles.

Les tests de performance doivent utiliser des volumes représentatifs de la Production.

20. Sécurité des personnalisations Share

Une personnalisation Share ne doit jamais contourner la sécurité du Repository.

Vérifiez systématiquement :

Authentification — Qui effectue la requête ?

Autorisation — Cet utilisateur possède-t-il les droits nécessaires ?

Validation des entrées — Ne faites jamais confiance aveuglément aux données provenant du navigateur.

Encodage des sorties — Encodez correctement les valeurs contrôlées par les utilisateurs.

Permissions Repository — Les opérations métier doivent être protégées côté serveur.

Encore une fois :

un bouton masqué dans Share n’est pas une frontière de sécurité.

21. Comment choisir le bon mécanisme de personnalisation ?

Vous pouvez utiliser ce modèle de décision :


Besoin uniquement de configuration ?
        ↓
share-config-custom.xml

Nouvel élément d'interface ?
        ↓
Composant Surf / Dashlet

Nouvelle logique de présentation ?
        ↓
Share Web Script / Widget

Accès aux données Repository ?
        ↓
Repository API / Repository Web Script

Nouvelle fonctionnalité Document Library ?
        ↓
DocLib Extension + Action

Interface conditionnelle ?
        ↓
Evaluator

Choisir le mécanisme le plus simple répondant au besoin facilite la maintenance.

22. Exemple d’utilisation en entreprise

Imaginons un établissement financier utilisant Alfresco pour gérer des dossiers de prêt.

Le besoin est le suivant :

Afficher sur le tableau de bord tous les dossiers en attente d’un contrôle de conformité et permettre aux utilisateurs autorisés d’ouvrir directement les documents concernés.

Une architecture possible serait :


Dashlet Compliance personnalisé
          ↓
Share Web Script
          ↓
Repository API / Web Script
          ↓
Recherche des documents Pending Compliance
          ↓
Réponse JSON
          ↓
FreeMarker / JavaScript
          ↓
Dashboard utilisateur

Cette architecture combine plusieurs mécanismes de personnalisation sans nécessiter de modification directe du produit Alfresco.

23. Checklist de personnalisation Alfresco Share

Avant une mise en Production, vérifiez :

✅ Le code personnalisé est séparé du code Alfresco
✅ Les extensions sont placées sous contrôle de source
✅ Aucun fichier Share standard n’est directement modifié
✅ Les permissions sont contrôlées côté serveur
✅ Les ressources JavaScript et CSS se chargent correctement
✅ Les dashlets gèrent les erreurs et résultats vides
✅ Les appels Repository sont optimisés
✅ Les logs ne contiennent pas d’erreurs inattendues
✅ Les navigateurs supportés ont été testés
✅ La compatibilité avec les futures versions a été étudiée
✅ Les procédures de déploiement et de rollback sont documentées

Conclusion

Alfresco Share peut être étendu bien au-delà de son interface utilisateur standard.

Une bonne personnalisation ne dépend pas uniquement de connaissances en JavaScript ou XML. Il faut comprendre comment Share, Surf, les Web Scripts, les dashlets, les widgets, la configuration et les services Repository interagissent.

Pour les besoins simples, une modification de configuration peut suffire. Pour les fonctionnalités plus avancées, les Surf Extension Modules, dashlets personnalisés, extensions de la Document Library et Web Scripts offrent une architecture beaucoup plus puissante.

Dans un environnement d’entreprise, l’objectif principal doit rester de produire des personnalisations :

modulaires, versionnées, testables, sécurisées et compatibles avec les futures mises à niveau.

Cette approche réduit fortement les risques et les efforts nécessaires lors des futures migrations ou mises à niveau d’Alfresco.

📢 Besoin d’aide pour Java, workflows ou backend?

J’aide les équipes à concevoir des applications scalables, performantes et prêtes pour la production.

Services:

Développement Java & Spring Boot
Implémentation workflows (Camunda, Flowable – BPMN, DMN)
Intégrations API & microservices
ECM & gestion documentaire (Alfresco)
Optimisation performance & résolution incidents
🔗 https://shikhanirankari.blogspot.com/p/professional-services.html
📩 Email: ishikhanirankari@gmail.com | info@realtechnologiesindia.com
🌐 https://realtechnologiesindia.com
✔ Disponible pour consultation rapide
✔ Réponse sous 24 heures

🎥 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

Guide de personnalisation d’Alfresco Share : extensions UI, dashlets et configuration Surf

Ce que vous allez apprendre

1. Comprendre l’architecture d’Alfresco Share

2. Pourquoi personnaliser Alfresco Share ?

3. Principaux points d’extension d’Alfresco Share

4. Qu’est-ce que le framework Surf dans Alfresco ?

5. Configuration avec share-config-custom.xml

6. Surf Extension Modules

7. Les dashlets dans Alfresco Share

Architecture typique d’un dashlet personnalisé

8. Création d’un Web Script Share simple

Descripteur

Contrôleur JavaScript

Template FreeMarker

9. Repository Web Scripts vs Share Web Scripts

Repository Web Script

Share Web Script

10. Actions personnalisées dans la Document Library

11. Actions conditionnelles avec les Evaluators

12. Personnalisation de l’affichage des métadonnées

13. Personnalisation des widgets JavaScript

14. Personnalisation CSS d’Alfresco Share

15. Packaging des personnalisations Share

16. Processus de déploiement recommandé

17. Personnalisation Share compatible avec les mises à niveau

À éviter

À privilégier

18. Problèmes fréquents de personnalisation Alfresco Share

Le module personnalisé n’apparaît pas

Les modifications JavaScript n’apparaissent pas

Le dashlet n’est pas disponible

Un Web Script renvoie HTTP 404

19. Considérations de performance

20. Sécurité des personnalisations Share

21. Comment choisir le bon mécanisme de personnalisation ?

22. Exemple d’utilisation en entreprise

23. Checklist de personnalisation Alfresco Share

Conclusion

Articles recommandés

🎥 Learn IT with Shikha sur YouTube

📢 Besoin d’aide pour Java, workflows ou backend?

J’aide les équipes à concevoir des applications scalables, performantes et prêtes pour la production.

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