Your Alfresco custom theme deployed as AMP or ZIP file

Alfresco ShareIn the various posts of this personal blog, the development of a custom theme of the Alfresco Share front end, is one of the most relevant and accessed. In a past tutorial, I share a simple way to develop your own theme for the Alfresco v4.2.c distribution.

In this post I would like to reach them same goal, but with an important improvement: the release of the theme in an AMP file or a ZIP file. All using an automatic solution based on a Java project managed by Eclipse IDE and Apache ANT.

Prerequisites

To understand how this solution works, you should have confidence with Eclipse IDE, Java projects, Git, Apache ANT and of course Alfresco (in particular with the AMP format). If you don’t have confidence with all of those things, this use case could be a way to improve your skills but, please, refer to the official documentations to learn how to use them before trying to test the content of this post.

Alle the source code described in this post has been tested in a Ubuntu 12.04 LTS operating system with Alfresco Community Edition v4.2.f on board, installed as bundle distribution. All the content should be valid for all the Alfresco distributions of the v4.2 family, both Community and Enterprise.

The git project my-first-alfresco-theme (on GitHub)

githubIn the repository below, you will find a Git repository called ‘my-first-alfresco-theme’, developing a copy of the ‘Green theme’ contained in the Alfresco vanilla installation. The developed theme is called ‘Alfresco themes – My first theme’.

The first task to do is to import the project from the repository, using Eclipse IDE at the link below:

https://github.com/fcorti/my-first-alfresco-theme.git

If you are not confident on how to import a project from Git, please refer to the web with a huge amount of tutorials or documentations. 😉

Once the project has been imported with success in your Eclipse IDE, in the ‘build’ folder you will find the two packages containing the theme: one in AMP format (‘alfrescoThemes_myFirstTheme.amp’) and one in ZIP format (‘alfrescoThemes_myFirstTheme.zip’).

If you want to re-build the packages after customizations, the build file (‘build.xml’) into the ANT view, is what you need for that purpose. If you are not confident on how to build a project with Apache ANT, please refer to the web with a huge amount of tutorials or documentations. 😉

How to deploy the theme in AMP format

The deployment using the AMP format should be preferred to the ZIP format. Below the step by step description of the task.

  • Open a terminal and go to the folder where Alfresco is installed (for example ‘/opt/alfresco-4.2.f’ on a linux platform).
  • Stop Alfresco (for example ‘./alfresco.sh stop’ on a linux platform).
  • Copy the AMP file from the ‘build’ folder of the project in the ‘amps-share’ folder (if you use an Alfresco bundle installation).
  • Go to the ‘bin’ subfolder and run ‘apply_amps’ script.
  • Go back to the Alfresco installation folder and start Alfresco again (for example ‘./alfresco.sh start’ on a linux platform).
  • Once Alfresco is started, open a browser with Alfresco Share, login as administrator and access to ‘Admin tools’ item in the menu.
  • In ‘Applications’, change the theme to your custom theme.

alfrescoCustomTheme1_en

That’s all!

How to deploy the theme in ZIP format

The deployment using the AMP format should be preferred to the ZIP format. Below the step by step description of the task.

  • Open a terminal and go to the folder where Alfresco is installed (for example ‘/opt/alfresco-4.2.f’ on a linux platform).
  • Stop Alfresco (for example ‘./alfresco.sh stop’ on a linux platform).
  • Unzip the ZIP file from the ‘build’ folder, directly in the Alfresco installation folder (you can merge the folders/subfolders/files to correctly install the theme).
  • Start Alfresco again (for example ‘./alfresco.sh start’ on a linux platform).
  • Once Alfresco is started, open a browser with Alfresco Share, login as administrator and access to ‘Admin tools’ item in the menu.
  • In ‘Applications’, change the theme to your custom theme, exactly in the same way is described in the picture before.

That’s all!

Francesco Corti

 

Advertisements

How to customize the Alfresco Share 4.2.d header menu modifying the default

menuHeaderTitleFollowing the Dave Draper posts that describes the new header bar using the updated widget processing framework provided by Surf of the new Alfresco 4.2.d, I thought it could be useful to show how to modify the existing header without deploying again some custom source code.

We all are agree that modifying the native Alfresco source code is possible but discouraged, but my purpose is to show some tips, underling that the correct method is the “extension” that Dave well described in his article.

As usual, I’m going to show the content wit a practical example with a step by step approach to better understand and reproduce.

Prerequisites

All the description has been developed on a vanilla installation of Alfresco 4.2.d on a Ubuntu 12.04 LTS distribution. To know how to prepare the vanilla installation of Alfresco 4.2.d you can use the bundle installation or a more controlled installation described here.

Modifying the default header

Before starting to modify something, stop the Alfresco service running the command below from the Alfresco’s installation folder.

./alfresco.sh stop

Now that the Alfresco service is stopped, we can go ahead modifying the default’s header declaration. As you probably know, the Alfresco header management is radically changed starting from this new 4.2.d release and the default composition is stored directly in a javascript code instead of a configuration file. In particular, the javascript file we are talking about is:

<alfresco>/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/imports/share-header.lib.js

Let’s go ahead modifying the javascript with the command below. Of course you have to replace the ‘<alfresco>’ tag with the correct path depending on you environment/installation.

nano <alfresco>/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/imports/share-header.lib.js

Once the javascript is opened, find the ‘generateAppItems()’ function inside the code. In this function is declared the menubar definition in the ‘appItems’ variable using a JSON format. You can recognize all the items of the menubar that you can modify but in this post we are interested to add a new one: a new link to an external URL (in our example my blog at http://fcorti.com).

To add the new link is enough to append the code below immediately before the return command. In our case develop a dummy ‘if’ command useful if you want to control the visibility of the item with a condition.

...
if (true /* dummy condition */)
{
  appItems.push({ 
    id: "HEADER_ADMIN_CONSOLE", 
    name: "alfresco/menus/AlfMenuBarItem", 
    config: { 
      id: "HEADER_AAAR", 
      label: "header.menu.myItem.label", 
      targetUrl: "http://fcorti.com", 
      targetUrlType: "FULL_PATH", 
      targetUrlLocation: "NEW" 
    } 
  }); 
}
return appItems;
...

Using the ‘targetUrlType’ you can control the Alfresco’s relative or absolute path. Using the ‘targetUrlLocation’ you can control the opening of a new window or the link to the current browser’s window. In every case, omitting to specify the properties, you request for a relative path in the same window.

Defining the label internationalization

Last but not least we have to define the label for the new item. To reach that goal you can modify the file described below.

<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar.properties

The requested modification is simple because you can simply append the code below.

header.menu.myItem.label=myItem

Until now we have defined the label for the default value in all the languages but if you want to customize the value for your own language you have to repeat this definition for one or more of the property files listed below.

<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_de.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_es.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_fr.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_it.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_ja.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_nb_NO.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_nl.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_ru.properties
<alfresco>/tomcat/webapps/share/js/alfresco/header/i18n/AlfMenuBar_zh_CN.properties

Check the result

Now that we have developed all the necessary, we are ready to start again the alfresco service and check the result. You know for sure that to start Alfresco you have simply to execute the command below in a terminal.

./alfresco.sh start

Finally, your result should look like the screenshot below.

Alfresco Share 4.2.d header