16 Mar

Alfresco’s Aikau framework and configuration properties

menuHeaderTitleSince the release 4.2 Community Edition, the Alfresco’s Aikau framework has been introduced as a brand new method of creating new Surf Pages or Components for the so called Alfresco Share client. Since then, some exciting tutorials and examples have been developed (Ole Hejlskov’s tutorial is one of the most complete, in my personal opinion) and I also enjoyed with the development of the A.A.A.R. menu for Alfresco Share, available in this GitHub project and downloadable here.

In this post I would like to share my experience using the Alfresco’s configuration parameters directly into the Aikau framework to customize and control the widgets. In this particular case creating a structured menu item into the header of Alfresco Share, but this approach could be used in every javascript code developed using the Alfresco’s Aikau framework.

Description of the goal

In this particular scenario we are going to start from the example developed by Ole Hejlskov where he describes how to extend the Alfresco Share header with a brand new menu item. The extension described is about a static item but our goal here, is to develop it using the Alfresco properties stored into the share-config-custom.xml configuration file. The properties stored in the configuration file would drive the item creation and features and will make the whole solution more customizable, scalable… in few words: more closed to the reasons why Aikau has been developed. 😉

The basic example of a static item

Before going ahead I suggest you to take a look to the mentioned example but, if you are too lazy or busy to read it, below I copy the portion of the code that manage the creation of the static item into the Alfresco header.

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: "myItem",
                targetUrl: "user/" + encodeURIComponent(user.name) + "/profile"
            }
    });
}

All the magic is around the extension of the headerMenu.config.widgets object with a specific JSON easy to understand and define.

The Alfresco custom properties

Now that we know how to extend the Alfresco Share header, it’s time to define our own custom properties into the share-config-custom.xml configuration file, as described here. Again: if you are too lazy or busy to read it, below I copy the portion of the configuration file to define.

<alfresco-config>

 ...

 <!-- A.A.A.R. config section -->
 <config evaluator="string-compare" condition="AAAR" replace="true">

 <!-- Set to true or false to view the menu and/or credits. -->
 <visible>true</visible>
 <visible-credits>true</visible-credits>

 <!-- Link set of the dashboards. -->
 <dashboards>
  <link label="Main dashboard" icon-class="" target-url="http://localhost:8080/pentaho/api/repos/%3Apublic%3AAAAR%3Amain.wcdf/generatedContent" />

 ...

 </config>

</alfresco-config>

How to use the properties into the javascript source code

At this point the question is: how the custom properties could be used to customize the JSON of the extended widget? The answer will come easily, taking a look into the Alfresco source code. In particular into the share-header.get.js file. If you will study the javascript source code, you will see that all the properties contained into the share-config-custom.xml configuration file are available through the config.scoped object. In other words the config.scoped object is the javascript representation of the share-config-custom.xml file.

The config.scoped object

Some useful methods of the config.scoped object are very easy to use and make our goal very close. In particular I would like to share some features below.

  • config.scoped["AAAR"] is used to get the tag object defined into the configuration file. Exactly in the same way we would retrieve config.scoped["AAAR"]["visible"] or any other child of the XML structure.
  • attributes["label-id"] is used to get the attribute value defined into the configuration file.
  • The getValue method of a XML node retrieves the text of an XML configuration. For example config.scoped["AAAR"]["visible"].getValue() retrieves true in the specific case we define in this post.
  • The getChildren method of a XML node retrieves all the nodes children in a XML structure. For example config.scoped["AAAR"]["dashboards"].getChildren("link") retrieves all the children nodes of the link type for the dashboards tag.

The final source code

Now that we know about the config.scoped object, we can share the code that develops our goal. Below the portion of the code that defines the menu items described by the properties of the configuration files. For further details and a real life project, you can see here.

var headerMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_APP_MENU_BAR");

if (headerMenu != null) {

    var AAARMenu = {
        id: "HEADER_AAAR_DROPDOWN",
        name: "alfresco/header/AlfMenuBarPopup",
        config: {
            label: "A.A.A.R. Analytics",
            widgets: []
        }
    };

    if (config.scoped["AAAR"]["dashboards"]) {

        // Adding group item.
        var AAARMenuGroup = {
            name: "alfresco/menus/AlfMenuGroup",
            config: {
                label: "Dashboards",
                widgets: []
            }
        };

        for (var i = 0; i < config.scoped["AAAR"]["dashboards"].getChildren("link").size(); ++i) {

            var link = config.scoped["AAAR"]["dashboards"].getChildren("link").get(i);

            AAARMenuGroup.config.widgets.push({
                name: "alfresco/menus/AlfMenuBarItem",
                config: {
                    label: link.attributes["label"],
                    iconClass: link.attributes["icon-class"],
                    targetUrl: link.attributes["target-url"],
                    targetUrlType: "FULL_PATH",
                    targetUrlLocation: "NEW"
                }
            });
       }

        AAARMenu.config.widgets.push(AAARMenuGroup);
    }

    headerMenu.config.widgets.push(AAARMenu);

}

As you can see into the code, the JSON extension of the widget is generated dynamically from the  configuration informations, in particular from XML tags content and attributes. All of this to do exactly what we wanted in the declared goal.

Last but not least, below is shown an example of the menu item developed with this approach. Of course the image referrers to a more complete development you can find here, but nothing is different as approach from the strategy we discuss in this post.

AAAR_Alfresco_menu

Conclusion

In this post I share my experience using the Alfresco’s configuration parameters directly into the Aikau framework to customize and control the widgets. In this particular case the goal is to create a structured menu item of Alfresco Share header, but this approach could be used in every javascript code developed using the Alfresco’s Aikau framework.

 

One thought on “Alfresco’s Aikau framework and configuration properties

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.