Customizing the Share Header (Part 3)

[ddraper]

Introduction

In the first two posts in this series I've focused on how to add or modify items in the new Alfresco Share header bar and in this post I'm going to focus on how to hide items.

This will be demonstrated in two different ways:

• Using a built-in helper function
• Through configuration exposed by the 'alfresco/header/AlfSitesMenu' widget.

To get the most out of this post you should ideally read the previous two entries in the series as the first provides detailed information on creating a JAR file for your extension and the second provides some useful information on the 'Sites' drop-down menu.

The examples described in this post can be downloaded as a JAR file from here.

Removing Menu Items

After we released Alfresco Community 4.2.d it was very quickly noticed by observant community members that whilst there was a built-in helper method for finding widget entries that was helpful when adding or changing entries, it didn't actually help with removing entries.

To resolve this issue we have introduced the 'widgetUtils.deleteObjectFromArray' helper function. Unfortunately this helper method is NOT available in Alfresco Community 4.2.d but will be available in the Alfresco Community 4.2.e and in Alfresco Enterprise 4.2 releases (...but you can always try it out in the nightly builds!).

The function is very simple to use. It takes 3 arguments:

1. The object to remove the widget definition from (you can typically just use 'model.jsonModel')
2. The attribute to search for (you should use 'id')
3. The value to match against the target attribute (the 'id' attribute of the widget definition to remove)

So for example to remove the 'My Files' link from the menu bar you would need to include the following code in your 'share-header.get.js' extension:

widgetUtils.deleteObjectFromArray(model.jsonModel, 'id', 'HEADER_MY_FILES'); ‍

Before the module is deployed the header is as follows:

...and after the module is deployed the link has disappeared:

This is obviously a very simple example and you can add finer grained control through JavaScript in the controller extension, e.g:

if (!user.isAdmin)
{
  widgetUtils.deleteObjectFromArray(model.jsonModel, 'id', 'HEADER_MY_FILES');
}‍‍‍‍

...that would hide the 'My Files' link if the user isn't the Admin, or by deploying the Module with an evaluator (which pretty much allows you complete control over when the module is applied).

Customizing the Sites Drop Down Menu

The topic of hiding specific items from the Sites menu was raised on the Alfresco forums and I was embarrassed to discover that I'd not provided adequate configuration for toggling what is displayed (e.g. 'Recent Sites', 'Favorites', 'Site Finder', etc) so I made some updates which unfortunately were also done after Alfresco Community 4.2.d release.

One of the goals for the Alfresco widget library is that the widgets are either completely atomic and can be added and removed without causing errors (although clearly removing widgets can change functionality) and that where a widget encapsulates child widgets it provides configuration for them.

The 'alfresco/header/AlfSitesMenu' falls into this latter category (as described in the last post) so it was important to add that missing configuration. The following boolean attributes have been added:

• 'showCreateSite' (controls whether or not the 'Create Site' menu item is displayed)
• 'showSiteFinder' (controls whether or not the 'Site Finder' menu item is displayed)
• 'showUsefulGroup' (controls whether or not the entire 'Useful' group is displayed - will override 'showCreateSite', 'showSiteFinder' and 'showFavourites')
• 'showRecentSites' (controls whether or not the 'Recent Sites' group is displayed)
• 'showFavourites' (controls whether or not the 'Favorites' and favourite controls, e.g. add/remove, are displayed)

So to make use of these attributes you can create a extension to 'share-header.get.js' as follows:

// Find the 'Sites' menu...
var sitesMenu = widgetUtils.findObject(model.jsonModel, 'id', 'HEADER_SITES_MENU');
if (sitesMenu != null)
{
  // Hide the site finder...
  sitesMenu.config.showSiteFinder = false;
}
‍‍‍‍‍‍‍

Before the module is deployed the 'Sites' menu appears as:

...and after the module is deployed it appears as:

The Importance of the Community

It's a shame that neither of these examples can be applied to Alfresco Community 4.2.d but it does highlight the powerful symbiotic nature of the community. As a company Alfresco (and ergo its Engineering team) has to prioritise it's customers but where possible we do listen to our open-source community and strive to respond to it's needs.

One of the biggest challenges when working on the extensibility features in Share and Surf is identifying the real world use cases that they will be required for. The more input we receive the better the product will become and if it is missing a feature then we will try our best to deliver it.

Summary

Hopefully this series of posts has provided enough information for you to start creating extensions to dynamically customize the new header menu. The header and it's implementation are new for Alfresco and its understandable that there it will take time to adapt. I'll be writing more posts over the coming weeks and months that provide more information on the recent changes with more examples on how to customize Alfresco Share. I'm also going to be covering the framework updates in detail at Alfresco Summit in November.

Finally, if you have any ideas for topics that you'd like me to blog about then please feel free to add sub-tasks to this JIRA issue. I can't guarantee that I'll definitely write up your suggestion but I will endeavour to cover as many as I can... and if nothing else, your suggestions will help us to understand where the pain points are for customizing Alfresco Share.