Wednesday, June 9, 2010

Adding new Configurations in the Alfresco Share Admin Console

Alfresco Enterprise 3.3 is out now.  A release called 3.3FCS (First Customer Ship) is available for download now, and another version, and rumor that a 3.3G (community version. G for Google docs) should become available next week.  The Alfresco product feels more stable and complete with every release.  The 3.3 version comes with a lot of new features.  One of those new features is the ability to change the theme of Alfresco directly from the Administration Console.  (You're not able to define the theme via the UI, but you can select from a set of pre-defined themes and then apply them to immediately see their effects.)

The default configuration area available in the Admin Console are Groups, Users, and now with the 3.3 release, the Application (which currently only includes the theme).


From the image above you can see the five out-of-the-box themes that come standard with Alfresco 3.3.  And the image below shows you the rainbow of effects that you can get by applying these themes.


Maybe not too exciting, but one interesting thing about the addition of Themes to the Admin Console is that it serves as a fairly simple example of how the Administration Console was designed to be extensible, so that new components that require administration could be added to the Console.

Surprisingly not that much new code is needed for the addition of themes into the Admin Console.  Let's look at some of the files involved in the rest of this posting.

The files that define the themes can be found at this location:
We're not creating a new theme in this blog, but if you plan to make a custom new one, note that you should start by cloning the files from a theme other than the default one.  The default theme has access to assets that the other themes have local copies of.

webapps\share\WEB-INF\classes\alfresco\messages\slingshot.properties
This file contains the labels used in the left-side navigation area of the Administration Console.  We can see the definition for the label and description of the 'Application' Console configuration (along with similar definitions for users and groups).
## Admin console tools
tool.users.label=Users
tool.users.description=User Management
tool.groups.label=Groups
tool.groups.description=Group Management
tool.application.label=Application
tool.application.description=Application Settings and Management

webapps\share\WEB-INF\classes\alfresco\site-data\themes\default.xml
webapps\share\WEB-INF\classes\alfresco\site-data\themes\greenTheme.xml
webapps\share\WEB-INF\classes\alfresco\site-data\themes\gdocs.xml
webapps\share\WEB-INF\classes\alfresco\site-data\themes\yellowTheme.xml
webapps\share\WEB-INF\classes\alfresco\site-data\themes\hcBlack.xml

These files contain title and description data for each of the themes like this (from default.xml):
<?xml version='1.0' encoding='UTF-8'?>
<theme>
 <title>Default Blue Theme</title>
 <title-id>theme.default</title-id>
</theme>

Files to Render the Admin Console Theme Selector

application.get.desc.xml
<webscript>
  <shortname>Admin Console Application Tool</shortname>
  <description>Administration Console - Application Settings Tool</description>
  <url>/components/console/application</url>
  <family>admin-console</family>
</webscript>

application.get.head.ftl
<#include "../component.head.inc">
<!-- Admin Console Application Tool -->
<@link rel="stylesheet" type="text/css" href="${page.url.context}/components/console/application.css" />
<@script type="text/javascript" src="${page.url.context}/components/console/consoletool.js"></@script>
<@script type="text/javascript" src="${page.url.context}/components/console/application.js"></@script>

These files are included in application.get.head.ftl:
webapps\share\components\console\application.css
webapps\share\components\console\application.js


application.get.html.ftl
This file provides the actual layout markup for the Application Configuration in the Admin Console.
<!--[if IE]>
<iframe id="yui-history-iframe" src="${url.context}/yui/assets/blank.html"></iframe> 
<![endif]-->
<input id="yui-history-field" type="hidden" />

<script type="text/javascript">//<![CDATA[
   new Alfresco.ConsoleApplication("${args.htmlid}").setMessages(${messages});
//]]></script>

<#assign el=args.htmlid>
<div id="${el}-body" class="application">
   
   <!-- Options panel -->
   <div id="${el}-options" class="hidden">
      
      <form id="${el}-options-form" action="${url.context}/service/components/console/application" method="post">
         
         <div class="title">${msg("label.options")}</div>
         
         <div class="row">
            <span class="label">${msg("label.theme")}:</span>
            <div class="flat-button">
               <select id="console-options-theme-menu">
                  <#list themes as t>
                  <option value="${t.id}"<#if t.selected> selected="selected"</#if>>${t.title?html}</option>
                  </#list>
               </select>
            </div>
         </div>
         
         <div class="buttons">
            <button id="${el}-apply-button" name="apply">${msg("button.apply")}</button>
         </div>
      
      </form>
   </div>

</div>

application.get.js
This small server side javascript file  makes use of the Surf/Share sitedata root object that is described here to find the available themes.  The code here finds the available themes and collects and stores them into the model for later display.
function main()
{
   model.themes = [];
   
   // retrieve the available theme objects
   var themes = sitedata.getObjects("theme");
   for (var i=0, t; i<themes.length; i++)
   {
      t = themes[i];
      model.themes.push(
      {
         id: t.id,
         title: t.title,
         // current theme ID is in the default model for a script
         selected: (t.id == theme)
      });
   }
}

main();

application.get.properties
This file defines labels that appear on the Application configuration page.
label.options=Options
label.theme=Theme
button.apply=Apply
message.failure=Failed to apply selected options.


Files to Set the New Theme  

Once the "Apply button is selected, the new theme (and later potentially other Application data) data is posted back to the server.

application.post.desc.xml
<webscript>
  <shortname>Admin Console Application Tool POST</shortname>
  <description>Admin Console Application Tool POST form submission processing</description>
  <format default="json" />
  <url>/components/console/application</url>
</webscript>

application.post.json.ftl
{
   "success": ${success?string},
   "message": "<#if errormsg??>${errormsg}</#if>"
}

application.post.json.js
This function marks the newly selected theme and sets it.
function main()
{
   var themeId = json.get("console-options-theme-menu");
   context.setThemeId(new String(themeId));
   
   // persist across Share application if this is the admin user
   if (user.isAdmin)
   {
      var sc = context.getSiteConfiguration();
      sc.setProperty("theme", themeId);
      sc.save();
   }
   
   model.success = true;
}

main();